Uxntal Notation
The stack-effect notation follows that of the Forth programming language, where each item on the left of the -- spacer is the state of the stack before, and to the right, the state of the stack after. On each side, the right-most item is the last to the pushed and the first to be removed:
@routine ( a b -- a b res ) ADDk JMP2r
Single items are a byte long, and shorts are indicated with a * suffix, the order in which they appear is the order of the stack with the top item to the right:
@routine ( a b* -- b* a ) ROT JMP2r
The dot notation is used to indicate that stack-effects to the right of the dot are happening on the return stack:
@routine ( a . b -- c ) STHr ADD JMP2r
If a routine is a vector, it uses the arrow notation.
@on-event ( -> ) BRK
This notation also holds for macros as well, the notation goes before the macro's body:
%macro ( a b -- res ) {
DIVk MUL SUB }
The stack notation is merely present to help readability but can be altogether disregarded without impacting the program.
Comments
A comment starts with any token beginning with opened parenthesis, and ends at its corresponding closed parenthesis. Comments may be nested, the enclosed comments parentheses must be whitespace separated on both sides.
( ( nested ) ) ( 1+2*(4/3) )
Outermost comments may be named, which means that sometimes the open parenthesis is immediately followed by a word holding some meaning to external tools.
(doc This is a docstring. )
Special comments are sometimes used to group routines together, they are
similar to the pragma mark notation:
( @|Group )
Brackets
The square brackets do nothing, they are used as an aid for readability and formatting, they are useful for making explicit certain things like grouping behaviors, joining literals or indicating lookup tables.
@routine ( -- )
[ LIT2 20 -Console/write ] DEO JMP2r
%min ( a b -- r ) {
GTHk [ JMP SWP ] POP }
@sprite [ 00 66 ff ff ff 7e 3c 18 ]