Skip to content

Standard library glossary

Jump to bottom
0x4646 edited this page Apr 29, 2022 · 15 revisions

Table of contents

Arguments are numbers, strings, registers or a direct stack reference.
The notation of numbers of both inputs and outputs is little-endian by default, opposite of what is standard in english. Should one desire it any different, endianness can be changed (see the set mnemonic and endian register).

Numbers

Numbers can be of any length, and must be a set of decimal digits that may be interrupted by spaces. To input the sign of a number, a minus sign (-) can be placed at the end. The default is positive.
Some examples:
314159265358979,
310771-, 00003 -,
000 000 1
Once again, the notation is little-endian by default, so 00003 is thirty thousand. The place of the sign does not change in the different endiannesses, so in big endian notation mode, -177013 will not be recognized and should be 177013-.
The + character is for quaternions. When a number is printed to the console, it has spaces between the digits.

Strings

A string is internally the same as a number, so it is possible to save them to registers and such. However, instead of 0-9, every digit is ASCII encoded, so arithmetic operations preform on strings what C devs would call 'Undefined Behaviour'.
Inputting a string is done by starting with a double quote character ("), then typing the desired string, and closing it again with a double quote character.
These are the supported escaped characters:

Character ASCII
\0 NUL, Null char
\a BEL, Bell
\b BS, Backspace
\t HT, Horizontal Tab
\v VT, Vertical Tab
\f FF, Form Feed
\r CR, Carriage Return
\n LF, Line Feed
\\ Backslash
\" Quotation marks

Some examples of strings:
"Hello world!\n",
"I am using a DOS system...\r\n",
"This is a null-terminated string.\0"
"A popular quote:\n\"Awawawaw\""
"Boop\a"

Labels

A label starts at the beginning of a line, with :, is alphanumeric (a-zA-z0-9) and can not be more than 10 characters. Some examples:
:L0
:loop1
:END
These are all tokenized when a script is run, and can later be jumped to with jmp. Other than this, they are ignored at runtime.

Registers

Registers are effectively built-in variables and constants, and are divided into three catagories.

Inert

These are all of variable length, are only changed if their name is called specifically, and don't have any effect on other parts of the interpreter's operation.

Register Name Notes
gr1 - gr6 General purpose registers Intended to be used for anything.
ir Index or incrementor register Intended to contain the main iterated value in an iterative loop.
jr Jump register Intended for use with rjmp and rmr, or as a second ir

Integral

Changing these change part of the operation of the interpreter, or how certain instructions behave.

Register Name Notes
inplen Input length Holds the maximum length of statements in scripts and the CLI, as well as for input and sinput.
endian Endianness Holds the endianness of the number representation (0 for little endian, 1 for big endian) used in scripts and the CLI, as well as for input, print, nprint, ston and ntos.
decip Decimal point Holds the position of the decimal point, which is taken into account in mul, div and mod.
path Path Holds the path used for prun.
stacsz Stack size Holds the size of the main and return stacks, changing this register will reset both.
offset Offset Holds the offset referenced by the $ operator.
flag Flag Holds the result of the cmp and ucmp instructions, and pertain to Ce, Cn, Cg and Cs.
loop Loop or not Scripts will loop if this register is 1.

Volatile

These should not be assumed to stay constant between instructions, since they can change without their name being mentioned. Some can not be changed at all.

Register Name Notes
ans Answer Holds the number/string that was returned by the previous statement in the CLI, as well as things printed by print, and the (last) element that was moved by ret.
mstptr Main stack pointer If there are no elements on the main stack, this is equal to stacsz, and grows to zero as the amount of elements on the main stack increases. This register can not be changed directly.
rstptr Return stack pointer If there are no elements on the return stack, this is equal to stacsz, and grows to zero as the amount of elements on the return stack increases. This register can not be changed directly.
ptime Time of previous Contains the time that the previous standard library statement took to execute.
time Time Contains the unix epoch in decimal at the time of calling.
flag Flag Holds the result of cmp and ucmp, is repeated here because it technically satisfied by my definition of a 'volatile register'.

Instruction mnemonics

The first thing in a statement is always the instruction mnemonic (first column). The result of an operation (fourth column) is stored in the first argument (if it is a register), unless stated otherwise.
The second column gives the syntax with expected 'types' for its corresponding instruction mnemonic. The types are:
n: Number
s: String
r: Register

If one of the arguments is expected to be a number or string, a register can always be substituted, unlike if an argument is expected to be a register, in which case replacing it with a number or string results in a no-op, or Undefined Behaviour.

General purpose

Mnemonic Syntax Name Description Returns
set <r>, <n/s> Set Sets the first argument as the second argument The second argument
dget <n/s>, <n>, <n/s> Digit get Gets, from the first argument, the digit at the index given by the second argument, saving it to the third argument. The selected digit
dset <r>, <n>, <n/s> Digit set Sets, in the first argument, the digit at the index given by the second argument to the first digit of the third argument. The first argument with one changed digit
len <n/s>, <r> Length Gets the length of the first argument and stores it in the second argument The length of the first argument
rot <n/s>, <n> Rotate Rotates the first argument by the second argument. The rotated argument
shf <n/s>, <n> Shift Arithmetically shifts (base 10) the first argument by the second argument. The shifted argument
rev <n/s> Reverse Reverses the first argument. The reversed argument
trun <n/s> Truncate Truncates trailing zero's (which are leading in big endian). The truncated argument
app <n/s>, <n/s> Append Appends the second argument to the end (so at the side of the most significant digits) of the first argument. The second argument appended to the first
sel <n>, <n/s>, <n> Selection Selects a region of the second argument, starting at the index given by the third argument and of length given by the first argument. The selected region
cut <n/s>, <n>, <n> Cut Cuts a region from the first argument, starting at the index given by the second argument and ending at the index given by the third argument. The region that was cut out
ins <n/s>, <n/s>, <n> Insert Overwrites the first argument, starting at the third argument, with the first argument. The overwritten first argument
*****************

Arithmetic

Mnemonic Syntax Name Description Returns
inc <n> Increment Increments the first argument by 1. The incremented argument
dec <n> Decrement Decrements the first argument by 1. The decremented argument
add <n>, <n> Addition Adds the two arguments together. The sum of the arguments
sub <n>, <n> Subtraction Subtracts the second argument from the first argument. The first argument minus the second argument
rsub <n>, <n> Reversed subtraction Subtracts the second argument from the first argument, storing the result in the second argument. The first argument minus the second argument
mul <n>, <n> Multiplication Multiplies the two arguments together. The product of the two arguments
div <n>, <n>, <r> Division Divides (integer division) the first argument by the second argument, storing the remainder in the third argument The first argument divided by the second argument
mod <n>, <n>, <r> Modulo Preforms a modulo operation where the second argument is the modulus, storing the division of the first argument by the second argument in the third argument The remainder of the first argument divided by the second argument
*************

IO

Mnemonic Syntax Name Description Returns
print <n/s> Print Prints the first argument to the console, starting a new line afterwards, copying the argument to the ans register. It attempts to correctly guess the type and prints it accordingly. The first argument
nprint <n> Number print Prints the first argument as a number, not starting a new line afterwards. The first argument
sprint <s> String print Prints the first argument as string, not automatically starting a new line afterwards. The first argument
input <r> Input Pauses the program to read user input, as number or string. The number inputted by the user
sinput <r> String input Pauses the program to read user input, as direct keyboard inputs. The user input, as string
fread <n>, <s>, <n> File read Reads a section from the file to which the path is given by the second argument, starting at the position given by the third argument. The length of the read section is equal to the length of the first argument. The selected section from the file, as string
fwrite <n>, <s>, <n> File write Writes the first argument as ASCII string to the file to which the path is given by the second argument, starting at the position given by the third argument. If the third argument is negative, it first truncates the designated file. The first argument, as string
flen <n/s>, <r> File length Gets the length of the file to which the path is given by the first argument and stores it in the second argument The length of the designated file
*************

Logic and Conditional statements

Mnemonic Syntax Name Description Returns
cmp <n>, <n> Signed compare Compares the two arguments. Stores the result in the flag register. 0 if the arguments are equal, 1 if the first argument is the largest, 2 if the second argument is the largest.
ucmp <n>, <n> Unsigned compare Compares the two arguments as if they were unsigned. Stores the result in the flag register. 0 if the arguments are equal, 1 if the first argument is the largest, 2 if the second argument is the largest.
Ce <statement> Condition equal Preforms the statement that follows it when the flag register is 0. Nothing or the result of the statement
Cn <statement> Condition not equal Preforms the statement that follows it when the flag register is not 0. Nothing or the result of the statement
Cg <statement> Condition greater Preforms the statement that follows it when the flag register is 1. Nothing or the result of the statement
Cs <statement> Condition smaller Preforms the statement that follows it when the flag register is 2. Nothing or the result of the statement

Stack control

There are two stacks: The main stack and the return stack. The main stack is meant to be used for temporarily relieving registers so that they can be used for different operations. The return stack is meant to be used to store numbers that will be returned at the end of the script or procedure it is being used in.

Mnemonic Syntax Name Description Returns
push <n/s> Push Pushes the first argument onto the main stack. The first argument
pop <n/s> Pop Pops the number on top of the main stack into the first argument. The number that was popped
peek <r> Peek Copies the number on top of the main stack into the first argument The number on top of the main stack
flip <n> Flip Pops the number on top of the main stack and pushes it onto the return stack. Does this once by default, but first argument amount of times if designated. The number that was popped and pushed
ret <n> Return Pops the number on top of the return stack and pushes (returns) it onto the main stack. Does this once by default, but first argument amount of times if designated. The number that was popped and pushed

ASCII-specific

Mnemonic Syntax Name Description Returns
cton <s>, <n> Character to number Takes the character at the the index given by the second argument and converts it into its decimal representation. The three-digit decimal representation
ntoc <n> Number to character Takes the first three digits of the first argument and converts it to the ASCII character that they represent. The ASCII character
ston <s> String to number Attempts to convert the first argument to a number, according to how arbasm numbers are formatted and the current endianness. The string as number
ntos <n>, <n> Number to string Turns the first argument into an ASCII printable number, according to how arbasm numbers are formatted, and the current endianness. If the second argument is 1, spaces are added between the digits. The first argument as string
********

Flow control

Mnemonic Syntax Name Description Returns
run <s> Run Runs the script the path to which is given by the first argument.
prun <s> Path run Temporarily appends the first argument to the path register and takes that as the path to the script, then runs that script.
jmp <s>, <r> Jump Jumps to the label given by the second argument, saving the address of the next line in the second argument. The address of the next line
rjmp <n>, <r> Return jump (unrelated to the ret stack instruction) Jumps to the address given by the first argument, saving the address of the next line in the second argument The address of the next line
rmr <r> Remember Saves the address of the next line to the first argument. The address of the next line
********

Miscellaneous

Mnemonic Syntax Name Description Returns
rand <r>, <n> Random Generates the second argument amount of random digits The set of random digits
********

Statefiles

A statefile has the .aal extension by convention, and is a binary file that contains the state of the registers and stacks at the time it was made.

Mnemonic Syntax Name Description Returns
SAVE <s> Save Saves the state of the registers and stacks to the file of which the path is given by the first argument. Creates the file if it does not exist, and overwrites it if the file does exist
LOAD <s> Load Loads the state of the registers and stacks from the file of which the path is given by the first argument, overwriting the current state of the registers and stacks.

Direct stack referencing

Using $, any element on the main stack can be referenced directly (if the to-be-accessed element is allocated), instead of only the one on the top.
Its syntax is:
$<n>
It can be used in any place where a number, string or register can be used, since it is substituted by, and points to, whatever element is on the stack at the referenced point.
Regarding the indexing used, $0 is the base of the stack, where mstptr is equal to stacsz, and $stacsz is the very end of the stack, where mstptr is equal to zero (and the stack is full).
At least, that all is the case if offset is untouched. Stack references are made relative to offset, which is initialised as stacsz.
When offset is set to mstptr, $0 points to the top of the stack, and $1- to the element right underneath it. If another element is then pushed on the stack, it can be referenced with $1.
More info about this, and more elaboration regarding the stacks can be found here.

Clone this wiki locally