Stekovaya Tutorial

Stekovaya is a stack based language. It is very light weight but also very versatile.

Hello World

Let's start with a simple hello world program.

index.stk

STR Hello World! END MSG

Congratulations! You've made a major step in understanding Stekovaya.
In this simple example, we've added a string (Hello World) and terminated with END. We've also popped it off of the stack and printed it to the console using MSG.

Comments

Let's make our example easier to read by adding some comments. REM is a key word reserved for adding comments.

index.stk

STR Hello World! END MSG
REM Push Hello World! to the stack and pop it off to print to the console.

If REM is a hard keyword to memorize for comments, think of it like REMembering something to write down.

Numbers

We can also work with numbers. Simply typing numbers will push them to the stack.

index.stk

1 2 7 3

Booleans

Booleans are basically true or false. In Stekovaya, a true is a 1 and a false is a 0. We'll review this concept more when we look at comparison operators.

Variables

Variables are an easy way to store values. There are two types of variables in Stekovaya: constant and changeable. Both variable types can be declared with DEF.
Let's start with a changeable variable. As the name suggests, the values of these variables can be changed.

index.stk

STR message END STR Hello World END DEF

What are we doing here? First we define an identifier called "message", which is terminated with END. We assign "message" a value of "Hello World" in a similar fashion, ending it with DEF. We can use this variable later on like so:

index.stk

STR message END STR Hello World END DEF
message MSG
REM we define a "message" variable and then print it to the console.

There are also constant variables. The values of these variables cannot be changed. In order to define a constant variable, simply add an underscore _ to the beginning of the variable name.

index.stk

STR _message END STR Hello World END DEF
REM the value of _message cannot be changed.

The Stack

So far, we've reviewed the MSG command, which prints the top of the stack to the console. We can also print the entire stack to the console using STK, which can be useful for debugging.

index.stk

1 2 7 3 STK
REM outputs STACK<4> 1 2 7 3 to the console

The other method to print to the console is DMSG. This method is special in that it does not alter the stack, it simply logs the top of the stack (MSG logs and pops the top of the stack). DMSG is used in the exact same way as MSG.

index.stk

1 DMSG
REM outputs 1 to the console without popping the stack

Operators

Stekovaya does not use the common operators you might expect, as it revolves around a purely stack based programming language. Let's start by learning how to perform simple math.
We can add, subtract, multiply, and divide fairly inuitively using ADD, SUB, MUL, and DIV.

index.stk

5 2 ADD MSG

In this example, we simply add the two numbers at the top of the stack and log it to the console. As mentioned earlier, the rest can be done in the same way.
For clarity:

index.stk

5 2 SUB MSG
REM outputs 3 to the console
5 2 MUL MSG
REM outputs 10 to the console
5 2 DIV MSG
REM outputs 2.5 to the console

Other Math

We can also calculate other mathematical operations with some useful functions. The first is POW, which raises the second value of the stack to the first stack power.

index.stk

2 5 POW MSG
REM outputs 32 to the console

We are effectively raising 2 to the 5th power (2 ^ 5). Like POW, we can also take roots of values using ROT. This is also the same as taking a value to the 1/n (where n is a real number).

index.stk

2 4 ROT MSG
REM outputs 2 to the console

Here, we take √4, or 4 to the 1/2 power.

Comparisons

In other programming languages, you might expect to see > or <=. Stekovaya uses key words to perform similar actions.

index.stk

5 2 LSS MSG
REM equivalent of 5 < 2
REM outputs 0 for false

LSS is used as the less than comparison operator. In order to log the result, we use MSG. The others are fairly self explanatory, so let's go over them quickly.

index.stk

5 2 LEQ
REM equivalent of 5 <= 2, checks if 5 is less than or equal to 2
5 2 GTR
REM equivalent of 5 > 2, checks if 5 is greater than 2
5 2 GEQ
REM equivalent of 5 >= 2, checks if 5 is greater than or equal to 2
5 2 EQU
REM equivalent of 5 == 2, checks if 5 is equal to 2
5 2 NEQ
REM equivalent of 5 != 2, checks if 5 is not equal to 2

Remember, 0 is false and 1 is true. To log the results of comparisons, you can use MSG or DMSG

Loops

There is only one kind of loop in Stekovaya, the FOR loop. Initializing a loop is easy. Simple start a loop with FOR and end it with EFOR For instance, the example below infinitely logs "Hello World!" to the stack.

index.stk

FOR
STR Hello World! END MSG
EFOR

In order to terminate or break from a loop, you must use BRK.

Do Nothing

While it seems like useless filler, you can also choose not to do anything with the stack.

index.stk

EMP
REM nothing happens

Exiting Program

You can exit a Stekovaya program with either EXT or ERX. EXT exits the program with a status of 0, where as ERX exits with a status of 1.

index.stk

EXT
REM exit status 0
ERX
REM technically this won't run, but if it did it would exit with status 1.

Thanks @AdCharity for write markdown!