6.7 KiB
Word reference
Builtins
ARL provides the following builtins by default. Note that while identifier matching is case insensitive, this document shows words in uppercase to make them distinct from arguments.
Stack
Operands | Word | Description |
---|---|---|
DEPTH | Push the current stack size | |
DROP | Discard the first stack entry (same as #1 DROPN ) |
|
DROP2 | Discard the first two stack entries (same as #2 DROPN ) |
|
n | DROPN | Discard the first n stack entries |
DUP | Copy the first stack entry (same as #1 DUPN ) |
|
DUP2 | Copy the first two stack entries (same as #2 DUPN ) |
|
n | DUPN | Copy the first n stack entries |
OVER | Copy the entry behind the first stack entry (same as #1 PICK ) |
|
n | PICK | Copy the nth entry |
n | ROLL | Move the nth entry to the front |
n | ROLLD | Move the front entry to the nth |
ROT | Move the last entry to the front (same as #-1 ROLLD ) |
|
SWAP | Swap the first two stack entries (same as #1 ROLL ) |
Type conversion
Operands | Word | Description |
---|---|---|
val [fmt] | FORMAT | Format number val using format string fmt (or a default format). Format strings are as for mpd_format() ; similar to Python ones. Think "6.2f". |
Variable management
Operands | Word | Suffixes | Description |
---|---|---|---|
val val... | -> | name name... | Assign each val to each name |
Containers
Operands | Word | Description |
---|---|---|
w h | ARRAY | Create a new array with width w and height h |
v A x y | APUT | Put v into array A at x, y |
A x y | AGET | Get x, y from array A |
A | ADIM | Push array dimesions w h |
Control flow
Statements inside control blocks are run in a nested scope. Local variables that already exist on entry are imported into the control scope, but newly created locals go out of scope at the end. For loops, the scope is reused for each iteration, so local variables created on one iteration exist for the next.
The IF statement allows the condition to appear before or after the IF keyword. Specifically, it executes everything between IF and THEN (which may be empty), then pops a condition from the stack.
For both IF and WHILE, be careful to remember that the condition is consumed on evaluation. You may want a DUP.
Also see "Executing programs" below.
Operands | Syntax | Description |
---|---|---|
program | EXEC | Execute program |
from to | FOR var statements END | Execute statements with var set to values from from (inclusive) to to (exclusive), by steps of 1 or -1. |
from to step | FOR STEP var statements END | Execute statements with var set to values from from (inclusive) to to (exclusive), by steps of step. If this does not land exactly on to, stops before going past. |
container | FOR var statements END | Execute statements with var set to each member of container in order. |
[cond] | IF [cond] THEN if-true [ELSE if-false] END | Execute one of up to two blocks depending on the value of cond. |
pgm stack | SAND | Execute program sandboxed on stack and push its error code. |
WHILE cond REPEAT statements END | As long as cond remains true, execute statements. |
System words
The following words are provided by each target. Note that the information stacked by the "display info" (DPYI) and "com port info" (COMI) words is fixed - new words will be added in the future if more information becomes available. In the future, COM port control words to set flow control and baud rate will become available.
Operands | Word | Description |
---|---|---|
DPYI | Push display info to stack. Pushes column count, then row count. | |
str | DPY | Print str (string or char) to the system display |
x y | DPYCUR | Move the cursor to x, y |
DPYCLR | Clear the display | |
COMI | Push com port info to stack. Pushes number of ports. | |
str n | COM | Print str (string or char) to com port n (must be integer) |
MEM | Push amounts of used memory and free memory, after running garbage collector | |
IDLE | Should be called whenever waiting. Allows the system to perform idle tasks. Calls functions registered by TIMER. | |
func ms | TIMER | Configure func to run every ms, rounded up to the nearest system tick interval. If already registered, edit the time duration. If already registered and ms is negative, unregister. |
Executing programs
A program defined by double angle quotes << like this >>
is executed with
either EXEC
or SAND
. For EXEC, this behaves like a function call. For SAND,
it is run in a sandbox: it runs on a stack you supply, any globals it defines
go out of scope at the end, and if any errors are thrown, they are caught and
returned in the form of an integer error code.
TODO/BUG: there are known bugs with this, most importantly #1 (still need to do an audit to make sure this try/catch never leaves interpreter state invalid or leaks memory). Also, the error code definitions are not fixed yet.
As an example, the following script creates a list to use as a stack, then defines a program that pushes three numbers to the stack and divides two of them. It throws a divide-by-zero error. At the end, the error code is displayed, and its stack remains for inspection.
{} (create the stack)
<< #2 #3 #0 / >> (define the program)
OVER (copy the stack so SAND can consume one copy)
SAND
(Now the stack contents are {#2} 10, where 10 is the error code.)
IF DUP THEN
"An error occurred: " PUTS
FORMAT PUTS
'\n' PUTC
ELSE
"No error\n" PUTS
END
(This program prints: "An error occurred: 10" and leaves {#2} on the stack.)
Timers
To create a timer, create a function and register it using TIMER
:
<< "Hello!\n" PUTS >> #1000 TIMER
The registration can be updated or deleted also:
<< "Hello!\n" PUTS >> -> hello_timer
hello_timer #1000 TIMER (Set to 1000ms)
hello_timer #2000 TIMER (Set to 2000ms)
hello_timer #-1 TIMER (Unset)
Functions are called as if by SAND
, and retain their scope and stack across
calls.