Documentation v2.7

Documentation

Official documentation for the RAM programming language. Please open an issue if you find any bugs, or want some features to be changed or added.

Program Structure

A program should always start with a main: label, defining a block. Blocks are like functions where you can jump anytime using jmp or conditional jumps (see jump reference to learn how to use them). Each label contains a block which is executed when the label is called. The program has a stack which stores integers and there exists some commands to manipulate it.

Variable Reference

The language has 6 general purpose variables (as in x86/arm), 4 global and 4 local dynamic named variables. Global variable's data can be changed and read from within other blocks.

General purpose vars

lx and rv store floating point integers.
string and lxstring to store strings.
vec int and vec str to store integer and string vectors.

NOTE: These variables can be read from any block but cannot be modified without jumping back to the block in which the user wishes to modify the value of the variable.

Dynamic Global vars

These variables are called global_var. There can be unlimited number of these named variables, restricted to types like string, integer, integer vector and string vector. You can move values from these vars to general purpose vars for further operations.

NOTE: These variables are truly global. They can change from a block without calling any jump statements.

Dynamic Local Vars

They are simply called var, and are readable and writable only in the block which declares them. But they can also be passed to other blocks/functions as parameters.

General Commands

comments

// this is a one line comment

print

print prints the last number on the screen present in the stack.
print lx/rv prints the value of lx/rv variables on the screen.
print string/lxstring prints the value of string/lxstring variables on the screen.
print vec str/vec int prints the value of vec str/vec int variables on the screen.
print global_var <var> str prints the value of str_var variable on the screen.
print global_var <var> int prints the value of int_var variable on the screen.
print global_var <var> str vec prints the value of str_vec_var variable on the screen.
print global_var <var> int vec prints the value of int_vec_var variable on the screen.
print var <var> str prints the value of str_var variable on the screen.
print var <var> int prints the value of int_var variable on the screen.
print var <var> str vec prints the value of str_vec_var variable on the screen.
print var <var> int vec prints the value of int_vec_var variable on the screen.

printc >> characters

Prints the characters specified on the screen

halt

halt stops the program

std commands

stdin

stdin lx/rv/string sets the value of the standard input provided in the next line to the specified variable.

stdfs

stdfs open >> ./path/to/file opens the file and stores the contents as strings in the string variable.
stdfs open string/lxstring opens the file from string/lxstring and stores the contents as strings in the string variable.

rand >> num1,num2

rand >> num1,num2/lx,rv/rv,lx generates a random decimal between num1 and num2 (including both) and pushes it to stack. May round be used after this statement to round it to an integer.

parse

parse int lx/rv string/lxstring parses string/lxstring and stores in lx/rv.

stack based commands

ram

ram <number> adds the number to the stack.
ram lx/rv <number> assigns the number to the variable
ram lx/rv adds the variable value to the stack for further calculations
ram lx/rv prev assigns the last stack value to the specified variable.
ram string >> <strings> assigns value to the strings global variable.
ram global_var <name> adds the int global_var value to the stack.
ram global_var <name> prev assigns the last stack value to the specified global int variable.
ram var <name> adds the int var value to the stack.
ram var <name> prev assigns the last stack value to the specified var int variable.

vectors

ram vec int >> [1,2,3,4,ints...] creates a vector and assigns it to the global vec int variable.
ram vec str >> [1,2,3,4,strs...] creates a vector and assigns it to the global vec str variable.
vec str push pushes the value of string to vec str variable.
vec int push lx/rv pushes the value of lx/rv to vec int variable.
vec str >> [<index>/lx/rv] extracts value of the index position of vec str and stores it in the string variable.
vec int lx/rv >> [<index>/lx/rv] extracts the value of the index position of vec int and stores it in lx/rv variable.
vec str len pushes the length of the vec str variable to the stack.
vec int len pushes the length of the vec int variable to the stack.
vec int pop pops the last item from the vec int.
vec str pop pops the last item from the vec str.

split

split >> "<arg>" splits the string variable into args and stores the values into the vec str

str

str lxstring string moves the value of the string variable to lxstring.
str string lxstring moves the value of the lxstring variable to string.
str cmp compares the variables lxstring & strings and pushes 0 to the stack if they are equal, and -1 if they are not.

pop

pop Removes the last value from the stack
pop <n> Removes the last n values from the stack

popall

Empties the entire stack. Useful for avg implementation.

Vars

var (local)

