felise/docstring.go

package main

var kwDocstrings = map[string]string{
	"var!":         "Stack: TYPE\nRead : SYMBOL\nPush :\nNotes: Will create a variable with a default value (the zero value for the given type) in the nearest environment",
	"set!":         "Stack: ANY\nRead : SYMBOL\nPush :\nNotes: Will set the given value as the value for the given symbol in the nearest environment that the symbol can be found in. The type of the value must match the type of the variable.",
	"scoped-var!":  "Stack: TYPE INT\nRead : SYMBOL\nPush :\nNotes: Like `var!`, but takes an INT to jump up that number of scopes. The INT must be a positive integer. There is no overflow: if the global scope is reached, it will be used.",
	"scoped-set!":  "Stack: ANY INT\nRead : SYMBOL\nPush :\nNotes: Like `set!`, but takes an INT to jump up that number of scopes. The INT must be a positive integer. There is no overflow: if the global scope is reached, it will be used.",
	"+":            "Stack: ANY ANY\nRead :\nPush : ANY\nNotes:\n\t- Adds two INT, leaves an INT\n\t- Adds two FLOAT, leaves a FLOAT\n\t- Concatenates two STRING, leaves a STRING\n\t- Joins two LIST, leaves a LIST\n\t- Appends an INT as a rune to STRING (the INT should be TOS), leaves a STRING",
	"-":            "Stack: ANY ANY\nRead :\nPush : ANY\nNotes:\n\t- Subtracts two INT, leaves an INT\n\t- Subtracts two FLOAT, leaves a FLOAT\n\tRemoves from STRING all instances of STRING (TOS), leaves a STRING\n\t- Removes from LIST all instances of ANY (including sublists)",
	"*":            "Stack: ANY ANY\nRead :\nPush : ANY\nNotes:\n\t- Multiplies two INT, leaves an INT\n\t- Multiplies two FLOAT, leaves a FLOAT\n\t- Repeats STRING INT times, leaves a STRING\n\t- Joins a LIST by STRING, leaves a STRING",
	"/":            "Stack: ANY ANY\nRead :\nPush : ANY\nNotes:\n\t- Divides two INT, leaves an INT\n\t- Divides two FLOAT, leaves a FLOAT\n\t- Splits STRING at STRING, leaves a LIST",
	"proc":         "Stack:\nRead : SYMBOL\nPush:\nExmpl: `proc square | int -- int | dup * .`\nNotes:\n\tCreates a new procedure named by SYMBOL. The body of the proc is any quantity of valid felise code, including other procedures. To Finish the procedure you must use a `.` KEYWORD, since proc is a block style keyword.",
	"proc!":        "Stack:\nRead : SYMBOL\nPush:\nExmpl: `proc! ++ procarg 1 + set! procarg .`\nNotes: Just like proc, but with the added feature of making the resulting procedure read a SYMBOL and replace all instances of the special keyword `procarg` with that SYMBOL on execution of the procedure. This creates a very limited macro-like effect that lets the user write their own procedures that can adjust variable state easily.",
	"length":       "Stack: STRING || LIST || DICT\nRead :\nPush : INT\nNotes: Takes a STRING, LIST, or DICT and leaves its length on the stack.",
	"return":       "Notes: This is a special keyword that can be used inside of a `proc`/`proc!` definition. When the interpreter encounters it during the run of a procedure the procedure will exit there and then, as opposed to running through the rest of it's body.",
	"dup":          "Stack: ANY\nRead :\nPush : ANY ANY\nNotes: Duplicates TOS and leaves the copy and the original on TOS. (a1 -- a1 a1)",
	"drop":         "Stack: ANY\nRead :\nPush :\nNotes: Read TOS and throw it away. (a1 -- )",
	"over":         "Stack: ANY1 ANY2\nRead :\nPush : ANY1 ANY2 ANY1\nNotes: (a1 a2 -- a1 a2 a1)",
	"swap":         "Stack: ANY1 ANY2\nRead :\nPush : ANY2 ANY1\nNotes: (a1 a2 -- a2 a1)",
	"cast":         "Stack: ANY TYPE\nRead :\nPush : ANY\nExmpl: `24.2 INT cast` => 24 (INT)\nNotes: Converts ANY to TYPE if possible, and puts the result on TOS.",
	"type":         "Stack: ANY\nRead :\nPush : TYPE\nNotes: Takes a value from TOS and puts it's TYPE on TOS.",
	"while":        "Stack: ANY\nRead :\nPush :\nExmpl: `true while \"Hello, world!\" println true .` (infinite loop printing hello world)\nNotes: Like proc and if, while is a language constructs. While reads TOS and casts it to BOOL. If truthy, the body is executed. Then, when the `.` is encountered TOS will be popped again and checked for truthiness. If found truthy, the loop will start over. If not, execution will continue outside of the while construct.",
	"dowhile":      "Stack:\nRead :\nPush :\nExmpl: `true while \"Hello, world!\" println true .` (infinite loop printing hello world)\nNotes: Like proc and if, dowhile is a language constructs. dowhile executes the body one time no matter what. Then, when the `.` is encountered TOS will be popped and checked for truthiness. If found truthy, the loop will start over (popping again when the `.` is reached again, and going through the same process). If not, execution will continue outside of the dowhile construct.",
	"if":           "Stack: ANY\nRead :\nPush :\nExmpl: `0 if \"Truthy!\" println else \"Falsy\" println .`\nNotes: Like proc, proc!, while, and dowhile, if has a body to it that will be executed based on a value read from TOS. If the value is truthy, the first branch of the if will be executed (the values between `if` and `else`, if an `else` is present, and `if` and `.` if no else is present). If the value is falsy the else section will be executed, if one exists. If no else is present, then execution will continue outside of the if body.",
	"else":         "Notes: Else is a special keyword used within an `if` block to denote the start of the falsy portion of the `if` block.",
	"and":          "Stack: ANY ANY\nRead :\nPush : BOOL\nNotes: Takes two values and reports whether or not they are both truthy, via a BOOL placed on TOS.",
	"or":           "Stack: ANY ANY\nRead :\nPush : BOOL\nNotes: Takes two values and reports whether or not either of them are truthy, via a BOOL placed on TOS.",
	">":            "Stack: INT/FLOAT/STRING/BOOL INT/FLOAT/STRING/BOOL\nRead :\nPush : BOOL\nNotes: Compares the top two stack items to see if the item under TOS is greater than TOS. `>` can only compare INT to INT, FLOAT to FLOAT, or STRING to STRING. Comparing two BOOL always results in false, but is allowable to facilitate `<=` and the like on BOOL, since `=` supports all types. Leaves a bool on TOS.",
	"<":            "Stack: INT/FLOAT/STRING INT/FLOAT/STRING\nRead :\nPush : BOOL\nNotes: Compares the top two stack items to see if the item under TOS is less than TOS. `<` can only compare INT to INT, FLOAT to FLOAT, or STRING to STRING. Comparing two BOOL always results in false, but is allowable to facilitate `<=` and the like on BOOL, since `=` supports all types. Leaves a bool on TOS.",
	"=":            "Stack: ANY ANY\nRead :\nPush : BOOL\nNotes: Compares the top two stack items to see if they have an equal value and leaves BOOL on the stack. Note the word value; `=` does not compare memory addresses, only value. So it does not check that two values represent, for example, the same list... just that the two lists have the same content.",
	"stackdump":    "Stack:\nRead :\nPush :\nNotes: Dumps the stack to stdout.",
	"clearstack":   "Stack: ...ANY...\nRead :\nPush :\nNotes: Erases all values from the stack.",
	"->":           "Alias. See `list-set`.",
	"<-":           "Alias. See `list-get`.",
	"=>":           "Alias. See `list-append`.",
	"->!":          "Alias. See `list-set!`.",
	"=>!":          "Alias. See `list-append!`.",
	"append":       "Stack: LIST/STRING ANY\nRead :\nPush : LIST/STRING\nNotes: Appends ANY to LIST/STRING and leaves LIST/STRING on TOS. If LIST/STRING is STRING, ANY will be cast to string before appending.",
	"append!":      "Stack: ANY\nRead : SYMBOL\nPush :\nNotes: SYMBOL should represent a LIST or STRING. Appends ANY to the given LIST or STRING. If SYMBOL represents STRING then ANY will be cast to STRING before appending.",
	"list-get":     "Stack: LIST INT || DICT STRING\nRead :\nPush : ANY\nNotes: The INT represents the index of the item being retrieved from the LIST. Remember that indexing starts at 1 (not 0). A negative number can be used to work from the end of the list, with -1 being the last item. If using a DICT instead of a LIST a STRING representing the DICT key will be required on TOS. The item at the given index/key will be placed on TOS.",
	"list-set":     "Stack: LIST INT ANY || DICT STRING ANY\nRead :\nPush : LIST\nNotes: Sets ANY item to INT index of LIST or STRING key of DICT and puts the LIST or DICT back on TOS. INT can be negative to index from the end of the list.",
	"list-set!":    "Stack: INT ANY || STRING ANY\nRead : SYMBOL(list) || SYMBOL(dict)\nPush :\nNotes: Reads a SYMBOL that must represent a LIST or a DICT (or an error will be thrown). Sets ANY item to INT index of that LIST or STRING key of that DICT and updates it in memory (in the environment/scope that the variable is first encountered). INT can be negative to index from the end of the list.",
	"file-write":   "Stack: ANY STRING\nRead :\nPush :\nNotes: Takes a path as a STRING from TOS, then takes ANY from TOS. ANY will be cast to STRING and written to the path if possible.",
	"file-remove":  "Docstring coming soon.",
	"file-exists?": "Stack: STRING\nRead :\nPush : BOOL\nNotes: Checks the file-system to see if the path referenced by STRING exists and leaves a BOOL on TOS.",
	"file-read":    "Stack: STRING\nRead :\nPush : STRING\nNotes: Takes a STRING from TOS that should represent a file path. The file is read in its entirety, if possible, and placed on TOS as a STRING.",
	"docstring!":   "Stack:\nRead : SYMBOL\nPush : STRING\nNotes: Looks for SYMBOL in the symbol table. If the SYMBOL represents a PROC, the docstring will be placed on TOS. If the PROC has no docstring, an empty string will be placed on TOS.",
	"input":        "Stack:\nRead :\nPush : STRING\nNotes: Reads from stdin until a newline is encountered and places the resulting string (not including the newline) on TOS.",
	"re-match?":    "Stack: STRING STRING\nRead :\nPush : BOOL\nNotes: Checks to see if the string on TOS matches the regex STRING under TOS and puts a BOOL on the stack indicating if a match is found",
	"re-find":      "Stack: STRING(Haystack) STRING(Needle)\nRead :\nPush : LIST\nNotes: Finds matches of the regex STRING under TOS (Needle) in the STRING on TOS (Haystack) and puts a LIST of STRINGs on TOS",
	"re-find-all":  "Stack: STRING(Haystack) STRING(Needle)\nRead :\nPush : LIST\nNotes: Finds matches of the regex STRING under TOS (Needle) in the STRING on TOS (Haystack) and puts a LIST of LISTs of STRINGs on TOS. Finds all matches rather than just the first",
	"re-replace":   "Stack: ANY ANY ANY\nRead :\nPush : STRING\nNotes: Replaces values in a string based on a regex pattern (pattern string replacement -- STRING), all values taken from the stack will be cast to STRING",
	"slice":        "Stack: LIST INT INT\nRead :\nPush : LIST\nNotes: TOS is the index to slice until (inclusive), which can be negative (with -1 representing the last list item). The INT under TOS is the from index.",
	"stackdepth":   "Stack:\nRead :\nPush : INT\nNotes: Places the stack depth, as an INT, on TOS.",
	"net-get":      "Stack: STRING\nRead :\nPush : DICT\nNotes: Takes a gemini, gopher, or http(s) url STRING from TOS. A response DICT will be left on the stack, key \"success\" will be a BOOL declaring whether or not the request was successful, key \"status\" will be the status code of the response (or -1 if there is no status code), key \"body\" will be the response body. If the response was successful key \"body\" will be the actual body of the response, if it was not successful it will be an error message.",
	"try":          "Notes: 'try is a special construct in the interpreter. Anything between the KEYWORD 'try' and the KEYWORD 'catch' will be executed and if an error is encountered the code between 'catch' and '.' will be executed. For example, to add two numbers... but not accept an error and instead leave 0 on TOS if there is an error:\n\ttry + catch 0 .\nInside the 'catch' portion of the construct a variable will be available in the environment called 'catch-error' that contains the text of the error.",
	"catch":        "Part of a block construct. See `try`.",
	"import":       "Stack: STRING\nRead :\nPush :\nNotes: Reads a string from TOS (will coerce to string if a non-string value is TOS) and attempts to load the code that the string references. An included library (such as \"stack\" or \"math\" can be loaded from its name. Otherwise, a path is required. It can be relative, but should not conflict with the built in modules, as they will take priority.",
	"rot":          "Docstring coming soon.",
	"each!":        "Stack: LIST\nRead : PROC/KEYWORD/SYMBOL\nPush : ???\nNotes: 'each!' takes a list from TOS and forward reads a PROC or KEYWORD (a SYMBOL that does not represent a PROC will result in an error). The first list item will be placed on TOS then the PROC/KEYWORD will be executed, then the next list item will be placed on TOS then the PROC/KEYWORD will be executed, and so on. What is left on the stack will be variable depending on the PROC/KEYWORD being used. For example, to sum a list:\n\t0 [1 2 3 4] each! +\nNote that a zero is put on the stack first so that + can add 1 and 0 as the first op. The above would result in 10 being on TOS.",
	"throw":        "Stack: ANY\nRead :\nPush :\nNotes: Takes a STRING from TOS and throws an error with the text of the STRING. If a non-string value is TOS, it will be cast as STRING. 'throw' is particularly useful when defining procedures with 'proc' or 'proc!' so that these errors can then be caught in other code using a 'try'/'catch' block, but can also just be used to exit a program early with the given error message and a stack trace.",
	"filter!":      "Docstring coming soon.",
	"time":         "Stack:\nRead :\nPush : INT\nNotes: Adds the current time, as a unix timestamp INT, to TOS.",
	"char-conv":    "Stack: INT/STRING\nRead :\nPush : STRING/INT\nNotes: If an INT is TOS converts the INT as a rune to a char STRING (single character based on the rune number), if a STRING is TOS converts the first character of the STRING to an INT as a rune value. Will error on empty STRING or negative INT.",
	"get-env":      "Stack: STRING\nRead :\nPush : STRING\nNotes: Takes a STRING representing an envirnment variable and returns the value of that environment variable. If the variable could not be found, an empty STRING is returned.",
	"set-env":      "Stack: STRING ANY\nRead :\nPush : STRING\nNotes: Takes a STRING representing an envirnment variable and then an ANY representing a value (which well be stringified) to set to the variable. If the variable could not be set an error will be raised.",
}