110 lines
4.2 KiB
HTML
110 lines
4.2 KiB
HTML
<h5>Null Terminated Strings</h5>
|
|
<p>
|
|
As null terminated strings are used throughout C interfaces,
|
|
their use is supported in Forth by way of several non-standard
|
|
words with the convention of using Z/z to refer to such strings
|
|
in names and stack comments.
|
|
</p>
|
|
<pre>
|
|
Z" ( "string" -- z ) Creates a null terminated string on the heap
|
|
Z>S ( z -- a n ) Convert a null terminated string to a counted string
|
|
S>Z ( a n -- z ) Conver a counted string string to null terminated (copies string to heap)
|
|
</pre>
|
|
|
|
<h5>Raw Strings</h5>
|
|
<p>
|
|
Raw strings are provided better support using a string
|
|
for the duration of the current command, without consuming heap memory.
|
|
</p>
|
|
<pre>
|
|
R" ( "string" -- a n ) Creates a temporary counted string
|
|
R| ( string| -- a n ) Creates a temporary counted string ending with |
|
|
</pre>
|
|
|
|
<h5>Utilities</h5>
|
|
<pre>
|
|
DUMP ( a n -- ) Dump a memory region
|
|
SEE ( "name" -- ) Attempt to decompile a word
|
|
VARIABLE ECHO -- Determines if commands are echoed
|
|
</pre>
|
|
|
|
<h5>Vocabularies</h5>
|
|
<p>
|
|
{{FORTH}} uses a hybrid of Forth-79 and Forth-83 style vocabularies.
|
|
By default vocabularies chain to the vocabulary in which they were defined,
|
|
as in Forth-79. However, like Forth-83, <code>ALSO</code>
|
|
can be used to add vocabularies to a vocabulary stack of which
|
|
<code>CONTEXT @</code> is the first item.
|
|
The word <code>ONLY</code> clears the vocabulary stack, but as there is
|
|
no separate ONLY vocabulary, it also sets <code>CONTEXT</code>
|
|
to the <code>FORTH</code> vocabulary.
|
|
The word <code>SEALED</code> modifies the most recently defined vocabulary
|
|
such that it does not chain. Note, this must be done before words are added to it.
|
|
</p>
|
|
<pre>
|
|
VOCABULARY ( "name" ) Create a vocabulary with the current vocabulary as parent
|
|
FORTH ( -- ) Make the FORTH vocabulary the context vocabulary
|
|
DEFINITIONS ( -- ) Make the context vocabulary the current vocabulary
|
|
VLIST ( -- ) List the words in the context vocabulary (not chains)
|
|
WORDS ( -- ) List the words in the context vocabulary (including chains)
|
|
TRANSFER ( "name" ) Move a word from its current dictionary to the current vocabulary
|
|
Useful for "hiding" built-in words
|
|
TRANSFER{ ..words.. }TRANSFER ( -- ) Transfer multiple words to the current vocabulary
|
|
ALSO ( -- ) Duplicate the vocabulary at the top of the vocabulary stack
|
|
ONLY ( -- ) Reset context stack to one item, the FORTH dictionary
|
|
Non-standard, as there's no distinct ONLY vocabulary
|
|
ORDER ( -- ) Print the vocabulary search order
|
|
SEALED ( -- ) Alter the last vocabulary defined so it doesn't chain
|
|
</pre>
|
|
|
|
<h5>Interpret Time Conditions</h5>
|
|
<p>
|
|
<code>[I]F</code>, <code>[ELSE]</code>, and <code>[THEN]</code> can be used
|
|
to selectively compile. Used in tandem with <code>DEFINED?</code> they can
|
|
be used to handle the absence of modules gracefully.
|
|
Nesting is supported.
|
|
</p>
|
|
<pre>
|
|
DEFINED? ( "name" -- xt|0 ) Check if a word exists (works at compile time too).
|
|
[IF] ( f -- ) Conditionally interpret the text the follows.
|
|
[ELSE] ( -- ) Interpret time ELSE.
|
|
[THEN] ( -- ) Interpret time THEN.
|
|
</pre>
|
|
|
|
<h5>Blocks</h5>
|
|
<pre>
|
|
USE ( "name" -- ) Use "name" as the blockfile, e.g. USE /spiffs/foo
|
|
OPEN-BLOCKS ( a n -- ) Open a file as the block file
|
|
LOAD ( n -- ) Evaluate a block
|
|
THRU ( a b -- ) Load blocks a thru b
|
|
LIST ( n -- ) List a block
|
|
BLOCK ( n -- a ) Get a 1024 byte block
|
|
BUFFER ( n -- a ) Get a 1024 byte block without regard to old contents
|
|
UPDATE ( -- ) Mark the last block modified
|
|
FLUSH ( -- ) Save and empty all buffers
|
|
EMPTY-BUFFERS ( -- ) Empty all buffers
|
|
SAVE-BUFFERS ( -- ) Save all buffers
|
|
SCR ( -- a ) Pointer to last listed block
|
|
</pre>
|
|
|
|
<h5>Block Editor</h5>
|
|
These words are available inside the <code>EDITOR</code> vocabulary.
|
|
Note the block editor places newlines in the 63rd column of each line
|
|
to make the block file readable in a text editor.
|
|
<pre>
|
|
WIPE ( -- ) Blank out the current block
|
|
L ( -- ) List the current block
|
|
D ( n -- ) Delete a line in the current block
|
|
E ( n -- ) Clear a line in the current block
|
|
R ( n "text" -- ) Replace a line in the current block
|
|
A ( n "text" -- ) Add (insert) a line in the current block
|
|
P ( -- ) Move to the previous block
|
|
N ( -- ) Move to the next block
|
|
</pre>
|
|
|
|
<h5>Utilities</h5>
|
|
<pre>
|
|
SEE ( "name" -- ) Attempt to decompile a word
|
|
ECHO ( -- a ) -- Address of flag that determines if commands are echoed
|
|
</pre>
|