~vdupras/collapseos

ref: ac3629b817115b1af75096856ee9499cfbbd3392 collapseos/doc/dict.txt -rw-r--r-- 11.3 KiB
ac3629b8Virgil Dupras Make BLK@* and BLK!* into ialiases 1 year, 11 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
# Dictionary

List of words defined in arch-specific boot code (for example,
B280 for Z80), Core words (B350) and Extra words (B150).

# 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.

Some words have a variable stack signature, most often in pair
with a flag. These are indicated with "?" to tell that the argu-
ment might not be there. For example, "-- n? f" means that "n"
might or might not be there.

Word references (wordref): When we say we have a "word
reference", it's a pointer to a word's *entry type field*. For
example, the address that "' DUP" puts on the stack is a
wordref, that is, a reference to the entry type field of the
word DUP. See impl.txt for details.

PF: Parameter field. The area following the entry type field of
a word. For example, "' H@ 1+" points to the PF of the word H@.

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.

# Symbols

Throughout words, different symbols are used in different
contexts, but we try to been consistent in their use. Here's
their definitions:

! - Store
@ - Fetch
$ - Initialize
^ - Arguments in their opposite order
< - Input
> - 1. Pointer in a buffer 2. Opposite of "<".
( - Lower boundary
) - Upper boundary
* - Word indirection (pointer to word)
? - Is it ...? (example: IMMED?)

# Entry management

'? x     -- a f   Find x it in dict. If found, f=1 and
                  a = wordref. If not found, f=0 and
                  a = string addr.
' 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.
FIND     w -- a f Like '?, but for w.
EMPTY    --       Rewind HERE and CURRENT where they were at
                  system initialization.            
FORGET   x --     Rewind the dictionary (both CURRENT and HERE)
                  up to x's previous entry.             
