|
- Be sure to read "usage.txt" for a guide to Collapse OS' Forth.
-
- *** Glossary ***
- Stack notation: "<stack before> -- <stack after>". Rightmost is top of stack
- (TOS). For example, in "a b -- c d", b is TOS before, d is TOS after. "R:" means
- that the Return Stack is modified. "I:" prefix means "IMMEDIATE", that is, that
- this stack transformation is made at compile time.
-
- Word references (wordref): When we say we have a "word reference", it's a
- pointer to a words *code link*. For example, the label "PLUS:" in this unit is a
- word reference. Why not refer to the beginning of the word struct? Because we
- actually seldom refer to the name and prev link, except during compilation, so
- defining "word reference" this way makes the code easier to understand.
-
- Atom: A word of the type compiledWord contains, in its PF, a list of what we
- call "atoms". Those atoms are most of the time word references, but they can
- also be references to NUMBER and LIT.
-
- Words between "()" are "support words" that aren't really meant to be used
- directly, but as part of another word.
-
- "*I*" in description indicates an IMMEDIATE word.
-
- *** Defining words ***
- (find) a -- a f Read at a and find it in dict. If found, f=1 and
- a = wordref. If not found, f=0 and a = string addr.
- : x ... -- Define a new word
- ; R:I -- Exit a colon definition
- , n -- Write n in HERE and advance it.
- ' x -- a Push addr of word x to a. If not found, aborts
- ['] x -- *I* Like "'", but spits the addr as a number
- literal. If not found, aborts.
- ( -- *I* Comment. Ignore rest of line until ")" is read.
- ALLOT n -- Move HERE by n bytes
- C, b -- Write byte b in HERE and advance it.
- CREATE x -- Create cell named x. Doesn't allocate a PF.
- [COMPILE] x -- Compile word x and write it to HERE. IMMEDIATE
- words are *not* executed.
- COMPILE x -- Meta compiles. Kind of blows the mind. See below.
- CONSTANT x n -- Creates cell x that when called pushes its value
- DOES> -- See description at top of file
- IMMED? a -- f Checks whether wordref at a is immediate.
- IMMEDIATE -- Flag the latest defined word as immediate.
- LITN n -- Write number n as a literal.
- VARIABLE c -- Creates cell x with 2 bytes allocation.
-
- *** Flow ***
- Note about flow words: flow words can only be used in definitions. In the
- INTERPRET loop, they don't have the desired effect because each word from the
- input stream is executed immediately. In this context, branching doesn't work.
-
- (br) -- Branches by the number specified in the 2 following
- bytes. Can be negative.
- (?br) f -- Branch if f is false.
- [ -- Begin interetative mode. In a definition, words
- between here and "]" will be executed instead of
- compiled.
- ] -- End interpretative mode.
- ABORT -- Resets PS and RS and returns to interpreter
- ABORT" x" -- *I* Compiles a ." followed by a ABORT.
- AGAIN I:a -- *I* Jump backwards to preceeding BEGIN.
- BEGIN -- I:a *I* Marker for backward branching with AGAIN.
- ELSE I:a -- *I* Compiles a (fbr) and set branching cell at a.
- EXECUTE a -- Execute wordref at addr a
- IF -- I:a *I* Compiles a (fbr?) and pushes its cell's addr
- INTERPRET -- Get a line from stdin, compile it in tmp memory,
- then execute the compiled contents.
- QUIT R:drop -- Return to interpreter prompt immediately
- RECURSE R:I -- R:I-2 Run the current word again.
- THEN I:a -- *I* Set branching cell at a.
- UNTIL f -- *I* Jump backwards to BEGIN if f is *false*.
-
- *** Parameter Stack ***
- DROP a --
- DUP a -- a a
- OVER a b -- a b a
- ROT a b c -- b c a
- SWAP a b -- b a
- 2DROP a a --
- 2DUP a b -- a b a b
- 2OVER a b c d -- a b c d a b
- 2SWAP a b c d -- c d a b
-
- *** Return Stack ***
- >R n -- R:n Pops PS and push to RS
- R> R:n -- n Pops RS and push to PS
- I -- n Copy RS TOS to PS
- I' -- n Copy RS second item to PS
- J -- n Copy RS third item to PS
-
- *** Memory ***
- @ a -- n Set n to value at address a
- ! n a -- Store n in address a
- ? a -- Print value of addr a
- +! n a -- Increase value of addr a by n
- C@ a -- c Set c to byte at address a
- C! c a -- Store byte c in address a
- CURRENT -- a Set a to wordref of last added entry.
- HERE -- a Push HERE's address
- H@ -- a HERE @
- MOVE a1 a2 u -- Copy u bytes from a1 to a2, starting with a1, going
- up.
-
- *** Arithmetic / Bits ***
-
- + a b -- c a + b -> c
- - a b -- c a - b -> c
- -^ a b -- c b - a -> c
- * a b -- c a * b -> c
- / a b -- c a / b -> c
- MOD a b -- c a % b -> c
- /MOD a b -- r q r:remainder q:quotient
- AND a b -- c a & b -> c
- OR a b -- c a | b -> c
- XOR a b -- c a ^ b -> c
-
- *** Logic ***
- = n1 n2 -- f Push true if n1 == n2
- < n1 n2 -- f Push true if n1 < n2
- > n1 n2 -- f Push true if n1 > n2
- CMP n1 n2 -- n Compare n1 and n2 and set n to -1, 0, or 1.
- n=0: a1=a2. n=1: a1>a2. n=-1: a1<a2.
- NOT f -- f Push the logical opposite of f
-
- *** Strings ***
- LIT -- Write a LIT entry. You're expected to write actual
- string to HERE right afterwards.
- LIT< x -- Read following word and write to HERE as a string
- literal.
- LITS a -- Write word at addr a as a atring literal.
- SCMP a1 a2 -- n Compare strings a1 and a2. See CMP
- SCPY a -- Copy string at addr a into HERE.
- SLEN a -- n Push length of str at a.
-
- *** I/O ***
-
- (parse) a -- n Parses string at a as a number and push the result
- in n as well as whether parsing was a success in f
- (false = failure, true = success)
- (parse.) a -- n f Sub-parsing words. They all have the same signature.
- Parses string at a as a number and push the result
- in n as well as whether parsing was a success in f
- (0 = failure, 1 = success)
- (parse*) -- a Variable holding the current pointer for system
- number parsing. By default, (parse).
- (print) a -- Print string at addr a.
- . n -- Print n in its decimal form
- .x n -- Print n's LSB in hex form. Always 2 characters.
- .X n -- Print n in hex form. Always 4 characters. Numbers
- are never considered negative. "-1 .X" --> ffff
- ." xxx" -- *I* Compiles string literal xxx followed by a call
- to (print)
- C< -- c Read one char from buffered input.
- DUMP n a -- Prints n bytes at addr a in a hexdump format.
- Prints in chunks of 8 bytes. Doesn't do partial
- lines. Output is designed to fit in 32 columns.
- EMIT c -- Spit char c to output stream
- IN> -- a Address of variable containing current pos in input
- buffer.
- KEY -- c Get char c from direct input
- PC! c a -- Spit c to port a
- PC@ a -- c Fetch c from port a
- WORD -- a Read one word from buffered input and push its addr
-
- There are also ascii const emitters:
- BS
- CR
- LF
- SPC
|
