💾 Archived View for rawtext.club › ~sloum › nimf › guide › api › builtins.gmi captured on 2023-05-24 at 18:17:33. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-12-03)
-=-=-=-=-=-=-
____ ____ ____ ____ ||n |||i |||m |||f || ||__|||__|||__|||__|| |/__\|/__\|/__\|/__\|
"Builtins" is the term for any words that come with the nimf interpreter and are coded in golang, rather than nimf itself. Most of them involve basic primitive operations (addition, subtraction, printing a character, etc) or involve something that I was unable to develop in nimf directly without great effort (socket connections, file handling, environment variables, etc). A few others are just there for convenience in order to make the base system semi-usable without any nimf modules to inline.
Signature: ( n1 n2 -- n )
Description: Eats the top two stack values and leaves their sum on the stack.
Signature: ( n1 n2 -- n )
Description: Eats the top two stack values and subtracts the first from the second (n1 - n2 in the above signature), leaving the result on the stack.
Signature: ( n1 n2 -- n )
Description: Eats the top two stack values and multiplies them together, leaving the result on the stack.
Signature: ( n1 n2 -- n )
Description: Eats the top two stack values and divides the second by the first ( n1 / n2 in the above signature), leaving the quotient (whole part of the result) on the stack.
Signature: ( n1 n2 -- n )
Description: Eats the top two stack values and divides the second by the first (n1 / n2 in the above signature), leaving the remainder on the stack.
Signature:
Description:
Signature:
Description:
Signature:
Description:
Signature:
Description:
Signature:
Description:
Signature: ( n -- _ )
Description: Eats TOS. Leaves nothing, outputs nothing.
Signature: ( n -- n n )
Description: Copies TOS and leaves the copy on TOS.
Signature: ( n1 n2 -- n2 n1 )
Description: Swaps the position of the top two stack values so that the first is now the second and the second is not the first.
Signature: ( n1 n2 -- n1 n2 n1 )
Description: Copies the second value on the stack and leaves it on TOS.
Signature: ( n1 ... nx v -- n1 ... nx n1 )
Description: Copies a value v values into the stack to TOS. In general, this word is to be avoided as possible as it blurs the purpose and usage of the stack into something it mostly shouldn't be.
Signature: ( n1 .. nx v -- n1-1 ... nx n1 )
Description: Moves a value v values into the stack to TOS (rather than copying, as pick does), displacing all other values down the stack by one. Much like pick, this word should be avoided if at all possible as it blurs the purpose and usage of the stack into something it mostly shouldn't be. Use variables and memory if you need to store and retrieve values in this way.
Signature: ( _ -- _ )
Description: Outputs a visual representation of the stack. The number between angle brackets (ex. <3>) is the stack depth and the numbers between the square brackets (ex. [ 5 23 2 ]) are the values of the stack itself with the rightmost value being TOS.
Signature: ( _ -- _ )
Description: Outputs a visual representation of the return stack. The number between angle brackets (ex. <3>) is the stack depth and the numbers between the square brackets (ex. [ 5 23 2 ]) are the values of the return stack itself with the rightmost value being TOS.
Signature: ( n -- _ ) r( _ -- n )
Description: Moves the top value on the data stack to the top of the return stack.
Signature: ( _ -- n ) r( n -- _ )
Description: Moves the top value on the return stack to the top of the data stack.
Signature: ( _ -- n ) r( n -- n )
Description: Copies the top value on the return stack to the top of the data stack (while leaving the value still on the return stack as well).
Signature: ( ... -- ... n)
Description: Eats nothing and leaves the current data stack depth, prior to calling `depth`, on the data stack.
Signature: ( _ -- n) r( ... -- ... )
Description: Eats nothing and leaves the current return stack depth, prior to calling `depth`, on the data stack.
Signature: ( ... -- _ )
Description: Eats all values on the stack, leaves nothing, outputs nothing.
Signature: ( n1 n2 -- flag )
Description: Eats the top two values on the stack and leaves a flag indicating if the second is greater than the first (in the signature it would test if n1 is greater than n2).
Signature: ( n1 n2 -- flag )
Description: Eats the top two values on the stack and leaves a flag indicating if the second is less than the first (in the signature it would test if n1 is less than n2).
Signature: ( n1 n2 -- flag )
Description: Eats the top two values on the stack and leaves a flag indicating if the two values are equal.
While not a word itself, the convention for entering individual characters is to preface them with a backtick like so: `J
In this case `J is actually an alias for the ascii value of J, which is 74. This provides an easy way to enter characters into source code without having a bunch of magic values everywhere (they are easy to forget). This syntax also allows for things like `\n to represent a newline or `\e to represent an escape. See the nimf guide for more information.
Signature: ( _ -- _ )
Description: Eats nothing, leaves nothing, outputs nothing. Exits an interactive session / quits the interpreter.
Signature: ( n -- _ )
Description: Eats TOS and exits the program with an exit code equal to the value that was eaten.
Signature: ( _ -- _ )
Description: Eats nothing and leaves nothing. Outputs a list of the words currently available to nimf at the time the word was called. Note that this can change at any time by inlining a module or by defining new words or enums.
Signature: ( _ -- _ )
Description: Eats nothing and leaves nothing. Toggles the interpreters string mode. If string mode was not on, it turns it on. While on, all text entered into the system will get added to the temporary string buffer until another instance of `"` is reached (which will toggle off string mode).
Signature: ( n -- _ )
Description: Eats top of stack and idles the system for a number of miliseconds equal to the value that was eaten. Leaves nothing.
Signature: ( _ -- _ )
Description: Eats nothing and leaves nothing. Starts the definition of a new word. Until the word `;` is reached, all input will be part of the new word definition and will not be processed until the word is completed and called.
Signature: ( _ -- _ )
Description: Eats nothing and leaves nothing. Ends a word definition and causes the new word to be parsed and added to the word list. Calling `;` while not in word composition mode will result in an error.
Signature: ( _ -- _ )
Description: Eats nothing and leaves nothing. Used in file mode only. Signals to the interpreter that a module being inlined has finished. All modules that will be inlined (`*.nh` files) should have this as the last word in the document. It will have no effect in interactive or run modes.
Signature: ( _ -- _ )
Description: Eats nothing and leaves nothing. Toggles on comment mode. From when this word is read until the comment closing word `)` all other words or values will be ignored by the interpreter.
Signature: ( _ -- _ )
Description: Eats nothing and leaves nothing. Toggles off comment mode and resumes normal interpreter opperation.
Signature: ( _ -- _ )
Description: Eats nothing and leaves nothing. Expects a word to follow it (ex. `see =`) and will output the definition of that word. If the word is a builtin, will output the fact that the word is a builtin. This is a great way to see how various module words are implemented as it will show the exact implementation being used.
Signature: ( flag -- _ )
Description: Eats a flag from TOS. If the value is truthy, sets a register to ignore anything it finds in a matching `else` branch and to process everything in the `if` branch of the conditional. If the value is falsy sets a register to ignore anything it finds in the `if` branch, but to process a matching `else` branch if one is present. `if` can only be used inside of word definitions and will throw an error if used outside of a word definion. See `:` for information about defining words.
Signature: ( _ -- _ )
Description: Eats nothing and leaves nothing. Reads from a system register to determine if the contents of the `else` branch should be processed or ignored. Must come somewhere between an `if` and a `then` to create an optional branch. Like `if` and `then` can only be used inside of word definitions.
Signature: ( _ -- _ )
Description: Eats nothing and leaves nothing. Sets the system registers and return stack data in such a way as to end the conditional branch that was started with `if` and may contain an optional `else`. Like `if` and `else` can only be used within word definitions.
Signature: ( _ -- _ )
Description: Eats nothing and leaves nothing. Sets a system value to indicate the starting point of a loop. This starting point will be returned to by a matching `loop` word if `loop` eats a truthy value. Like the various conditional words, `do` and `loop` can only be used inside of word definitions.
Signature: ( flag -- _ )
Description: Eats a flag from TOS, leaves nothing. If the flag is truthy will move execution back to a point specified by a preceding `do`. Otehrwise, it will exit the loop and execution will continue on from left to right. Like the various conditional words, `do` and `loop` can only be used inside of word definitions.
Signature: ( _ -- _ )
Description: Has no stack effects. Reads a string from the termporary string buffer and attempts to load a module that matches that string name. Will look in: "./", "./lib", "$XDG_DATA_HOME" or "~/.local/share/nimf", and "/usr/local/lib/nimf"; will search these locations in that order. If a module that matches is found, its contents will be parsed and its words will be added to the available words list. If no module is found an error will be thrown.
Signature: ( _ -- _ )
Description: Has no stack effects. Reads a string from the temporary string buffer and throws an error with a message matching that string. Halts further execution.
Signature: ( _ -- col row)
Description: Takes nothing from the stack and leaves the number of columns and rows the current terminal window contains on TOS.
Signature: ( _ -- timestamp )
Description: Takes nothing from the stack and leaves the current time on TOS as a unix time stamp.
Signature: ( sptr -- flag )
Description: Eats a string pointer from TOS. Attempts to retrieve an environment variable with a key matching the string the pointer points to. If a match is found, the value for that environment variable is left as a string in the temporary string buffer and a truthy flag is left on TOS. If no key is found that matches, then a falsy flag is left on TOS indicating no matching variable could be found.
Signature: ( _ -- _ )
Description: Takes nothing from and leaves nothing on the stack. Can only be used within a word definition. Will exit the word immediately and functions similar to `return` or `break` in some other languages, except it does not return anything and what it breaks out of is the word. Will clean up any unfinished loops or conditionals automatically. Does not modify variables or leave anything on the stack, it is up to the caller to handle any variable or stack state they wish to leave upon exit.
Signature: ( _ -- _ )
Description: Takes nothing from the stack and leaves nothing on it. Lets the interpreter know that the next thing it encounters will not be a word but the name of a new variable. It will set aside one cell of memory space for the variable and update the name list with the given name and store the memory address as that name. Example: `var myvar` would create a variable named myvar whose value is a memory address. The value (`myvar @`) is initialized as `0` and can now be set with `!` or `set`. When used with the word `allot` `var` can be used to create arrays, store strings without using `svar` (which is really just a quick way to store a particular string), and create other data structures.
Signature: ( _ -- _ )
Description: Takes nothing from the stack and leaves nothing on it. Similar to `var` it lets the interpreter know to expect a name to follow it. The difference comes from the fact that when svar is called, it will reserve enough memory space to store the string currently in the termporary string buffer and copy the string into that space. Example: `" hello " svar hi`. In the example `hi` would have the value of the first memory address for the string (which contains the string length).
Signature: ( n -- _ )
Description: Takes TOS and moves the available memory pointer ahead that number of spaces. This effectively expands a variable, since no other variables will be assigned that space. It is on the programmer to remember this available length, or depending on usage store the length in the first cell similar to how strings store their length. Note that allot extends the current memory space. You cannot create two vars and then allot more for the first one. You can only allot for the last created variable (at time of call). Also note that a variable created with `var` is already one cell long, so `5 allot` would result in a 6 cell variable.
Signature: ( _ -- _ )
Description: Takes nothing from the stack and leaves nothing on it. Lets the interpreter know that the next thing it encounters will not be a word but the name of a new local variable. It will set aside one cell of memory space for the variable and update the word local name list with the given name and store the memory address as that name. Example: `local myvar` would create a variable named myvar whose value is a memory address. The value (`myvar @`) is initialized as `0` and can now be set with `!` or `set`. When used with the word `lallot` `local` can be used to create arrays, store strings without using `svar` (which is really just a quick way to store a particular string), and create other data structures. `allot` will have not effect on a variable create with local (`lallot` must be used). `local` can only be used within a word definition. All memory and references to a local are lost when the word they are created within ends. Words called after a local variable is created will not have access to the local variable by name, but the memory address can still be passed to them on the stack. So long as they access the memory before the word with the local declaration ends, the memory will be avialable. Repeated calls to `local myvar` would reassign memory to `myvar` each time local was calle
Signature: ( n -- _ )
Description: Takes TOS and moves the available local memory pointer ahead that number of spaces. This effectively expands a local variable, since no other variables will be assigned that space. It is on the programmer to remember this available length, or depending on usage store the length in the first cell similar to how strings store their length. Note that `lallot` extends the current memory space. You cannot create two vars and then `lallot` more for the first one. You can only `lallot` for the last created variable (at time of call). Also note that a variable created with `local` is already one cell long, so `5 lallot` would result in a 6 cell local variable.
Signature: ( n ptr -- _ )
Description: Takes a memory address (pointer) and a value from the stack and writes that value to the memory address. Remember that all variables are pointers. So, if you have a variable `myvar` you can set its value to 5 like so: `5 myvar !`
Description: `set` is an alias for `!` and performs exactly the same. Some developers may prefer to use set since it is more clear, others may prefer the less verbose and more forth-like `!`. Either works fine.
Signature: ( ptr -- _ )
Description: Eats a memory address (pointer) from TOS and writes the string currently in the temporary string buffer to that memory address. Note that `s!` has no knowledge of where memory diverges between variables and it is up to the caller to make sure there is room for the string in memory at that location. Leaves nothing on the stack.
Description: `set-string` is an alias for `s!` and performs exactly the same. Some developers may prefer to use set since it is more clear, others may prefer the less verbose `s!`. Either works fine.
Signature: ( ptr -- n )
Description: Eats a memory address (pointer) from TOS and leaves the value held at that address on TOS.
Description: `get` is an alias for `@` and performs exactly the same. Some developers may prefer the shorter `@` and others may prefer `get` for its clear wording. Either is fine.
Signature: ( sptr -- _ )
Description: Eats a memory address (pointer) that points to a string and copies that string to the temporary string buffer (where it may be moved elsewhere, manipulated, etc). Leaves nothing on the stack. Note that providing a memory address that does not point to the first cell of a string (which stores the string's length) may have unexpected results.
Description: `get-string` is an alias for `s@` and performs exactly the same. Use whichever you can remember and like working with.
Signature: ( start end -- _ )
Description: Eats an ending memory address and a starting memory address from the stack. `sr@` makes the assumption that the range of addresses form the bounds of a string and it moves that string into the temporary string buffer. This is a way to work with substrings or sections of very large strings. Leaves nothing on the stack.
Description: `get-raw-string` is an alias for `sr@` and performs exactly the same. Use whichever you can remember and like working with.
Signature: ( n ptr -- _ )
Description: Takes a memory address (pointer) and a value from the stack. Adds the value from the stack to the value already held at the memory address. If `myvar` was `5` then `6 myvar +!` would make the value of myvar `11`. Leaves nothing on the stack.
Signature: ( n -- _)
Description: Eats TOS and outputs its value to the screen. Does not apply a space or newline after output. If they are desired, they will need to be added. The `std` module has words that do this, but they are trivial to make and can be easily reimplemented. Leaves nothing on the stack.
Signature: ( _ -- _ )
Description: Takes nothing from the stack and leaves nothing on it. Outputs a newline (`\n`). The naming here is admittedly confusing, since it does not ouput a `cr`. This is a carryover name from forth that may get updated or aliased in the future.
Signature: ( _ -- _ )
Description: Takes nothing from the stack and leaves nothing on it. Outputs an ascii space character.
Signature: ( _ -- _ )
Description: Takes nothing from the stack and leaves nothing on it. Gets a line of input from the user, with a line defined as ending in a newline (`\n`). Stores the string that was entered in the temporary string buffer.
Signature: ( _ -- ch )
Description: Takes nothing from the stack. Gets a single keypress from the user and leaves the numerical value of that keypress on TOS.
Signature: ( ch -- _ )
Description: Takes a numerical value representing a character from TOS and outputs that value as a character. Values of 1 - 127 correspond to their ascii values. Larger numbers correspond to golang rune values, which map to unicode code points.
Signature: ( sptr -- flag )
Description: Takes a string address (string pointer) from TOS. The string should be a host and a port in the format `myhost.com:99` where 99 could be any port. The system will attempt to connect to this host/port and leave a flag on the stack indicating whether the connection was successful. Only one connection can be open at a time and connections should be closed with `tcp.close`.
Signature: ( _ -- _ )
Description: Takes nothing from the stack. Closes any open tcp connection that may have been created with `tcp.connect`. Connections should always be closed when your code is done using them. Leaves nothing on the stack. An attempt to close an already closed connection will silently do nothing.
Signature: ( sptr -- flag )
Description: Takes a string address (string pointer) from TOS. The string should be the value you want to write to an open connection created with `tcp.connect`. Will attempt to write the value to the connection and will leave a flag on the stack indicating if the write was successful or not.
Signature: ( _ -- flag )
Description: Takes nothing from the stack. Attempts to read all data available from the connection and store it in the temporary string buffer. Leaves a flag on the stack indicating if the read was successful.
Signature: ( sptr ch -- _ )
Description: Takes a character and a string address (string pointer) from TOS. The string should contain the path for the file that will be opened. The character should be one of the following:
In line read mode, the user will be able to call `file.read` until the file is fully read, to get one line at a time moved to the temporary string buffer.
Whole file read mode will attempt to open the file, read the whole file into the temporary string buffer and close the file (ie. no call to `file.read` will be necessary). If the file is longer than the available memory in the temporary string buffer, the file contents will be truncated.
Write mode will open the file for writing with `file.write`. This will truncate the file itself and replace its contents with any calls to `file.write`. If the file does not exist, it will be created.
Append mode works like write mode, except any calls to `file.write` will be appended to the file, rather than nimf truncating the file. If the file does not exist, it will be created.
If permission issues or any other issues are encountered, an error will be raised.
Signature: ( sptr -- flag )
Description: Takes a string address (string pointer) from TOS. The string referenced by the pointer should be a filepath on the local system. Leaves a flag on the stack indicating if the filepath is a valid filepath.
Signature: ( _ -- flag )
Description: Takes nothing from the stack. Reads the next available line from the open file (starting from the beginning with the first read) and copies it to the temporary string buffer. If successful leaves a truthy value (-1) on the stack. If successful, but the end of the file is reached leaves a falsy value (0) on the stack. If any issues are encountered `file.read` will throw an error.
Signature: ( sptr -- _ )
Description: Takes a string address (string pointer) from TOS. Will write the string at the address to the currently open file (in either write or append mode). Leaves nothing on the stack. Will throw an error if the write fails.
Signature: ( _ -- _ )
Description: Takes nothing from the stack an leaves nothing on the stack. Closes the currently open file. Subsequent calls to `file.close` (ie. where there is no open file) will have no effect.
Signature: ( sptr -- _ )
Description: Takes a string address (string pointer) from TOS. Will create, but not run, a subprocess with the value of the given string split into space separated fields. The first field will be the run path of the subprocess. Any additional fields are treated as arguments to the first field. At time of writing quoted strings are not supported. Leaves nothing on the stack, will error if unable to create the subprocess.
Signature: ( sptr -- _ )
Description: Takes a string address (string pointer) from TOS. Will pipe the given string into the stdin of a subprocess created with `subproc.create`. `subproc.send` must be called before `subproc.exec`. Will error if a process does not exist. Use `subproc.ready?` if you want to check if a process exists. Leaves nothing on the stack.
Signature: ( sptr -- _ )
Description: Takes a string address (string pointer) from TOS. Will change the working directory of the current process, created with `subproc.create`, to the contents of the given string. Leaves nothing on the stack, will error if the string is invalid.
Signature: ( _ -- flag )
Description: Takes nothing from the stack. Leaves a flag on TOS indicating whether there is an unexecuted subprocess.
Signature: ( ch -- _ )
Description: Takes a character from TOS. The character passed determines the run mode for executing the subprocess:
Quick mode is best used when you want to run the subprocess and capture its output as a string to the temporary string buffer.
Interactive mode is best used for programs you wish to interact with, like launching a text editor. Interactive mode connects stdin and stdout to the subprocess, and as a result can print to the screen, rather than just capture output.
Background mode will launch a subprocess, and relinquish it to the system to handle (it will not interact with nimf any further beyond nimf executing it). This is great if you need to, say, launch a web browser or open a pdf, while still having access to nimf at the command line (background mode does not block).
Once execution completes, the subprocess will be cleared and `subproc.ready?` will be false. If you wish to run the same subprocess again, you will need to go through the steps to re-create it (or better yet: make a word for it).
Leaves nothing on the stack, will error if there are any issues running the process.
________________________________________________