💾 Archived View for rawtext.club › ~sloum › nimf › guide › api › std-module.gmi captured on 2023-04-26 at 13:36:50. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-12-03)
-=-=-=-=-=-=-
____ ____ ____ ____ ||n |||i |||m |||f || ||__|||__|||__|||__|| |/__\|/__\|/__\|/__\|
The standard module provides a lot of basic tools for a wide range of purposes. Most of these are items that should come with the language, but because they are not builtins (coded in Go) and are written in nimf itself, they land in the std module. Unlike most other modules, words in the std module are not generally prefixed with a module name. This is due to their usefulness and the fact that you will be typing them often, so brevity is the name of the game here.
Many of the words in this module come directly from the forth programming language and exist to provide familiarity for forth programmers. Use them if you like, or develop your own to accomplish the specific tasks you have in mind in a way that works for you.
The std module comes with four variables. All of them are intended to make looping easier and are named with common looping shorthand, with the exception of std.t, which stands for target. Do remember that if you use these you will likely want to move whatever values they have at the time of setting them onto the return stack and then move the values from the return stack back to the variables at the end of your word, creating a local scope. That said, they can also be used to pass values between words.
Signature: ( n -- _ )
Description: Eats TOS and outputs the number followed by a space. This word is the same as `,`, but adds a space to the output.
Signature: ( n -- flag )
Description: Eats TOS and leaves a flag on the stack indicating if the value was false (0).
Signature: ( n -- flag )
Description: Eats TOS and leaves a flag on the stack indicating if the value was truthy (not 0).
Signature: ( n1 n2 -- flag )
Description: Eats the top two values from the stack and leaves a flag indicating if they are not equal.
Signature: ( n1 n2 -- flag )
Description: Eats two numbers from the top of the stack and leaves a flag indicating if the second number removed from the stack is greater than or equal to the first. Looking at the signature, >= would test if n1 is greater than or equal to n2.
Signature: ( n1 n2 -- flag )
Description: Eats two numbers from the top of the stack and leaves a flag indicating if the second number removed from the stack is less than or equal to the first. Looking at the signature, <= would test if n1 is greater than or equal to n2.
Signature: ( n1 n2 n3 -- n2 n3 n1 )
Description: Eats the top three numbers on the stack and leaves them with the third number down now on top of the stack, the formerly top one in the second position, and the formerly second one in the third position. See the signature for clarification.
Signature: ( n1 n2 -- n1 n2 n1 n2 )
Description: Copies the top two items on the stack and puts them on top of the originals. See signature.
Signature: ( n1 n2 -- _ )
Description: Drops the top two values from the stack, does not output any values.
Signature: ( n1 n2 n3 n4 -- n1 n2 n3 n4 n1 n2 )
Description: Requires at least four items on the stack. Copies the third and fourth item and places them on top of the stack in the order they were found in. See signature.
Signature: ( n1 n2 n3 n4 -- n3 n4 n1 n2 )
Description: Requires at least four items on the stack. Swaps the positions of the first and second with the third and third and fourth. See signature.
Signature: ( n1 n2 n3 -- n1 n2 n3 n1 n2 n3 )
Description: Copies the top three items on the stack and palces the copies on top of the stack.
Signature: ( n1 n2 n3 -- _ )
Description: Drops the top three values from the stack, does not output any values.
Signature: ( n1 n2 -- n2 n1 n2 )
Description: Requires at least two values on the stack. Copies TOS and places the copy below the second stack item (into the third position), can be thought of as the reverse of `over`. See signature.
Signature: ( ptr -- _ )
Description: Eats a memory address from TOS and sets the value stored at that address to true (-1). Leaves nothing on the stack.
Signature: ( ptr -- _ )
Description: Eats a memory address from TOS and sets the value stored at that address to false (0). Leaves nothing on the stack.
Signature: ( _ -- _ )
Description: Drops TOS from the return stack.
Signature: ( n -- n+1 )
Description: Eats TOS, increments it by one, and leaves the new value on TOS.
Signature: ( n -- n-1 )
Description: Eats TOS, decrements it by one, and leaves the new value on TOS.
Signature: ( n1 count -- n1 [...] )
Description: Eats a count from TOS, then copies the new TOS and adds its value to TOS a number of times equal to the count that was eaten.
Signature: ( count -- _ )
Description: Eats TOS and outputs a number of ascii space characters equal to the value that was eaten.
Signature: ( n1 n2 -- remainder quotient )
Description: Like `/`, but also leaves the remainder on the stack (underneath the quotient), allowing the caller to work with a decimal value.
Signature: ( n exp -- n^exp )
Description: Eats the top two values on the stack and raises the second to the power of the first, leaving the result on the stack.
Signature: ( ptr -- _ )
Description: Eats TOS and outputs the value stored at the pointer address leaving nothing on the stack.
Signature: ( n ptr -- n )
Description: Eats a pointer and a value from TOS. Adds the valie to the value stored at the pointer address and puts the result on TOS, without altering the value stored at the memory address.
Signature: ( flag flag -- flag )
Description: Logical `or`; eats two flags from TOS. If either flag is truthy (not 0), leaves -1 on TOS. If neither is truthy leaves 0 on TOS.
Signature: ( flag flag -- flag )
Description: Logical `and`; eats two flags from TOS. If both flags are truthy (not 0) leaves -1 on TOS. Otherwise, leaves 0 on TOS.
Signature: ( flag -- !flag )
Description: Eats a flag from TOS and leaves the inversion of the flag on top of stack. For example, if 5 was TOS before not was called, then 0 would be left on the stack after. Likewise if 0 was TOS before, then -1 would be after.
________________________________________________