Merge pull request #2 from KSP-KOS/master

Upstream pull

SUMMARY.md

@@ -4,8 +4,8 @@ This repository is created from libraries submitted by multiple kOS users. All c
 This is an attempt at summarising and categorising the libraries by their use cases.
 
 ### Control
-1. [lib_pid.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_pid.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_pid.md) : provides functions for creating a PID controller. This functionality has been superseded by kOS buil-in `PIDLoop()`.
-2. [lib_raw_user_input.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_raw_user_input.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_raw_user_input.md) : currently broken. Listens for action groups in a list and returns the index of the activated action group.
+1. [lib_pid.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_pid.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_pid.md) : provides functions for creating a PID controller. This functionality has been superseded by kOS buil-in `PIDLoop()`.
+2. [lib_raw_user_input.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_raw_user_input.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_raw_user_input.md) : Listens for action groups in a list and returns the index of the activated action group.
 
 ### Data Structures
 1. [lib_enum.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_enum.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_enum.md) : provides functions to manipulate structures like lists, stacks, queues etc.
@@ -17,27 +17,30 @@ This is an attempt at summarising and categorising the libraries by their use ca
 1. [lib_file_exists.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_file_exists.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_file_exists.md) : checks whether a given file exists or not on the current volume. This functionality has been superseded by kOS built-in `VOLUME:EXISTS()`.
 
 ### Maths and Statistics
-1. [lib_running_average_filter.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_running_average_filter.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_running_average_filter.md) : gives a running average of a given list of numbers.
+1. [lib_running_average_filter.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_running_average_filter.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_running_average_filter.md) : gives a running average of a given list of numbers.
 
 ### Navigation
 1. [lib_circle_nav.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_circle_nav.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_circle_nav.md) : provides functions to help with great circle / geodesic navigation while in atmosphere or the surface. For example, finding out the compass heading of a waypoint to fly there along the shortest path.
-2. [lib_navball.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_navball.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_navball.md) : provides various state values of a vessel like compass heading, pitch, roll etc.
-3. [lib_navigation.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_navigation.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_navigation.md) : provides a range of functions to used in calculations of both space, atmospheric and surface navigation.
+2. [lib_location_constants.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_location_constants.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_location_constants.md) : provides latitude longitude values for various locations on some bodies.
+3. [lib_navball.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_navball.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_navball.md) : provides various navball state values (heading, pitch, roll, etc) of several kOS structures that can be considered to have such state.
+4. [lib_navigation.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_navigation.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_navigation.md) : provides a range of functions to used in calculations of both space, atmospheric and surface navigation.
 
 ### Programming Utilities
-1. [lib_exec.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_exec.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_exec.md) : allows executing commands and evaluating expressions from strings. This is possibly broken.
+1. [lib_exec.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_exec.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_exec.md) : allows executing commands and evaluating expressions from strings.
 
 ### Space Navigation
-1. [lib_lazcalc.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_lazcalc.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_lazcalc.md) : does launch azimuth calculation.
+1. [lib_lazcalc.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_lazcalc.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_lazcalc.md) : does launch azimuth calculation.
 
 ### Terminal Utilities
