____ ____ ____ ____ ||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 exiting the current word.
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: ( _ -- _ )
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 a new memory address to myvar each time local was called.
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: ( 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 \r. 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 a subprocess created with subproc.create:
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.