adds cursor control ANSI escape codes

doc/specs/stdlib_ansi_cursor.md

@@ -0,0 +1,235 @@
+---
+title: ansi_cursor
+---
+
+# The `stdlib_ansi_cursor` module
+
+[TOC]
+
+## Introduction
+
+Module for cursor control using ansi terminal escape sequences
+
+## Constants provided by `stdlib_ascii`
+
+### ``esc``
+
+The ESC character
+
+
+### ``home``
+
+ansi escape code to move the cursor to it's home coordinates `(0,0)`
+
+
+### ``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(0, 0) ! Same as printing the constant `home`
+    read (*,*), input  ! Waiting for input to actually see the effect of the `move_to` function
+end program test
+```
+
+
+### `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
+

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

src/stdlib_ansi_cursor.f90

@@ -0,0 +1,132 @@
+module stdlib_ansi_cursor
+    use stdlib_strings, only: to_string
+    implicit none
+
+    private
+
+    public :: move_to, move_up, move_down, move_left, move_right, move_to_column
+    public :: esc, home, clear_till_screen_end, clear_till_screen_start, clear_completely, &
+        & clear_till_line_end, clear_till_line_start, clear_entire_line
+
+    !> the ESC character
+    character(len=*), parameter :: esc = achar(27)
+    !> moves the cursor to home => `(0,0)`
+    character(len=*), parameter :: home = esc//"[H"
+    !> erases from the cursor till the end of the screen
+    character(len=*), parameter :: clear_till_screen_end = esc//"[0J"
+    !> erases from the cursor to the beginning of the screen
+    character(len=*), parameter :: clear_till_screen_start = esc//"[1J"
+    !> erases the entire screen
+    character(len=*), parameter :: clear_completely = esc//"[2J"
+    !> erases from the cursor till the end of line
+    character(len=*), parameter :: clear_till_line_end = esc//"[0K"
+    !> erases from the cursor till the beginning of the line
+    character(len=*), parameter :: clear_till_line_start = esc//"[1K"
+    !> erases the entire line
+    character(len=*), parameter :: clear_entire_line = esc//"[2K"
+
+contains
+    !> Version: Experimental
+    !>
+    !> moves the cursor to `(line, column)`
+    !> returns an empty string if any of them is negative
+    !> [Specification](../page/specs/stdlib_ansi_cursor.html#move_to)
+    pure function move_to(line, col) result(str)
+        integer, intent(in) :: line
+        integer, intent(in) :: col
+        character(:), allocatable :: str
+
+        if (line < 0 .or. col < 0) then
+            str = ""
+        else
+            str = esc//"["//to_string(line)//";"//to_string(col)//"H"
+        end if
+
+    end function move_to
+
+    !> Version: Experimental
+    !>
+    !> moves the cursor to column `col`
+    !> returns an empty string if `col` is negative
+    !> [Specification](../page/specs/stdlib_ansi_cursor.html#move_to_column)
+    pure function move_to_column(col) result(str)
+        integer, intent(in) :: col
+        character(:), allocatable :: str
+
+        if (col < 0) then
+            str = ""
+        else
+            str = esc//"["//to_string(col)//"G"
+        end if
+
+    end function move_to_column
+
+    !> Version: Experimental
+    !>
+    !> moves the cursor up by `line` lines
+    !> returns an empty string if `line` is negative
+    !> [Specification](../page/specs/stdlib_ansi_cursor.html#move_up)
+    pure function move_up(line) result(str)
+        integer, intent(in) :: line
+        character(:), allocatable :: str
+
+        if (line <= 0) then
+            str = ""
+        else
+            str = esc//"["//to_string(line)//"A"
+        end if
+
+    end function move_up
+
+    !> Version: Experimental
+    !>
+    !> moves the cursor down by `line` lines
+    !> returns an empty string if `line` is negative
+    !> [Specification](../page/specs/stdlib_ansi_cursor.html#move_down)
+    pure function move_down(line) result(str)
+        integer, intent(in) :: line
+        character(:), allocatable :: str
+
+        if (line <= 0) then
+            str = ""
+        else
+            str = esc//"["//to_string(line)//"B"
+        end if
+
+    end function move_down
+
+    !> Version: Experimental
+    !>
+    !> moves the cursor right by `line` lines
+    !> returns an empty string if `line` is negative
+    !> [Specification](../page/specs/stdlib_ansi_cursor.html#move_right)
+    pure function move_right(col) result(str)
+        integer, intent(in) :: col
+        character(:), allocatable :: str
+
+        if (col <= 0) then
+            str = ""
+        else
+            str = esc//"["//to_string(col)//"C"
+        end if
+
+    end function move_right
+
+    !> Version: Experimental
+    !>
+    !> moves the cursor left by `line` lines
+    !> returns an empty string if `line` is negative
+    !> [Specification](../page/specs/stdlib_ansi_cursor.html#move_left)
+    pure function move_left(col) result(str)
+        integer, intent(in) :: col
+        character(:), allocatable :: str
+
+        if (col <= 0) then
+            str = ""
+        else
+            str = esc//"["//to_string(col)//"D"
+        end if
+
+    end function move_left
+
+end module stdlib_ansi_cursor

test/terminal/CMakeLists.txt

@@ -1 +1,2 @@
 ADDTEST(colors)
+ADDTEST(ansi_cursor)