readline: add missing documentation, fix documentation format, add README.md (#7683)

vlib/readline/README.md

@@ -0,0 +1,20 @@
+# Readline
+
+The `readline` module let you await and read user input
+from a terminal in an easy and structured manner.
+
+The module provides an easy way to prompt the user for
+questions or even make a REPL or an embedded console.
+
+Use `readline.Readline` if you want to include more
+advanced features such as history or simply use
+`readline.read_line('Please confirm (y/n):')` directly
+for one-off user interactions.
+
+# Usage
+
+```v ignore
+import readline { Readline }
+
+Readline.read_line('Continue?: (y/n)')
+```

vlib/readline/readline.v

@@ -1,25 +1,23 @@
 // Copyright (c) 2019-2020 Alexander Medvednikov. All rights reserved.
 // Use of this source code is governed by an MIT license
 // that can be found in the LICENSE file.
-
+//
-// Will serve as more advanced input method
+// Serves as a more advanced input method
-// Based on the work of https://github.com/AmokHuginnsson/replxx
+// based on the work of https://github.com/AmokHuginnsson/replxx
-
+//
 module readline
 
-// Linux
+// Termios stores the terminal options on Linux.
-// Used to change the terminal options
 struct Termios {
 mut:
 	c_iflag int
 	c_oflag int
 	c_cflag int
 	c_lflag int
-  c_cc [12]int //NCCS == 12. Cant use the defined value here
+	c_cc    [12]int // NCCS == 12. Can't use the defined value here
 }
 
-// Linux
+// Winsize stores the screen information on Linux.
-// Used to collect the screen information
 struct Winsize {
 	ws_row    u16
 	ws_col    u16
@@ -27,6 +25,8 @@ struct Winsize {
 	ws_ypixel u16
 }
 
+// Readline is the key struct for reading and holding user input via a terminal.
+// Example: import readline { Readline }
 pub struct Readline {
 mut:
 	is_raw            bool
@@ -41,3 +41,17 @@ mut:
 	search_index      int
 	is_tty            bool
 }
+
+// get_prompt_offset computes the length of the `prompt` `string` argument.
+fn get_prompt_offset(prompt string) int {
+	mut len := 0
+	for i := 0; i < prompt.len; i++ {
+		if prompt[i] == `\e` {
+			for ; i < prompt.len && prompt[i] != `m`; i++ {
+			}
+		} else {
+			len = len + 1
+		}
+	}
+	return prompt.len - len
+}

vlib/readline/readline_default.c.v

@@ -1,20 +1,26 @@
 // Copyright (c) 2019-2020 Alexander Medvednikov. All rights reserved.
 // Use of this source code is governed by an MIT license
 // that can be found in the LICENSE file.
-
+//
-// Mac version
+// TODO Mac version needs to be implemented
-// Need to be implemented
 // Will serve as more advanced input method
-// Based on the work of https://github.com/AmokHuginnsson/replxx
+// based on the work of https://github.com/AmokHuginnsson/replxx
-
+//
 module readline
 
 import os
 
 #include <termios.h>
-
 // Only use standard os.get_line
 // Need implementation for readline capabilities
+//
+// read_line_utf8 blocks execution in a loop and awaits user input
+// characters from a terminal until `EOF` or `Enter` key is encountered
+// in the input stream.
+// read_line_utf8 returns the complete input line as an UTF-8 encoded `ustring` or
+// an error if the line is empty.
+// The `prompt` `string` is output as a prefix text for the input capturing.
+// read_line_utf8 is the main method of the `readline` module and `Readline` struct.
 pub fn (mut r Readline) read_line_utf8(prompt string) ?ustring {
 	r.current = ''.ustring()
 	r.cursor = 0
@@ -23,14 +29,11 @@ pub fn (mut r Readline) read_line_utf8(prompt string) ?ustring {
 	if r.previous_lines.len <= 1 {
 		r.previous_lines << ''.ustring()
 		r.previous_lines << ''.ustring()
-  }
+	} else {
-  else {
 		r.previous_lines[0] = ''.ustring()
 	}
-
 	print(r.prompt)
 	line := os.get_raw_line()
-
 	if line.len >= 0 {
 		r.current = line.ustring()
 	}
@@ -42,22 +45,32 @@ pub fn (mut r Readline) read_line_utf8(prompt string) ?ustring {
 	return r.current
 }
 
-// Returns the string from the utf8 ustring
+// read_line does the same as `read_line_utf8` but returns user input as a `string`.
+// (As opposed to `ustring` returned by `read_line_utf8`).
 pub fn (mut r Readline) read_line(prompt string) ?string {
 	s := r.read_line_utf8(prompt) ?
 	return s.s
 }
 
-// Standalone function without persistent functionnalities (eg: history)
+// read_line_utf8 blocks execution in a loop and awaits user input
-// Returns utf8 based ustring
+// characters from a terminal until `EOF` or `Enter` key is encountered
+// in the input stream.
+// read_line_utf8 returns the complete input line as an UTF-8 encoded `ustring` or
+// an error if the line is empty.
+// The `prompt` `string` is output as a prefix text for the input capturing.
+// read_line_utf8 is the main method of the `readline` module and `Readline` struct.
+// NOTE that this version of `read_line_utf8` is a standalone function without
+// persistent functionalities (e.g. history).
 pub fn read_line_utf8(prompt string) ?ustring {
 	mut r := Readline{}
 	s := r.read_line_utf8(prompt) ?
 	return s
 }
 
-// Standalone function without persistent functionnalities (eg: history)
+// read_line does the same as `read_line_utf8` but returns user input as a `string`.
-// Return string from utf8 ustring
+// (As opposed to `ustring` as returned by `read_line_utf8`).
+// NOTE that this version of `read_line` is a standalone function without
+// persistent functionalities (e.g. history).
 pub fn read_line(prompt string) ?string {
 	mut r := Readline{}
 	s := r.read_line(prompt) ?

vlib/readline/readline_linux.c.v

@@ -1,9 +1,10 @@
 // Copyright (c) 2019-2020 Alexander Medvednikov. All rights reserved.
 // Use of this source code is governed by an MIT license
 // that can be found in the LICENSE file.
-// Linux version
+//
-// Will serve as more advanced input method
+// Serves as more advanced input method
-// Based on the work of https://github.com/AmokHuginnsson/replxx
+// based on the work of https://github.com/AmokHuginnsson/replxx
+//
 module readline
 
 import term
@@ -11,7 +12,15 @@ import os
 
 #include <termios.h>
 #include <sys/ioctl.h>
-// Defines actions to execute
+fn C.tcgetattr() int
+
+fn C.tcsetattr() int
+
+fn C.raise()
+
+fn C.getppid() int
+
+// Action defines what actions to be executed.
 enum Action {
 	eof
 	nothing
@@ -32,17 +41,10 @@ enum Action {
 	suspend
 }
 
-fn C.tcgetattr() int
+// enable_raw_mode enables the raw mode of the terminal.
-
+// In raw mode all key presses are directly sent to the program and no interpretation is done.
-fn C.tcsetattr() int
+// Please note that `enable_raw_mode` catches the `SIGUSER` (CTRL + C) signal.
-
+// For a method that does please see `enable_raw_mode_nosig`.
-fn C.raise()
-
-fn C.getppid() int
-
-// Enable the raw mode of the terminal
-// In raw mode all keypresses are directly sent to the program and no interpretation is done
-// Catches the SIGUSER (CTRL+C) Signal
 pub fn (mut r Readline) enable_raw_mode() {
 	if C.tcgetattr(0, &r.orig_termios) == -1 {
 		r.is_tty = false
@@ -60,8 +62,10 @@ pub fn (mut r Readline) enable_raw_mode() {
 	r.is_tty = true
 }
 
-// Enable the raw mode of the terminal
+// enable_raw_mode_nosig enables the raw mode of the terminal.
-// Does not catch the SIGUSER (CTRL+C) Signal
+// In raw mode all key presses are directly sent to the program and no interpretation is done.
+// Please note that `enable_raw_mode_nosig` does not catch the `SIGUSER` (CTRL + C) signal
+// as opposed to `enable_raw_mode`.
 pub fn (mut r Readline) enable_raw_mode_nosig() {
 	if C.tcgetattr(0, &r.orig_termios) == -1 {
 		r.is_tty = false
@@ -79,7 +83,8 @@ pub fn (mut r Readline) enable_raw_mode_nosig() {
 	r.is_tty = true
 }
 
-// Disable the raw mode of the terminal
+// disable_raw_mode disables the raw mode of the terminal.
+// For a description of raw mode please see the `enable_raw_mode` method.
 pub fn (mut r Readline) disable_raw_mode() {
 	if r.is_raw {
 		C.tcsetattr(0, C.TCSADRAIN, &r.orig_termios)
@@ -87,15 +92,18 @@ pub fn (mut r Readline) disable_raw_mode() {
 	}
 }
 
-// Read a single char
+// read_char reads a single character.
 pub fn (r Readline) read_char() int {
 	return utf8_getchar()
 }
 
-// Main function of the readline module
+// read_line_utf8 blocks execution in a loop and awaits user input
-// Will loop and ingest characters until EOF or Enter
+// characters from a terminal until `EOF` or `Enter` key is encountered
-// Returns the completed line as utf8 ustring
+// in the input stream.
-// Will return an error if line is empty
+// read_line_utf8 returns the complete input line as an UTF-8 encoded `ustring` or
+// an error if the line is empty.
+// The `prompt` `string` is output as a prefix text for the input capturing.
+// read_line_utf8 is the main method of the `readline` module and `Readline` struct.
 pub fn (mut r Readline) read_line_utf8(prompt string) ?ustring {
 	r.current = ''.ustring()
 	r.cursor = 0
@@ -129,41 +137,39 @@ pub fn (mut r Readline) read_line_utf8(prompt string) ?ustring {
 	return r.current
 }
 
-// Returns the string from the utf8 ustring
+// read_line does the same as `read_line_utf8` but returns user input as a `string`.
+// (As opposed to `ustring` returned by `read_line_utf8`).
 pub fn (mut r Readline) read_line(prompt string) ?string {
 	s := r.read_line_utf8(prompt) ?
 	return s.s
 }
 
-// Standalone function without persistent functionnalities (eg: history)
+// read_line_utf8 blocks execution in a loop and awaits user input
-// Returns utf8 based ustring
+// characters from a terminal until `EOF` or `Enter` key is encountered
+// in the input stream.
+// read_line_utf8 returns the complete input line as an UTF-8 encoded `ustring` or
+// an error if the line is empty.
+// The `prompt` `string` is output as a prefix text for the input capturing.
+// read_line_utf8 is the main method of the `readline` module and `Readline` struct.
+// NOTE that this version of `read_line_utf8` is a standalone function without
+// persistent functionalities (e.g. history).
 pub fn read_line_utf8(prompt string) ?ustring {
 	mut r := Readline{}
 	s := r.read_line_utf8(prompt) ?
 	return s
 }
 
-// Standalone function without persistent functionnalities (eg: history)
+// read_line does the same as `read_line_utf8` but returns user input as a `string`.
-// Return string from utf8 ustring
+// (As opposed to `ustring` as returned by `read_line_utf8`).
+// NOTE that this version of `read_line` is a standalone function without
+// persistent functionalities (e.g. history).
 pub fn read_line(prompt string) ?string {
 	mut r := Readline{}
 	s := r.read_line(prompt) ?
 	return s
 }
 
-fn get_prompt_offset(prompt string) int {
+// analyse returns an `Action` based on the type of input byte given in `c`.
-	mut len := 0
-	for i := 0; i < prompt.len; i++ {
-		if prompt[i] == `\e` {
-			for ; i < prompt.len && prompt[i] != `m`; i++ {
-			}
-		} else {
-			len = len + 1
-		}
-	}
-	return prompt.len - len
-}
-
 fn (r Readline) analyse(c int) Action {
 	match byte(c) {
 		`\0`, 0x3, 0x4, 255 { return .eof } // NUL, End of Text, End of Transmission
@@ -182,6 +188,7 @@ fn (r Readline) analyse(c int) Action {
 	}
 }
 
+// analyse_control returns an `Action` based on the type of input read by `read_char`.
 fn (r Readline) analyse_control() Action {
 	c := r.read_char()
 	match byte(c) {
@@ -223,6 +230,8 @@ match c {
 	return .nothing
 }
 
+// analyse_extended_control returns an `Action` based on the type of input read by `read_char`.
+// analyse_extended_control specialises in cursor control.
 fn (r Readline) analyse_extended_control() Action {
 	r.read_char() // Removes ;
 	c := r.read_char()
@@ -240,19 +249,24 @@ fn (r Readline) analyse_extended_control() Action {
 	return .nothing
 }
 
+// analyse_extended_control_no_eat returns an `Action` based on the type of input byte given in `c`.
+// analyse_extended_control_no_eat specialises in detection of delete and insert keys.
 fn (r Readline) analyse_extended_control_no_eat(last_c byte) Action {
 	c := r.read_char()
 	match byte(c) {
-		`~` { match last_c {
+		`~` {
+			match last_c {
 				`3` { return .delete_right } // Suppr key
 				`2` { return .overwrite }
 				else {}
-			} }
+			}
+		}
 		else {}
 	}
 	return .nothing
 }
 
+// execute executes the corresponding methods on `Readline` based on `a Action` and `c int` arguments.
 fn (mut r Readline) execute(a Action, c int) bool {
 	match a {
 		.eof { return r.eof() }
@@ -276,12 +290,14 @@ fn (mut r Readline) execute(a Action, c int) bool {
 	return false
 }
 
+// get_screen_columns returns the number of columns (`width`) in the terminal.
 fn get_screen_columns() int {
 	ws := Winsize{}
 	cols := if C.ioctl(1, C.TIOCGWINSZ, &ws) == -1 { 80 } else { int(ws.ws_col) }
 	return cols
 }
 
+// shift_cursor warps the cursor to `xpos` with `yoffset`.
 fn shift_cursor(xpos int, yoffset int) {
 	if yoffset != 0 {
 		if yoffset > 0 {
@@ -294,6 +310,7 @@ fn shift_cursor(xpos int, yoffset int) {
 	print('\x1b[${xpos + 1}G')
 }
 
+// calculate_screen_position returns a position `[x, y]int` based on various terminal attributes.
 fn calculate_screen_position(x_in int, y_in int, screen_columns int, char_count int, inp []int) []int {
 	mut out := inp.clone()
 	mut x := x_in
@@ -316,7 +333,7 @@ fn calculate_screen_position(x_in int, y_in int, screen_columns int, char_count
 	return out
 }
 
-// Will redraw the line
+// refresh_line redraws the current line, including the prompt.
 fn (mut r Readline) refresh_line() {
 	mut end_of_input := [0, 0]
 	end_of_input = calculate_screen_position(r.prompt.len, 0, get_screen_columns(), r.current.len,
@@ -336,7 +353,7 @@ fn (mut r Readline) refresh_line() {
 	r.cursor_row_offset = cursor_pos[1]
 }
 
-// End the line without a newline
+// eof ends the line *without* a newline.
 fn (mut r Readline) eof() bool {
 	r.previous_lines.insert(1, r.current)
 	r.cursor = r.current.len
@@ -346,6 +363,7 @@ fn (mut r Readline) eof() bool {
 	return true
 }
 
+// insert_character inserts the character `c` at current cursor position.
 fn (mut r Readline) insert_character(c int) {
 	if !r.overwrite || r.cursor == r.current.len {
 		r.current = r.current.left(r.cursor).ustring().add(utf32_to_str(u32(c)).ustring()).add(r.current.right(r.cursor).ustring())
@@ -370,7 +388,7 @@ fn (mut r Readline) delete_character() {
 	r.refresh_line()
 }
 
-// Removes the character in front of cursor.
+// suppr_character removes (suppresses) the character in front of the cursor.
 fn (mut r Readline) suppr_character() {
 	if r.cursor > r.current.len {
 		return
@@ -379,7 +397,7 @@ fn (mut r Readline) suppr_character() {
 	r.refresh_line()
 }
 
-// Add a line break then stops the main loop
+// commit_line adds a line break and then stops the main loop.
 fn (mut r Readline) commit_line() bool {
 	r.previous_lines.insert(1, r.current)
 	a := '\n'.ustring()
@@ -392,6 +410,7 @@ fn (mut r Readline) commit_line() bool {
 	return true
 }
 
+// move_cursor_left moves the cursor relative one cell to the left.
 fn (mut r Readline) move_cursor_left() {
 	if r.cursor > 0 {
 		r.cursor--
@@ -399,6 +418,7 @@ fn (mut r Readline) move_cursor_left() {
 	}
 }
 
+// move_cursor_right moves the cursor relative one cell to the right.
 fn (mut r Readline) move_cursor_right() {
 	if r.cursor < r.current.len {
 		r.cursor++
@@ -406,22 +426,24 @@ fn (mut r Readline) move_cursor_right() {
 	}
 }
 
+// move_cursor_begining moves the cursor to the beginning of the current line.
 fn (mut r Readline) move_cursor_begining() {
 	r.cursor = 0
 	r.refresh_line()
 }
-
+// move_cursor_end moves the cursor to the end of the current line.
 fn (mut r Readline) move_cursor_end() {
 	r.cursor = r.current.len
 	r.refresh_line()
 }
 
-// Check if the character is considered as a word-breaking character
+// is_break_character returns true if the character is considered as a word-breaking character.
 fn (r Readline) is_break_character(c string) bool {
 	break_characters := ' \t\v\f\a\b\r\n`~!@#$%^&*()-=+[{]}\\|;:\'",<.>/?'
 	return break_characters.contains(c)
 }
 
+// move_cursor_word_left moves the cursor relative one word length worth to the left.
 fn (mut r Readline) move_cursor_word_left() {
 	if r.cursor > 0 {
 		for ; r.cursor > 0 && r.is_break_character(r.current.at(r.cursor - 1)); r.cursor-- {
@@ -432,6 +454,7 @@ fn (mut r Readline) move_cursor_word_left() {
 	}
 }
 
+// move_cursor_word_right moves the cursor relative one word length worth to the right.
 fn (mut r Readline) move_cursor_word_right() {
 	if r.cursor < r.current.len {
 		for ; r.cursor < r.current.len && r.is_break_character(r.current.at(r.cursor)); r.cursor++ {
@@ -442,16 +465,19 @@ fn (mut r Readline) move_cursor_word_right() {
 	}
 }
 
+// switch_overwrite toggles Readline `overwrite` mode on/off.
 fn (mut r Readline) switch_overwrite() {
 	r.overwrite = !r.overwrite
 }
 
+// clear_screen clears the current terminal window contents and positions the cursor at top left.
 fn (mut r Readline) clear_screen() {
 	term.set_cursor_position(x: 1, y: 1)
 	term.erase_clear()
 	r.refresh_line()
 }
 
+// history_previous sets current line to the content of the previous line in the history buffer.
 fn (mut r Readline) history_previous() {
 	if r.search_index + 2 >= r.previous_lines.len {
 		return
@@ -465,6 +491,7 @@ fn (mut r Readline) history_previous() {
 	r.refresh_line()
 }
 
+// history_next sets current line to the content of the next line in the history buffer.
 fn (mut r Readline) history_next() {
 	if r.search_index <= 0 {
 		return
@@ -475,6 +502,7 @@ fn (mut r Readline) history_next() {
 	r.refresh_line()
 }
 
+// suspend sends the `SIGSTOP` signal to the terminal.
 fn (mut r Readline) suspend() {
 	is_standalone := os.getenv('VCHILD') != 'true'
 	r.disable_raw_mode()

vlib/readline/readline_windows.c.v

@@ -1,18 +1,25 @@
 // Copyright (c) 2019-2020 Alexander Medvednikov. All rights reserved.
 // Use of this source code is governed by an MIT license
 // that can be found in the LICENSE file.
-
+//
-// Windows version
+// TODO Windows version needs to be implemented.
-// Need to be implemented
 // Will serve as more advanced input method
-// Based on the work of https://github.com/AmokHuginnsson/replxx
+// based on the work of https://github.com/AmokHuginnsson/replxx
-
+//
 module readline
 
 import os
 
 // Only use standard os.get_line
 // Need implementation for readline capabilities
+//
+// read_line_utf8 blocks execution in a loop and awaits user input
+// characters from a terminal until `EOF` or `Enter` key is encountered
+// in the input stream.
+// read_line_utf8 returns the complete input line as an UTF-8 encoded `ustring` or
+// an error if the line is empty.
+// The `prompt` `string` is output as a prefix text for the input capturing.
+// read_line_utf8 is the main method of the `readline` module and `Readline` struct.
 pub fn (mut r Readline) read_line_utf8(prompt string) ?ustring {
 	r.current = ''.ustring()
 	r.cursor = 0
@@ -21,14 +28,11 @@ pub fn (mut r Readline) read_line_utf8(prompt string) ?ustring {
 	if r.previous_lines.len <= 1 {
 		r.previous_lines << ''.ustring()
 		r.previous_lines << ''.ustring()
-  }
+	} else {
-  else {
 		r.previous_lines[0] = ''.ustring()
 	}
-
 	print(r.prompt)
 	r.current = os.get_raw_line().ustring()
-
 	r.previous_lines[0] = ''.ustring()
 	r.search_index = 0
 	if r.current.s == '' {
@@ -37,22 +41,32 @@ pub fn (mut r Readline) read_line_utf8(prompt string) ?ustring {
 	return r.current
 }
 
-// Returns the string from the utf8 ustring
+// read_line does the same as `read_line_utf8` but returns user input as a `string`.
+// (As opposed to `ustring` returned by `read_line_utf8`).
 pub fn (mut r Readline) read_line(prompt string) ?string {
 	s := r.read_line_utf8(prompt) ?
 	return s.s
 }
 
-// Standalone function without persistent functionnalities (eg: history)
+// read_line_utf8 blocks execution in a loop and awaits user input
-// Returns utf8 based ustring
+// characters from a terminal until `EOF` or `Enter` key is encountered
+// in the input stream.
+// read_line_utf8 returns the complete input line as an UTF-8 encoded `ustring` or
+// an error if the line is empty.
+// The `prompt` `string` is output as a prefix text for the input capturing.
+// read_line_utf8 is the main method of the `readline` module and `Readline` struct.
+// NOTE that this version of `read_line_utf8` is a standalone function without
+// persistent functionalities (e.g. history).
 pub fn read_line_utf8(prompt string) ?ustring {
 	mut r := Readline{}
 	s := r.read_line_utf8(prompt) ?
 	return s
 }
 
-// Standalone function without persistent functionnalities (eg: history)
+// read_line does the same as `read_line_utf8` but returns user input as a `string`.
-// Return string from utf8 ustring
+// (As opposed to `ustring` as returned by `read_line_utf8`).
+// NOTE that this version of `read_line` is a standalone function without
+// persistent functionalities (e.g. history).
 pub fn read_line(prompt string) ?string {
 	mut r := Readline{}
 	s := r.read_line(prompt) ?