All stas programs starts at the main function. Each function is denoted with the ‘fn’ keyword, then it’s name.

After the name of the function, you have two options.

On the left, is the conventional way to write infix based expressions. You are very likely to be used to this, for good reason.

On the right, is the way to write postfix based expressions. Both examples are equivalent, down to the order of evaluation.

This analogy has been done to death, but nonetheless, here it is.

Think of a stack of plates. You can only operate on those plates but removing or adding upon the uppermost plate.

\_2_/    /-> \_7_/ >-\
\_7_/   /    \_2_/  \_9_/
\_5_/ \_5_/         \_5_/
\_2_/ \_2_/   add   \_2_/
\_8_/ \_8_/         \_8_/

 1-3.                     5.                      7.
        \_2_/                   \_7_/           
 /-       +      -\       /-      /      -+-    \_3_/  
        \_5_/     |             \_2_/     |       *      -\
\_5_/                   \_2_/                   \_2_/     |
\_2_/     4.    \_7_/   \_7_/     6.    \_3_/           
\_2_/           \_2_/   \_2_/           \_2_/           \_6_/

A sequence of operations in an applicative language like C is as follows.

int mul_8(int a) {
	return a * 8;	
}

int div_2(int a) {
	return a / 2;	
}

int add_3(int a) {
	return a + 3;	
}


void main() {
	int a = 99;
	a = div_2(a);
	a = div_2(a);
	a = add_3(a);
	a = mul_8(a);
}

And this is a sequence of operations in a concatenative language like stas.

fn mul_8 1 1 {
	8 *
}

fn div_2 1 1 {
	2 /
}

fn add_3 1 1 {
	3 +
}

fn main {
	99 div_2 div_2 add_3 mul_8
}

See how each output feeds the input of the next function? This is how concatenative languages work.

There is no such thing as a statement, only expressions. Expressions that manipulate the state of the stack.

Don’t have it? Download it from their website.

I recommend to get it from your package manager.

Visual Studio Code users, There is an extension avaliable for stas!

The Visual Studio Code extension supports syntax highlighting. Freely avaliable in the vscodium extension store, or download a copy from open-vsx.

The include keyword followed by path to a file, similar to ‘#include’ in C, will dump the contents of that file into your own files.

String literals are a special case. They don’t work how you would think, instead they push 2 values onto the stack. The lower value being a pointer to the start of the string and the higher value being the length of the string.

The ‘puts’ function accepts the string and it’s length and prints it to stdout.

$ ./stas hello.stas
$ ./a.out
Hello world!

$ ./stas hello.stas -r
Hello world!

The default name for a generated executable is ‘a.out’.

Passing the ‘-r’ switch will cause the stas compiler to execute the file after compilation.

Here are some extra functions and their signatures for printing strings and numbers to stdout and stderr.

The exit function can be used to exit with a code, once called it will never return as the process will be killed.

puts    ; ( str len -- )
eputs   ; ( str len -- )

putu    ; ( num -- )
eputu   ; ( num -- )
putuln  ; ( num -- )
eputuln ; ( num -- )

exit    ; ( code -- )

The most basic form of control flow is the If statement and like everything else, is in a postfix form.

The standard library defines two constants, ’true’ and ‘false’. They can be used with If statements.

Booleans in stas work just like booleans in C. Zero equals false, and any number other than zero is true.

If you’re a bit crafty, you can write conditional loops using this recursive calls.

This is perfectly valid. Even better if the function call is at the end of the function body, which in this example it is, as the function call can be entirely optimised out.

Notice the drop at the end? Stack counts are strictly checked and evaluated during compile time. If you leave unhandled values on the stack in a function that doesn’t return anything, the compiler will ask you to handle them by doing more operations or dropping them off of the stack before a function return.

The while loop, it’s nothing new, but stas has a different way of handling it.

The index is pushed onto the stack at the start of the loop. A conditional clause at the top of the while loop determines if the loop will continue. When the conditional clause ends, it must leave one boolean value on the stack to consume.

Duplicating the index and comparing it to the max index is very similar to a C for loop of this layout.

for (int a = 0 ; a < 10 ; a++);

The ’elif’ keyword is used to chain if statements. It is useless unless next to an If statement.

The constant duplication of the number seems pointless, but I urge you to look closer. If the first If case fails, how will the next one get it’s value to compare?

$ ./stas dum_print.stas -r
Number is two
Number is zero
Number unsupported

Elifs can be chained to other Elifs, or end with an else case at the end.

To avoid unhandled values on the stack, drop the original number off of the stack after all branches.

We need a way to store the total sum and also the current index in the loop.

The index should go first, because the while loop will inspect the top value on the stack.

A while loop will just infinitely loop without updating the index. So now after the index has been moved to the top after the swap, increment it, closing off the loop.

When the while loop ends, the index and sum will be on the stack. The index will be first as it always on top outside of the while body, simply drop it off.

The remaining value is the sum, and you can just print it!