nyl

A stack-based concatenative programming language.

Datatypes

• i64
• byte
• string
• array
• null

Language

• i64s are written as expected
• bytes start with # and written in hex: #3b
• strings are double-quoted: "hello there"
• builtin words are all uppercase (may end in ?): ADD, CONCAT, EQU?
• arrays are wrapped in brackets and whitespace-delimited: [ 1 2 3 ]
• labels start with @
• jumps start with !
• calls start with %
• reading from memory address names starts with *
• storing values into memory addresses starts with &
• anonymous labels are curly brackets
• comments start with ; and go to the end of the line
• include libraries with > and the library file name: >string.nyl

Built-in Words

Stack manipulation

Word	Example	Result	Description
DUP	1 DUP	1 1	Duplicates the top value
SWP	2 1 SWP	2 1	Swaps the top two values
POP	1 POP		Removes the top value
NIP	2 1 NIP	1	Removes the second value
ROT	3 2 1 ROT	2 3 1	Rotates the top three values
OVR	2 1 OVR	2 1 2	Copies the second value to the top

Math

Math operators wrap. #ff #01 ADD equals #00. Operations involving integers and bytes will return integers.

Word	Example	Result	Description
ADD	2 1 ADD	3	Addition of the top two values
SUB	1 4 SUB	3	Subtraction of the top two values
MUL	2 3 MUL	6	Multiplication
DIV	2 8 DIV	4	Integer division
MOD	2 9 MOD	1	Modulo
BYTE	215 BYTE	#d7	Converts the top value to a byte

Bitwise operations

Only on bytes.

Word	Example	Result	Description
XOR	#f2 #d9 XOR	#2b	Bitwise XOR
AND	#b4 #35 AND	#34	Bitwise AND
OR	#f2 #d9 OR	#fb	Bitwise OR

Strings

Word	Example	Result	Description
CHR	#6d CHR	"m"	Unicode code point to string
COCNAT	"a" "b" CONCAT	"ba"	String concatenation
FORMAT	[ "dude" ] "hi %" FORMAT	"hi dude"	String interpolation
PRINT	">>> " PRINT		Print string to stdout
PRINTLN	"Hello!" PRINTLN		Print string to stdout with newline
READLN	READLN	"..."	Read line from stdin
SPLIT	"hi"	[ "h" "i" ]	Split a string into an array

Arrays

Word	Example	Result	Description
APUSH	2 [ 1 ] APUSH	[ 1 2 ]	Push a value onto an array
APOP	[ 1 2 ] APOP	2 [ 1 ]	Pops the last value off an array
APOPF	[ 1 2 ] APOPF	1 [ 2 ]	Pops the first value off an araay
ACOUNT	[ "a" "b" ] ACOUNT	2 [ "a" "b" ]	Pushes an array's size onto the stack
AGET	1 [ "a" "b" ] AGET	"b" [ "a" "b" ]	Pushes the nth value of an array
ASET	"c" 1 [ "a" "b" ] ASET	[ "a" "c" ]	Sets the nth value of an array

Flow control

Word	Example	Result	Description
EQU?
NEQ?
LTH?
GTH?
NULL?
JMP

Memory

Word	Example	Result	Description
LOAD
STORE

Other

Word	Example	Result	Description
DBG
ARGV
EXIT

Notes

• Array literals can only be written with literal values.

• There is no literal null value. If you need a null value, you can read from an uninitialized memory slot. It is customary to read from *null (being careful, of course, to never write to it). Alternatively, if you are averse to being careful, you can use [ ] APOP NIP.

• Curly braces create a label at the closing brace and an immeidate jump to that label at the opening brace. They are useful with the control flow operators. By putting the opening brace immediately after a test, execution will jump to the closing brace if the test succeeds. If the test fails, the jump is skipped:

    1 2 EQU? { "Math still works" PRINTLN }
    ;; This will print a comforting message because the test failed.
    ;; The jump to the closing bracket will be skipped.