Warning: this is an htmlized version!
The original is across this link,
and the conversion rules are here.
A GLOSSARY of words in the RubyFORTH dictionary. ================================================ Words in the FORTH wordlist --------------------------- ! ( n a -- ) Store value /n/ at address /a/. " ( "...<">" -- $ ) Forward parse until either EOL or the string delimiter. Return a string object. ' ( "<word>" -- xt ) Push the execution token of the next word in the input stream. Searched all vocabularies. See also 'xt?' ( ( "...<)>" -- ) Comment until closing parenthesis or EOL. * ( n1 n2 -- n1*n2 ) Multiply. + ( n1 n2 -- n1+n2 ) Add. +! ( n a -- ) Increment /a/ by /n/. , ( n -- ) Write /n/ to the next free cell of data space, then increment the data space pointer, /here/. - ( n1 n2 -- n1-n2 ) Subtract. -rot ( a b c -- c a b ) Inverse of /rot/. . ( n -- ) Print the top of the stack. ." ( "...<">" -- ) Forward parse until either EOL or the string delimiter. Type the parsed string. .context ( -- ) Print the active wordlist. .ds ( -- ) Dictionary dump. Dumps the contents of the dictionary with mild formatting. .r ( n1 n2 -- ) Print /n1/ with visual width /n2/. .s ( -- ) Print a representation of the data stack. .vocab ( <vocab> -- ) Print all the words in the 'forth' and 'compiler' wordlists from the supplied vocabulary (see 'words'). / ( n1 n2 -- n1/n2 ) Divide. 0= ( n -- f ) Is /n/ equal to 0? Can also mean, is /n/ 'false'? 1+ ( n -- n+1 ) 1- ( n -- n-1 ) 2! ( n1 n2 a -- ) Store a double at address /a/. 2, ( n1 n2 -- ) Write a double to dataspace, advancing HERE accordingly. (See /,/). 2@ ( a -- n1 n2 ) Fetch a double from address /a/. 2drop ( n1 n2 -- ) Drop the first two items on the data stack. 2dup ( n1 n2 -- n1 n2 n1 n2 ) Duplicate the first two items on the data stack. 2swap ( n1 n2 n3 n4 -- n3 n4 n1 n2 ) Swap the the top two pairs on the data stack. : ( "<word>" -- ) Begin a new word definition. Writes its header immediately. :noname ( -- ) Begin a headerless definition. Leaves the word's xt on the top of the stack immediately, so beware of accessing the stack during the :noname word's definition (e.g., inside [ ]). < ( n1 n2 -- f ) Is /n1/ less than /n2/? <= ( n1 n2 -- f ) Is /n1/ less than or equal to /n2/? = ( n1 n2 -- f ) Is /n1/ equal to /n2? > ( n1 n2 -- f ) Is /n1/ greater than /n2/? >= ( n1 n2 -- f ) Is /n1/ greater than or equal to /n2/? >r ( n -- ) Push the top of the data stack into the return stack. ?branch ( f -- ) Conditionally branch to the contents of the adjacent memory address. ?dup ( n -- n ?n ) Conditionally duplicate the top of the stack if it tests true. @ ( a -- n ) Fetch the contents of /a/. \ ( "...<EOL>" -- ) Comment out the rest of the line. ] ( -- ) Enter compilation mode. alias ( "<new-word>" "<old-word>" -- ) Create a new header, /new-word/, pointing to the same xt as /old-word/. allot ( n -- ) Advance the data space pointer by /n/. and ( n1 n2 -- f ) Logical and of /n1/ and /n2/. bl ( -- ) Emit a space. branch ( -- ) Branch to the contents of the adjacent memory address. bye ( -- ) Exit RubyFORTH. cd ( "directory" -- ) Forward parse the entire line, and change the current working directory. chdir ( directory$ -- ) Using a stack string, change the current working directory. char ( "<character>" -- c ) Forward parse and push the ascii value of the found character to the data stack. close ( fd -- ) Close the file specified by file descriptor /fd/. compiler ( -- ) Switch the active wordlist to 'compiler'. This means that subsequent headers will be written into the compiler vocabulary. constant ( n "<word>" -- ) Create a new word that will push /n/ to the stack when it is called. cr ( -- ) Print a newline character. create ( "<word>" -- ) Create a new word that will return its data space address when called. See also does>. defer ( "<word>" -- ) Create a new deferred word. The specific action of this word can be set using 'is'. drop ( n -- ) Drop the top of the stack. dup ( n -- n n ) Duplicate the top of the stack (i.e., push a copy of the TOS). emit ( c -- ) Print ascii value /c/ to stdout. enter-ruby ( -- ) Enter Ruby REPL using the IRB module. eof? ( fd -- f ) Is file /fd/ at the EOF? execute ( xt -- ) Execute the xt. For example "myword" could be executed by calling "myword" OR "' myword execute". See also ':noname'. expose ( <vocab> -- ) Push the supplied vocabulary onto the vocabulary search stack. forth ( -- ) Switch the active wordlist to 'forth'. This means that subsequent headers will be written into the forth vocabulary. header ( "<word>" -- ) Create a new header in the active wordlist, pointing 'here'. here ( -- a ) The data space pointer. Also, the code space pointer. i! ( c string$ i -- ) Set the /i/th element in /string/ to character /c/. This will work with arrays, too. 0 offset. i@ ( string$ i -- c ) Return the /i/th character in /string/. 0 offset. include ( "<filename>" -- ) Load the contents of filename, evaluating each line. Sets 'forth' as the default context before and after including source. included ( filename$ -- f ) Has 'filename' already been included? is ( xt "<deferred word>" -- ) Set the deferred word's value to xt. This means that when the deferred word is called, the code at xt will be executed. local' ( "word" -- xt ) Push the execution token of the next word in the input stream. Only search the current vocabulary. See also 'search', tick, and 'xt?'. local-name? ( xt -- f | name$ ) Return the header for xt, if found in the active wordlist in the current vocabulary. Return a false flag otherwise. local-xt ( name$ -- xt ) Return the execution token of the supplied name if it's in the current vocabulary. make ( name$ -- ) Identical to 'create' with one exception -- instead of forward parsing, the created word's header is read from the stack. This offers additional flexibility as it can be used in conjunction with string handling words to automate word generation. max ( n1 n2 -- n3 ) Calculate the greater of n1 and n2, leave it on the stack. min ( n1 n2 -- n3 ) Calculate the lesser of n1 and n2, leave it on the stack. name? ( xt -- f | name$ ) Return the header for xt, if found in the active wordlist. Return a false flag otherwise. nip ( n1 n2 -- n2 ) Drop the stack item beneath the top of stack. needs ( "<filename>" -- ) Include 'filename' (see 'include') unless it has already been included. not ( n -- f ) Equivalent to '0=', used for logical comparison. open ( filename$ mode$ -- fd ) Open /filename/ with the relevant /mode/, returning a file descriptor. For more on modes, see the words: 'r/o', 'r/w', 'w/o' and w/r'. or ( n1 n2 -- f ) Logical or. order ( -- ) Print the current vocabulary search order (see 'vocab', 'expose', 'shield'). over ( n1 n2 -- n1 n2 n1 ) Push a copy of the second stack item to the data stack. page ( -- ) Clears the screen (currently Unix only). parse ( c -- parsed$ ) Consume the input stream up until character /c/ or EOL is met. Everything that has been consumed is placed on the stack as the parsed string. parse-word ( -- parsed$ ) Consume the input stream up until a whitespace token -- this can be either TAB or space. This is *not* equivalent to 'bl parse' as 'parse' can only take one termination character. peek ( c -- peeked$ ) Identical to 'parse', except that the input stream is left unharmed. In other words, peek _copies_ everything up until /c/ or EOL, it doesn't consume. peek-word ( -- peeked$ ) Identical to 'parse-word', except that the input stream is left unharmed. position ( fd -- pos ) Push the current position in file /fd/. prim ( "<name>" "...<EOL>" -- ) Create a new primitive from within RubyFORTH. The first token is the name of this primitive (which is inserted into the active wordlist). The rest of the line is Ruby code, evaluated as a primitive whenever encountered. quit ( -- ) Return to toplevel immediately. r/o ( -- mode$ ) Return a Ruby mode string indicating read-only. r/w ( -- mode$ ) Return a Ruby mode string indicating read-write. r> ( -- n ) Pop the top of the return stack and push it to the data stack. r@ ( -- n ) As 'r>', but _copies_ from the return stack instead of popping. read ( fd count -- read$ ) Read /count/ bytes from /fd/. readline ( fd -- line$ ) Read a line from /fd/. rot ( n1 n2 n3 -- n2 n3 n1 ) Rotate the third stack item, bringing it to the top of the data stack. ruby-include ( "<filename>" -- ) Load a Ruby module, evaluating its contents. rubyforth ( -- <vocab> ) Push the main RubyFORTH vocabulary onto the stack. search ( word$ vocabulary -- xt ) Search for word$ in the supplied vocabulary, returning the execution token. see ( "<word>" -- ) Print a representation of the parsed word. This is useful for debugging. Primitives are also represented. seek ( fd pos -- ) Set the position of /fd/ to /pos/. shield ( -- ) Drop the topmost vocabulary from the search stack. space ( -- ) Print a space to stdout. spaces ( n -- ) Print /n/ spaces to stdout. swap ( n1 n2 -- n2 n1 ) Swap the top two stack items. tuck ( n1 n2 -- n2 n1 n2 ) Basically: 'swap', then 'over'. A useful stack manipulation word. type ( string$ -- ) Print a string. (See also '.'). variable ( "<name>" -- ) Create a new variable. When executed, a variable returns its data space address. This can then be stored to (see '!') and fetched from (see '@'). vocab ( name$ -- <vocab> ) Create a new vocabulary object with the supplied name and place it on the stack. vocab: ( "name" -- ) Creates a new vocabulary object with the supplied name and store this object has a RubyFORTH word with the same header. w/o ( -- mode$ ) Return a Ruby mode string indicating write-only. w/r ( -- mode$ ) Return a Ruby mode string indicating write-read. word ( c -- a len ) Like 'parse', but returns a familiar addr/len pair in scratch space. This is like a string; each address cell holds one character. Useful for quick parsing operations where all we want to do is fetch. Used by 'char'. words ( -- ) Print all the words in the 'forth' and 'compiler' wordlists from the topmost vocabulary. write ( text$ fd -- ) Write /text/ to file /fd/. xt? ( word$ -- xt ) Push the execution token of the string at the top of the stack. See also tick. Words in the COMPILER wordlist ------------------------------ " See FORTH glossary. ( See FORTH glossary. ." See FORTH glossary. 2>r ( n1 n2 -- ) Place /n1/ and /n2/ on the return stack. 2literal ( n1 n2 -- ) As 'literal', but deals with pairs of literals. 2r> ( -- n1 n2 ) Fetch the top two items from the return stack. 2r@ ( -- n1 n2 ) As '2r>', but leave the return stack unchanged. Peek. 2rdrop ( -- ) Drop the first two items on the return stack. Compiles '2r> 2drop'. ; ( -- ) End a colon definition. ?if ( -- ) Conditionally duplicate the top of stack if it's true (see '?dup'), then enter a conditional (see 'if'). [ ( -- ) Exit compilation mode. See ']' ['] ( "<word>" -- ) Used to "tick" the next word in the input stream, immediately. This differs from the standard tick word which when compiled will only be called when its parent word is executed. [compile] ( "<word>" -- ) Compile the next word -- from the COMPILER wordlist -- into the current definition. [is] ( xt "<deferred word>" -- ) See 'is'. Works immediately within a definition. \ See FORTH glossary. again ( a -- ) Branch to the contents of memory address /a/. Used for 'begin...again' constructions (infinite loops). ahead ( -- a ) Compiles a branch instruction, returning an address that can be set by /then/. begin ( -- a ) Simply returns the data space pointer. Marks the beginning of two loop constructs, 'begin...while...repeat' and 'begin...again'. char See FORTH glossary. compile ( "<word>" -- ) Compile the next word -- from the FORTH wordlist -- into the current definition when the parent word is called. do ( upper lower -- a ) Push the loop bounds to the return stack, compile a 'dobranch?' instruction and return the data space pointer for branching purposes. dobranch? ( -- ) Test the top two items on the return stack (loop bounds) to see whether a do...loop should continue iterating. Contains a '?branch' instruction. does> ( -- ) Used with 'create'. 'does>' can expect the address of the created word on the stack. The body of a 'does>' statement specified what to do with this address whenever the created word is called. A very flexible construct. else ( -- ) Branching in conditionals. for ( count -- a ) Compile 'do', inferring a lower bound of 0. So, '10 0 do' becomes '10 for'. As such, 'for...next' iterates from 0 to the supplied bound on the stack. This may differ from some 'for...next' implementations, notorious for the variety of their operation. Ours is a syntactic simplification of 'do'. i ( -- n ) Same as r@, a return stack peek word. Conventially used to indicate the loop index in 'do...loop's. if ( -- a ) Compiles a '?branch' instruction and places the address of the cell in which the branch address will be situated on the stack. iterate ( -- ) Increment the top of the return stack. Used to increment the do...loop index (see 'i'). literal ( n -- ) Compile a 'lit' instruction, then write /n/ into the current definition. This tells the interpreter to treat the number as a literal, not a memory address. loop ( -- ) Compile an 'iterate' instruction to increase the loop index, then branch to the beginning of the loop (i.e., to 'do'). next ( -- ) Compiles 'loop'; see the latter for more details. repeat ( a -- ) Takes an address for branching and compiles an 'again' instruction. then ( a -- ) Resolves branching addresses, thereby ending a conditional. unloop ( -- ) Used in a 'do...loop' construction. Sets the current index to the upper bound, making the current iteration the final one. while ( -- a2 a1 ) Compiles a conditional branch instruction, branching information, etc.