PREV     a -- a   Return a wordref's previous entry.
WORD(    a -- a   Get wordref's beginning addr.

# Defining words

: x ... ;   --     Define a new word
:* x        a --   Define a new alias
:** x       a --   Define a new ialias
CREATE x    --     Create cell named x. Doesn't allocate a PF.
[COMPILE] x --     *I* Compile word x and write it to HERE.
                   IMMEDIATE words are *not* executed.
COMPILE x   --     *I* Meta compiles: write wordrefs that will
                   compile x when executed.
CONSTANT x  n --   Creates cell x that when called pushes its
                   value.
DOES>       --     See primer.txt
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 that 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.

f IF A ELSE B THEN: if f is true, execute A, if false, execute
B. ELSE is optional.
[IF] .. [THEN]: Meta-IF. Works outside definitions. No [ELSE].
BEGIN .. f UNTIL: if f is false, branch to BEGIN.
BEGIN .. AGAIN: Always branch to BEGIN.
x y DO .. LOOP: LOOP increments y. if y != x, branch to DO.

x CASE y OF A ENDOF z OF B ENDOF C ENDCASE: If x == y, execute
A, if x == z, execute B. Otherwise, execute C. x is dropped
in case of an OF match, *but it is kept if it reaches C*. You
have to consume it to avoid PSP leak.           

(br)      --   Branches by the number specified in the 2
               following bytes. Can be negative.
(?br)     f -- Branch if f is false.
(         --   *I* Comment. Ignore input until ")" is read.
[         --   *I* Begin interpretative mode. In a definition,
               execute words instead of compiling them.
]         --   End interpretative mode.
ABORT     --   Resets PS and RS and returns to interpreter.
ABORT" x" --   *I* Compiles a ." followed by a ABORT.
ERR       a -- Prints a and ABORT. Defined early and used by
               drivers.
EXECUTE   a -- Execute wordref at addr a
INTERPRET --   Main interpret loop.
LEAVE     --   In a DO..LOOP, exit at the next LOOP call.
QUIT      --   Return to interpreter prompt immediately.

# Parameter Stack

DROP        a --
DUP         a -- a a
?DUP        DUP if a is nonzero
NIP         a b -- b
OVER        a b -- a b a
ROT         a b c -- b c a
ROT>        a b c -- c a b
SWAP        a b -- b a
TUCK        a b -- b a b
2DROP       a a --
2DUP        a b -- a b a b
'S          Returns current stack pointer, not counting the
            push it's making right now.
S0          Returns address of PSP TOS. When PSP is empty,
            'S == S0                                 
PICK        Pick nth item from stack. "0 PICK" = DUP,
            "1 PICK" = OVER.
ROLL        Rotate PSP over n items. "1 ROLL" = SWAP,
            "2 ROLL" = ROT. 0 is noop.

# Return Stack

>R          n -- R:n        Pops PS and push to RS
2>R         x y -- R:x y    Equivalent to SWAP >R >R
R>          R:n -- n        Pops RS and push to PS
2R>         R:x y -- x y    Equivalent to R> R> SWAP
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
,        n --            Write n in HERE and advance it.
?        a --            Print value of addr a
+!       n a --          Increase value of addr a by n
~C!      a --            Set C! and ! overrides. See notes.
C@       a -- c          Set c to byte at address a
C@+      a -- a+1 c      Fetch c from a and inc a.
C@-      a -- a-1 c      Fetch c from a and dec a.
C!       c a --          Store byte c in address a
C!+      c a -- a+1      Store byte c in a and inc a.
C!-      c a -- a-1      Store byte c in a and dec a.
C,       b --            Write byte b in HERE and advance it.
*!       a al --         Change alias al's addr to a.
**!      a sw --         Change ialias sw's addr to a.
ALLOT    n --            Move HERE by n bytes
CURRENT  -- a            Set a to wordref of last added entry.
CURRENT* -- a            A pointer to active CURRENT*. Useful
                         when we have multiple active dicts.
FILL     a n b --        Fill n bytes at addr a with val b.
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.
MOVE-    a1 a2 u --      Copy u bytes from a1 to a2, starting
                         with a1+u, going down.
MOVE,    a u --          Copy u bytes from a to HERE.

Notes:

~C!: When supplied a non-zero address, sets the SYSVARS+3e (see
     impl.txt) override routine address. This should link dir-
     ectly to assembly code because we call this address. This
     routine shouldn't end with a call to next, but rather a
     regular assembly return. Registers used are arch-specific.
     When supplied 0, unsets override.

# 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
|L          n -- msb lsb    Split n word in 2 bytes, LSB on TOS
|M          n -- lsb msb    Split n word in 2 bytes, MSB on TOS
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
LSHIFT      a u -- c        a << u -> c
RSHIFT      a u -- c        a >> u -> c

Shortcuts: 1+ 2+ 1- 2-

# 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
><   n l h -- f Push true if l < n < h
=><= n l h -- f Push true if l <= n <= h
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

Strings in Collapse OS begin with a one byte length, followed
by the contents of the string.

LIT" x" --         Read following characters and write to HERE
                   as a string literal.
S=      a1 a2 -- f Returns whether string a1 == a2.

# 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)
STYPE    a --     EMIT all chars of string at 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" --        Write xxx to HERE
." xxx" --        *I* Compiles string literal xxx followed by a
                  call to STYPE.
C<?     -- f      Returns whether there's a char waiting in buf.
C<      -- c      Read one char from buffered input.
EMIT    c --      Spit char c to output stream
IN>     -- a      Address of variable containing current pos in
                  input buffer.
IN$     --        Flush input buffer
KEY?    -- c? f   Polls the keyboard for a key. If a key is
                  pressed, f is true and c is the char. Other-
                  wise, f is false and c is *not* on the stack.
KEY     -- c      Get char c from direct input
NL>     --        Emit newline
PC!     c a --    Spit c to port a
PC@     a -- c    Fetch c from port a
RDLN    --        Read a line in IN(
SPC>    --        Emit space character
WORD    -- a      Read one word from buffered input and push its
                  addr. Always null terminated. If ASCII EOT is
                  encountered, a will point to it (it is cons-
                  idered a word).

These ASCII consts are defined:
EOT BS CR LF SPC

KEY? and EMIT are ialiases to (key?) and (emit) (see TTY proto-
col in protocol.txt). KEY is a loop over KEY?.

NL> spits CRLF by default, but can be configured to spit an 
alternate newline char. See impl.txt.

# Disk

BLK>   -- a      Address of the current block variable.
BLK(   -- a      Beginning addr of blk buf.
BLK)   -- a      Ending addr of blk buf.
COPY   s d --    Copy contents of s block to d block.
FLUSH  --        Write current block to disk if dirty and inval-
                 idates current block cache.
LIST   n --      Prints the contents of the block n on screen
                 in the form of 16 lines of 64 columns.
LOAD   n --      Interprets Forth code from block n
LOAD+  n --      Relative load. Loads active block + n.
LOADR  n1 n2 --  Load block range between n1 and n2, inclusive.
LOADR+ n1 n2 --  Relative ranged load.
WIPE   --        Empties current block
WIPED? -- f      Whether current block is empty

# Other

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.
TICKS   n --   Wait for approximately 0.1 millisecond. Don't
               use with n=0.