fixed typo, added specs for stdlib_ansi_cursor, added helpful error messages to tests, small fixes

Author: wassup05

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/stdlib_ansi_cursor.f90

@@ -2,11 +2,18 @@ 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//"[OJ"
+ 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
@@ -19,8 +26,11 @@ module stdlib_ansi_cursor
  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
@@ -34,8 +44,11 @@ pure function move_to(line, col) result(str)
 
  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
@@ -48,8 +61,11 @@ pure function move_to_column(col) result(str)
 
  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
@@ -62,8 +78,11 @@ pure function move_up(line) result(str)
 
  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
@@ -76,30 +95,36 @@ pure function move_down(line) result(str)
 
  end function move_down
 
+ !> Version: Experimental
+ !>
  !> moves the cursor right by `line` lines
  !> returns an empty string if `line` is negative
- pure function move_right(line) result(str)
- integer, intent(in) :: line
+ !> [Specification](../page/specs/stdlib_ansi_cursor.html#move_right)
+ pure function move_right(col) result(str)
+ integer, intent(in) :: col
  character(:), allocatable :: str
 
- if (line <= 0) then
+ if (col <= 0) then
  str = ""
  else
- str = esc//"["//to_string(line)//"C"
+ 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
- pure function move_left(line) result(str)
- integer, intent(in) :: line
+ !> [Specification](../page/specs/stdlib_ansi_cursor.html#move_left)
+ pure function move_left(col) result(str)
+ integer, intent(in) :: col
  character(:), allocatable :: str
 
- if (line <= 0) then
+ if (col <= 0) then
  str = ""
  else
- str = esc//"["//to_string(line)//"D"
+ str = esc//"["//to_string(col)//"D"
  end if
 
  end function move_left