var <name> str >> test123 creates a variable called name with string type and assigns "test123" to it.
var <name> int >> 75 creates a variable called name with integer type and assigns 75 to it.
var <name_vec> int vec >> [10, 13, 12] creates a variable called name_vec with vec integer type and assigns [10, 13, 12] to it.
var <name_vec> str vec >> [one,two] creates a variable called name_vec with vec integer type and assigns [one,two] to it.
var <name_vec> str vec push >> string/lxstring/var <name> pushes string/lxstring/<name> into the <name_vec> variable.
var <name_vec> int vec push >> lx/rv/var <name> pushes lx/rv/<name> into the <name_vec> variable.
var <name_vec> int vec lx/rv/var <name> >> [lx/rv/var name/<number>] stores the [index] value of <name_vec> into the specified variable.
var <name_vec> str vec string/lxstring/var <name> >> [lx/rv/var name/<number>] stores the [index] value of <name_vec> into the specified variable.
var <name_vec> str vec len -> pushes the length of str <name_vec> into the stack.
var <name_vec> int vec len -> pushes the length of int <name_vec> into the stack.

global_var (global)

global_var <name> str >> test123 creates a variable called name with string type and assigns "test123" to it.
global_var <name> int >> 75 creates a variable called name with integer type and assigns 75 to it.
global_var <name_vec> int vec >> [10, 13, 12] creates a variable called name_vec with vec integer type and assigns [10, 13, 12] to it.
global_var <name_vec> str vec >> [one,two] creates a variable called name_vec with vec integer type and assigns [one,two] to it.
global_var <name_vec> str vec push >> string/lxstring/var <name> pushes string/lxstring/<name> into the <name_vec> variable.
global_var <name_vec> int vec push >> lx/rv/var <name> pushes lx/rv/<name> into the <name_vec> variable.
global_var <name_vec> int vec lx/rv/var <name> >> [lx/rv/var name/<number>] stores the [index] value of <name_vec> into the specified variable.
global_var <name_vec> str vec string/lxstring/var <name> >> [lx/rv/var name/<number>] stores the [index] value of <name_vec> into the specified variable.
global_var <name_vec> str vec len -> pushes the length of str <name_vec> into the stack.
global_var <name_vec> int vec len -> pushes the length of int <name_vec> into the stack.

move

Move is used to move the value of vars to general purpose vars and vice versa (note its destination first).

move int lx/rv = var <name> moves the value of name variable to lx/rv (make sure name is of int type)
move str string/lxstring = var <name> moves the value of name variable to string/lxstring (make sure name is of str type)
move str var <name> = string/lxstring moves the value of string/lxstring to name var (make sure name is of str type)
move int var <name> = lx/rv moves the value of lx/rv to name var (make sure name is of int type)
move vec vec str = var <name> moves the value of name var to vec str (make sure name is a string vector)
move vec vec int = var <name> moves the value of name var to vec int (make sure name is a integer vector)
move vec var <name> = vec int moves the value of vec int to name var (make sure name is a integer vector)
move vec var <name> = vec str moves the value of vec str to name var (make sure name is a string vector)

Operation Commands

add

adds last two numbers in the stack and pushes the result to the stack
add lx rv adds the two variables and pushes the result to the stack

sub

subtracts the last number from the number added prior to it and pushes to stack

mul

mul multiplies the last two numbers in the stack and adds the result to the stack
mul rv lx multiplies lx and rv and pushes the result to the stack.

div

the number added prior to the last number / last number and pushes to stack.

sqr

sqr squares the last number in the stack and adds the result to the stack.
sqr lx/rv squares lx/rv and assigns the result to the variable squared.

sqrt

sqrt squares the last number in the stack and adds the result to the stack.
sqrt lx/rv squares lx/rv and assigns the result to the variable squared.

avg

Takes out the average of all the numbers present in the stack. popall should be used somewhere in the code to remove the vars which are redundant.

round

round rounds the last number present in the stack to decimals and pushes it to the stack.
round lx/rv rounds the specified variable and assigns the result to the var itself.

`cmp` and Jump statements

The program is devided into labels and we can jump on any label to execute the code block below it.

main:
    ram 100
    ram 300
    cmp
    jne not_equal:
    cmp
    je equal:
    
 not_equal:
    printc >> Not Equal
    
equal:
    printc >> Equal

The main: label is considered compulsory at the beginning of the program.

jmp <label:> - jumps to the label
cmp pushes -1, 0, 1 to the stack if the previous number smaller, equal or greater than the number after it in the stack.

main:
    ram 10
    ram 20
    cmp
    print
    // this will print -1 as 10 < 20

jne <label:> - jumps to the label if the previous cmp statement is not 0 (not equal)
je <label:> - jumps to the label if the previous cmp statement is 0 (equal)
jgr <label:> - jumps to the label if the prev cmp statement is 1 (greater)
jsm <label:> - jumps to the label if the prev cmp statement is -1 (smaller)

Imports

Imports are restricted only to the main file. You can import as many files you want using include <filepath> and then you shall be able to call all the codeblocks associated with the file.

// main.ram

include "ok.ram"
main:
    printc >> hello from main
    jmp test:

// ok.ram
test:
    printc >> hello from ok.ram

Example Coin Flip

main:
    printc >> Coin Flip
    rand >> 0,1
    round
    ram 1
    cmp
    je heads:
    pop
    ram 0
    cmp
    je tails:

heads:
    printc >> Heads

tails:
    printc >> Tails