-1. [lib_gui_box.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_gui_box.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_gui_box.md) : draws ASCII boxes in the terminal.
-2. [lib_input_string.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_input_string.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_input_string.md) : creates an on-screen keyboard inside the terminal.
-3. [lib_list_dialog.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_list_dialog.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_list_dialog.md) : helps with long list navigation.
-4. [lib_menu.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_menu.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_menu.md) : draws an interactive menu in the terminal.
-5. [lib_num_to_formatted_str.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_num_to_formatted_str.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_num_to_formatted_str.md) : provides functions to format numbers and date-time values in standard formats. For example, numbers with given digit precision and SI unit, time broken into years, months, days etc.
-6. [lib_num_to_str.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_num_to_str.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_num_to_str.md) : formats numbers to specified number of digits.
-7. [lib_number_dialog.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_number_dialog.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_number_dialog.md) : draws a dialog box for numerical input in the terminal.
-8. [lib_seven_seg.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_seven_seg.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_seven_seg.md) : creates a seven segment display to show single digit numbers.
-9. [lib_str_to_num.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_str_to_num.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_str_to_num.md) : converts numerical strings into numbers. This has been superseded by kOS built-in `STRING:TONUMBER()`.
-10. [lib_term.ks](https://github.com/KSP-KOS/KSLib/master/library/lib_term.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_term.md) : a primitive terminal ASCII graphics library. Helps with drawing straight lines, circles and elliptical arcs.
+1. [lib_gui_box.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_gui_box.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_gui_box.md) : draws ASCII boxes in the terminal.
+2. [lib_input_string.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_input_string.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_input_string.md) : creates an on-screen keyboard inside the terminal.
+3. [lib_input_terminal](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_input_terminal.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_input_terminal.md) : for string input by typing in the terminal.
+
+4. [lib_list_dialog.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_list_dialog.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_list_dialog.md) : helps with long list navigation.
+5. [lib_menu.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_menu.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_menu.md) : draws an interactive menu in the terminal.
+6. [lib_num_to_formatted_str.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_num_to_formatted_str.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_num_to_formatted_str.md) : provides functions to format numbers and date-time values in standard formats. For example, numbers with given digit precision and SI unit, time broken into years, months, days etc.
+7. [lib_num_to_str.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_num_to_str.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_num_to_str.md) : formats numbers to specified number of digits.
+8. [lib_number_dialog.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_number_dialog.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_number_dialog.md) : draws a dialog box for numerical input in the terminal.
+9. [lib_seven_seg.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_seven_seg.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_seven_seg.md) : creates a seven segment display to show single digit numbers.
+10. [lib_str_to_num.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_str_to_num.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_str_to_num.md) : converts numerical strings into numbers. This has been superseded by kOS built-in `STRING:TONUMBER()`.
+11. [lib_term.ks](https://github.com/KSP-KOS/KSLib/blob/master/library/lib_term.ks) / [docs](https://github.com/KSP-KOS/KSLib/blob/master/doc/lib_term.md) : a primitive terminal ASCII graphics library. Helps with drawing straight lines, circles and elliptical arcs.

doc/lib_exec.md

@@ -5,6 +5,10 @@
 This library is a powerful tool for unhardcoding program's behavior.
 As far as I know it works fine in all possible special cases.
 
+#### WARNINGS:
+  * this library can fail if there is insufficient free space on the local volume.
+  * this library requires several global variables to work. As a result, any scripts making use of this library should not use any of the following variable names: `_exec_idString` , `_evaluate_result` , `_exec__param_list` , `_past_exec_strings`
+
 ### execute
 
 args:
@@ -17,7 +21,7 @@ description:
 
 example:
   `execute("set x to 42. print x.").`
-  
+
 caveat #1:
   * run command in the current version of kOS works in a weird way:
 ```
@@ -44,12 +48,15 @@ caveat #2:
 }
 ```
 
+caveat #3
+  * The limit on the size of a command that can be executed is how much free space you have on the local volume of the core
+
 ##### The same caveats apply to other functions from this library.
 
 ### evaluate
 
 args:
-  * expression - an expression to evaluate. Unlike "command" parameter from function
+  * expression - string, an expression to evaluate. Unlike "command" parameter from function
     `execute` an expression should **not** end with dot: `evaluate("7 * a + 2").`.
 
 returns:
@@ -75,6 +82,40 @@ example:
   does exactly the same as:
   `print foo(42, true, "hello").`
 
+### get_suffix
+
+args:
+  * structure - any structure, the structure to get the suffix of
+  * suffix - string, the suffix to get
+  * parameter_list - list of anything, if a suffix is a function then this is the ordered list of parameters to be passed to the suffix 0th parameter maps to the 0th item in the list, will be ignored if not of type list, defaulted to `FALSE`
+
+returns:
+  * result - will be what ever the suffix returns
+
+example:
+```
+print get_suffix(ship,"mass").
+print get_suffix(body,"geopositionlatlng",list(1,2)).
+```
+  is equivalent to
+```
+print ship:mass.
+print body:geopositionlatlng(1,2).
+```
+
+### set_suffix
+
+args:
+  * structure - any structure, the structure to set the suffix of
+  * suffix - string, the suffix to set
+  * val - any structure, the value to set the suffix to
+
+example:
+  `set_suffix(core,"tag","lib_exec").`
+  is the same as
+  `set core:tag to "lib_exec".
+
+
 ### useful tips
 
 * Compilation is a slow process. Each call of lib_exec's functions causes
@@ -86,4 +127,4 @@ example:
   until done {
     print my_expr.  // insert your main loop code here
   }
-  ```
+  ```

doc/lib_input_terminal.md

@@ -0,0 +1,81 @@
+// This file is distributed under the terms of the MIT license, (c) the KSLib team
+
+## lib_input_terminal.
+
+`lib_input_terminal` provides functions for getting user entered strings or numbers though terminal inputs.
+
+### terminal_input_string
+
+args:
+  1) col - (scalar), The column to start the print of the current string at as required by `PRINT x AT(col,row).`
+  2) row - (scalar), The row to start the print of the current string at as required by `PRINT x AT(col,row).`
+  3) maxLength - (scalar), The maximum length of the string that can be returned,
+    defaulted to the terminal width minus the col argument.
+  4) inValue - (string or scalar), The string or scalar to pre-populate the input space with,
+    defaulted to an empty string.
+  5) cursorBlink - (boolean), Determines if the character denoting where the next char entered by the user will go will cycle between `█` and `_` or stay a stedy `_`
+    defaulted to true.
+
+returns:
+  A string
+
+description:
+  This function takes key presses on the kOS terminal and adds them into a single string until the user presses enter to stop and return the string.
+  While the string is being added to it will be printed on the terminal at the location set by the arguments.
+  The control keys that are recognized by this function are backspace, delete, and enter/return.
+    Pressing enter/return ends the loop and returns the current string.
+    Pressing backspace removes the last charter from the current string until the string is empty.
+    Pressing delete sets the current string to an empty string.
+
+### terminal_input_number
+
+args:
+  1) col - (scalar), The column to start the print of the current string at as required by `PRINT x AT(col,row).`
+  2) row - (scalar), The row to start the print of the current string at as required by `PRINT x AT(col,row).`
+  3) maxLength - (scalar), The one greater than the maximum length of the string that can be returned,
+    defaulted to the terminal width minus the col argument.
+  4) inValue - (string or scalar), The string or scalar to pre-populate the input space with,
+    defaulted to an empty string.
+    if not a valid number will be discarded and replaced with the default.
+  5) cursorBlink - (boolean), Determines if the character denoting where the next char entered by the user will go will cycle between "█" and "_" or stay a steady "_"
+    defaulted to true.
+
+returns:
+  A string
+
+description:
+  This function takes key presses on the kOS terminal and adds them into a single string for displaying a number.  As such this function only works with a limited set of keys. The keys it will add to the string are "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", and "." with "+" and "-" for denoting sign.
+  While the string is being added to it will be printed on the terminal at the location set by the arguments.
+  The function will also try to format the string so that it can be directly converted into a scalar by the `:TOSCALAR()` suffix. Should the formatting fail, " 0" is returned by default.
+  There is only allowed to be one "." character in a string at a time. If a second "." is entered it will be ignored.
+  The control keys that are recognized by this function are "+", "-", backspace, delete, and enter/return.
+    Pressing "-" will change the first character of the string from "-" to " " or " " to "-".
+    Pressing "+" will change the first character of the string from "-" to " " or will do nothing if the first character is already " ".
+    Pressing backspace will remove the last character from the string until there is only one character left.
+    Pressing delete will erase then currently stored string.
+    Pressing enter/return will end the function and return the current string.
+
+### input_loop
+
+args:
+  1) col - (scalar), The column to start the print of the current string at as required by `PRINT x AT(col,row).`
+  2) row - (scalar), The row to start the print of the current string at as required by `PRINT x AT(col,row).`
+  3) maxLength - (scalar), The one greater than the maximum length of the string that can be returned,
+  4) minLength - (scalar), The smallest length that pressing backspace can reduce the string to.
+  5) workingStr - (string), The string to pre-populate the input space with
+  6) cursorBlink - (boolean), determines if the character denoting where the next char entered by the user will go will cycle between "█" and "_" or stay a steady "_"
+  7) concatenator - (user delegate or anonymous function), a function with the rules for concatenation of the string.
+
+returns:
+  *A string
+
+description:
+  This function reads the key presses and stores the current string until the loop is ended by pressing enter.
+  While the current string is being added to it will be printed on the terminal at the location set by the arguments.
+  The concatenator function is called with the current string, non-control key presses, and maxLength.
+    It is responsible for the rules of what a given key press will do to the current string and keeping the string from getting larger than maxLength.  It is expected to return the processed string back to `input_loop` - to be stored as the current string.
+  The control keys that are recognized by this function are backspace, delete, and enter/return.
+    Pressing enter/return ends the loop and returns the current string.
+    Pressing backspace removes the last character from the current string until the string length is less than or equal to minLength
+    Pressing delete sets the current string to an empty string.
+