adds cursor control ANSI escape codes

doc/specs/stdlib_ansi_cursor.md

@@ -0,0 +1,241 @@
+---
+title: ansi_cursor
+---
+
+# The `stdlib_ansi_cursor` module
+
+[TOC]
+
+## Introduction
+
+Module for cursor control using ansi terminal escape sequences
+
+## Constants provided by `stdlib_ansi_cursor`
+
+### ``esc``
+
+The ESC character
+
+
+### ``home``
+
+ansi escape code to move the cursor to it's home coordinates `(1,1)`
+
+
+### ``clear_till_screen_start``
+
+ansi escape code to clear the screen till the start of the terminal
+
+
+### ``clear_till_screen_end``
+
+ansi escape code to clear the screen till the end of the terminal
+
+
+### ``clear_completetely``
+
+ansi escape code to clear the terminal screen completely
+
+
+### ``clear_till_line_end``
+
+ansi escape code to clear till the current line end
+
+
+### ``clear_till_line_start``
+
+ansi escape code to clear till the current line start
+
+
+### ``clear_entire_line``
+
+ansi escape code to clear the entire line
+
+
+
+## Procedures and methods provided
+
+
+### `move_to`
+
+#### Status
+
+Experimental
+
+#### Description
+
+moves the cursor to the specified `line` and `column`
+
+#### Syntax
+
+`code =` [[stdlib_ansi_cursor(module):move_to(function)]] `(line, col)`
+
+#### Class
+
+Pure function.
+
+#### Arguments
+
+`line`: line (row) number to move it to 
+
+`col`: col (column) number to move it to
+
+#### Return value
+
+a default character string
+
+#### Examples
+
+```fortran
+program test
+    use stdlib_ansi_cursor, only: move_to
+    implicit none
+
+    character(len=1) :: input
+
+    print *, move_to(1, 1) ! Same as printing the constant `home`
+    read (*,*), input  ! Waiting for input to actually see the effect of the `move_to` function
+end program test
+```
+
+A more detailed example of drawing a blue box in a terminal
+
+```fortran
+{!example/terminal/example_ansi_cursor.f90!}
+```
+
+
+### `move_to_column`
+
+#### Status
+
+Experimental
+
+#### Description
+
+moves the cursor to the specified `column`
+
+#### Syntax
+
+`code =` [[stdlib_ansi_cursor(module):move_to_column(function)]] `(col)`
+
+#### Class
+
+Pure function.
+
+#### Arguments
+
+`col`: col (column) number to move it to
+
+#### Return value
+
+a default character string
+
+
+### `move_up`
+
+#### Status
+
+Experimental
+
+#### Description
+
+moves the cursor up by `line` lines
+
+#### Syntax
+
+`code =` [[stdlib_ansi_cursor(module):move_up(function)]] `(line)`
+
+#### Class
+
+Pure function.
+
+#### Arguments
+
+`line`: number of lines to move it above by
+
+#### Return value
+
+a default character string
+
+
+### `move_down`
+
+#### Status
+
+Experimental
+
+#### Description
+
+moves the cursor down by `line` lines
+
+#### Syntax
+
+`code =` [[stdlib_ansi_cursor(module):move_down(function)]] `(line)`
+
+#### Class
+
+Pure function.
+
+#### Arguments
+
+`line`: number of lines to move it below by
+
+#### Return value
+
+a default character string
+
+
+### `move_left`
+
+#### Status
+
+Experimental
+
+#### Description
+
+moves the cursor to the left by `col` columns
+
+#### Syntax
+
+`code =` [[stdlib_ansi_cursor(module):move_left(function)]] `(col)`
+
+#### Class
+
+Pure function.
+
+#### Arguments
+
+`col`: number of columns to move the cursor to the left by
+
+#### Return value
+
+a default character string
+
+
+### `move_right`
+
+#### Status
+
+Experimental
+
+#### Description
+
+moves the cursor to the right by `col` columns
+
+#### Syntax
+
+`code =` [[stdlib_ansi_cursor(module):move_right(function)]] `(col)`
+
+#### Class
+
+Pure function.
+
+#### Arguments
+
+`col`: number of columns to move the cursor to the right by
+
+#### Return value
+
+a default character string
+

example/CMakeLists.txt

@@ -31,3 +31,4 @@ add_subdirectory(stringlist_type)
 add_subdirectory(strings)
 add_subdirectory(string_type)
 add_subdirectory(version)
+add_subdirectory(terminal)

example/terminal/CMakeLists.txt

@@ -0,0 +1 @@
+ADD_EXAMPLE(ansi_cursor)

example/terminal/example_ansi_cursor.f90

@@ -0,0 +1,36 @@
+program ansi_cursor
+    use stdlib_ansi_cursor, only: move_to, clear_completely
+    use stdlib_ansi, only: fg_color_blue, to_string
+    implicit none
+
+    character(len=1) :: input
+    character(len=*), parameter :: delim = "#"
+
+    print *, clear_completely
+    print *, to_string(fg_color_blue) ! The box will be blue now
+
+    call draw_box(10, 38, 77, 17, delim)
+
+    ! read *, input                   ! Waiting for input to actually see the box drawn
+
+contains
+    !> Draws a box on the terminal of `width` width and `height` height
+    !> The topmost left vertex of the box is at `(line,col)`
+    subroutine draw_box(line, col, width, height, char)
+        integer, intent(in) :: line, col, width, height
+        character(len=1), intent(in) :: char
+        integer :: i
+
+        do i = 0, width - 1
+            write (*, "(a,a)", advance="NO") move_to(line, col + i), char
+            write (*, "(a,a)", advance="NO") move_to(line + height - 1, col + i), char
+        end do
+
+        do i = 0, height - 1
+            write (*, "(a,a)", advance="NO") move_to(line + i, col), char
+            write (*, "(a,a)", advance="NO") move_to(line + i, col + width - 1), char
+        end do
+
+    end subroutine draw_box
+
+end program ansi_cursor

src/CMakeLists.txt

@@ -28,13 +28,13 @@ set(fppFiles
     stdlib_linalg_kronecker.fypp
     stdlib_linalg_cross_product.fypp
     stdlib_linalg_eigenvalues.fypp
-    stdlib_linalg_solve.fypp    
+    stdlib_linalg_solve.fypp
     stdlib_linalg_determinant.fypp
     stdlib_linalg_qr.fypp
     stdlib_linalg_inverse.fypp
     stdlib_linalg_norms.fypp
     stdlib_linalg_state.fypp
-    stdlib_linalg_svd.fypp 
+    stdlib_linalg_svd.fypp
     stdlib_linalg_cholesky.fypp
     stdlib_optval.fypp
     stdlib_selection.fypp
@@ -108,6 +108,7 @@ set(SRC
     stdlib_ansi.f90
     stdlib_ansi_operator.f90
     stdlib_ansi_to_string.f90
+    stdlib_ansi_cursor.f90
     stdlib_array.f90
     stdlib_codata.f90
     stdlib_error.f90