Stax: An Esoteric Programming Language Made by Cameron!

Stax is an interpreted esoteric programming language written in JavaScript for the browser. It took roughly 19 hours of work time to complete. This is the complete documentation of Stax.

Basis:

Stax was made under insiration of having not just one or a few stacks for an entire language, but as many as you want, treating them similarly to arrays, but if you could only get the top value of an array. There are 2 main priciples that Stax stands on, One is that you can create an infinite amount of your own stacks filled with data that you choose. Two is it's english like nature, it's easy to read and remember code should not be foriegn to any english speaker. Wrapping up this section I want to say that Stax is the first programming language I've ever written!

Stacks:

A stack in Stax is an object, the only object in the language, that may be created by the programmer and can be used to both read and write data to the stack. When creating, or assigning as stack, you will give it a name and a data type. There are 3 data types in Stax, they are 'Number', 'String', and 'Boolean', these help keep the structure of the code and allow easy reading. The name of your stack will act as a variable for the top most value of the stack as well as a reference to the stack itself, it's dependant on the context in which it is used. When reading the stack, it will act as a variable for the top most value in the stack, however when writing to the stack it will act simply as a reference to what stack you're writing to.

Screen Panels:

In my officially made web interpreter of Stax there are 3 'panels'. These are the code editor, the output console, and the stack visualizer. The code editor is where Stax code will be written and upon running will be interpreted, it is a simple textarea with some fancy css styling. The output console is used for receiving error messages tailored to help debug your code, and also for printing data. The output console is cleared when the code is ran, and will fill up as the code executes. Finally we have the stack visualizer, it allows you to see your stacks, their names, their data types, and all of the data stored inside of them, top most values on top. I first made it as a debugging tool but found that it gives a lot of charm to the Stax experience when running on slow interpret mode.

Buttons:

In my web interpretation of Stax, there are 2 buttons. One button is the Play and Stop Code button, it will be gray when no code is running, and sepia when code is running. You will be able to click it when it is sepia to stop the code, and click it again to re run the code. The other button is the Slow Interpret Mode button, when sepia (or on) it will see that code executes line by line at 1 line per 25 milliseconds. When gray (or off) the Stax code will attempt to run instantly, the power of your interpreter and or your machine will affect how fast the process is. More often than not, you will only have the option to stop your code by pressing the Play/Stop Code button when Slow Interpret Mode is sepia because when it isn't my interpreter either completes the code instantly or slows down to the point where the button does nothing.

Commands:

In Stax, every line will start with a valid Stax command, or a method. Regardless of if the command is used for logic, value reading or writing, data control, looping, or just commenting code all commands are called methods. This is because they all take up the first word of every line, and based on that word, perform an action.

Methods:

There are a total of 12 methods, with these 12 methods you will do everything that there is to do in this programming language. They are as follows: 'assign', 'push', 'pop', 'print', 'pass', 'until', 'input', 'if', 'end', 'add', 'sub', and 'bury'.

Assign:

'assign' is the method that will create a stack, or multiple stacks, of a data type. It will take in a number of names, and a data type, and create a stack of the data type you put for every name you gave it.

`assign myStack to String` Will create a String stack named 'myStack'

`assign myStack1 myStack2 myStack3 to Number` Will create 3 Number stacks, named 'myStack1', 'myStack2', and 'myStack3'

`assign trueOrFalseStack to Boolean` Will create a Boolean stack named 'trueOrFalseStack'

Push:

'push' is the method that will both add a value to a stack, or multiple stacks, and specify what the data in the value should be. Data types must be noted, in some cases it will be converted correctly, however "Hello World" can not be converted into a number value for example. When pushing data into a stack, you will give it that data directly after the push command. When a String, you may type whatever you like, spaces, quotes it does not matter it will be put into the stack. When the data type is a number you may type in a single number, but when multiple numbers are put in with spaces seperating them, they will be added and their sum will be pushed to the stack. When the data type is Boolean only "true" or "false" values will be accepted. You are also able to call stack values instead of inputing values directly, in some cases data type conversion can happen, but if it is not possible you will receive an error in your output console.

`push Hello World! to myString` Will put the string data 'Hello World!' into a new and top most value of the stack 'myString'

`push 69 to myStack1 myStack2 myStack3` Will put the number data '69' into tables 'myStack1' through 'myStack2' assuming they've been assigned as Number stacks.

`push true to trueOrFalseStack` Will put the boolean data 'true' into the stack 'trueOrFalseStack' assuming it has been assigned as a boolean stack.

`push myStack1 to myStack2` Will put the value of the stack 'myStack1' into the top most value of 'myStack2'

Pop:

'pop' is the method used to remove the top most value from a stack, it will also put a copy of that value into any number of other stacks if specified. Data conversions will happen when allowed, otherwise an error will be put into the console.

`pop myString` Will remove the top most value of the stack 'myString' and delete it.

`pop myStack1 to myStack2 myStack3` Will remove the top most value from the stack 'myStack1' and will then copy and add that value to the top of stacks 'myStack2' and 'myStack3'

Print:

'print' is a basic print method with a single limitation, it can only print stack data. You can print a stack, but you can not print stray data, you may also concatenate stacks without worry of data conversion in print simply by stating the stacks you would like to concatenate after stating the print method seperated by spaces.

`print myString` Will print the contents of whatever the top most value in the stack 'myString' is. It's worth noting that if there is nothing in 'myString' and error will be thrown.

`print myStack1 myStack2 myStack3` Will print the contents of the top most value of the stacks 'myStack1' through 'myStack3' assuming they all have values. Their data will be printed, seperated by spaces.

Pass:

'pass' is the most basic method in the language, it is just a line comment! It must be used at the start of the line, and will make the interpreter ignore that line.

`pass This is a code comment! :D`

Until:

'until' is this languages only loop method. It is not similar to a for loop or a while loop. Instead it works as a sort of anti-while loop. It will loop the code block inside (denoted by the 'end' method) until the conditional is true, once it is it will break out of the loop, rather than looping until it's false like a while loop. 'or' and 'and' conditionals apply. The until loop is formatted as 'until conditional do' the do at the end is required. The conditional will have an 'is' statement, which is this languages form of a double equals sign. More on conditionals later.

`until myStack is 1 do` Will first find where it is supposed to end, denoted by the following, or out nested end method, and from there will test the conditional. Should in this case 'myStack's value be equal to 1 it will skip that code block and run immediately to the end it found. If it is false however it will run the conditional and when it reaches the end it will test the conditional again.

`until 1 is 1 and 2 is 1 and 3 is 1 do` Will loop until 3 and 2 and 1 are all equal to 1, which will never be the case, so this will be an infinite loop. This demonstrates and conditionals.

`until 1 is 1 or 2 is 1 or 3 is 1 do` Will loop until either 3 or 2 or 1 is equal to 1, since 1 is equal to 1 this loop will never begin and will skip. This demonstates or conditionals

Input:

'input' is a method used for getting user input. When using it, you will use the input method at the start, and then after that you will specify all of the stacks that you want to add input to. It will go through all stacks specified one by one asking the user for input to put into the top most value of the stack, note that this will not push a value onto the stack, it will only set the current top most value to it. Some data conversion is possible, but if it isn't an error will be thrown in the output console.

`input myStack` Will pause the code at this line and wait for the user to give input, after which it will set the top most value of 'myStack' to the input data.

`input myStack1 myStack2 myStack3` Will pause the code at this line and wait for the user to give input. It will request the users input 3 times one after another upon submiting each one. The stacks' top most value will be set to the input in the order they are given.

If:

'if' is the other conditional based method, however it does not loop like 'until'. 'if' will only find it's corrosponding 'end' line and then text the conditional once. If it is true it will perform the code block but if it is false it will skip the code block.

`if 1 is 1 do` Will state true, therefore it will run the code block.

`if 1 is above 0` Will state true, 'above' and 'below' are synonymous with '>' and '<' in most other languages, they always go after the 'is'.

End:

'end' is technically a conditional, but only for 'until' loops and instead of having an end just take the code back up to the until line just to test the conditional again, the end will test the conditional for the until and if true will do nothing and carry on, if false will jump back up to the until loop. End is also used to end if statements, until and if statements do not contradict each other, and can be nested indefinitely. End is at it's core, the end for a code block, denoted by either an if or an until line.

`end`

Add:

'add' will take a number and than any number of stacks to perform that action with. Assuming the stack is a Number stack, it will take the top most value and add whatever number you tell it to to it. It will do this for all stacks that you insert as you can tell it to add the same number to multiple different stacks, or just one.

`add 5 to myStack` Will take the top value you 'myStack' and add 5 to it assuming 'myStack' is a Number stack, and that there is a top value to be read.

`add 5 to myStack1 myStack2 myStack3` Will take the top values of all 3 stacks specified and add 5 to each of them assuming all conditions are met.

Sub:

'sub' is a method exactly opposite to 'add'. Instead of adding a number to a stack or stacks, it will subtract a number from a stack or stacks. It's worth noting that negative numbers are possible but all numbers are whole and can not be decimal numbers.

`sub 5 from myStack` Will take the top value you 'myStack' and subtract 5 from it assuming 'myStack' is a Number stack, and that there is a top value to be read.

`sub 5 from myStack1 myStack2 myStack3` Will take the top values of all 3 stacks specified and subtract 5 from each of them assuming all conditions are met.

Bury:

'bury is a method that will allow you to pop the top value of a stack or multiple stacks, and put it at the bottom of those stacks, in effect allowing you to shuffle through stacks effortlessly.'

`bury myStack` Will take the top value of 'myStack' and put it on the bottom, pushing all other values up.

`bury myStack1 myStack2 myStack3` Will take the top value of all of the stacks specified and put them all on the bottom of their stacks, pushing all other values up.

Syntax:

As you've probably noticed there are several combining words in this language that most other languages would use special characters for. Here's a list of them: 'to', 'from', 'do', 'is', 'or', and 'and'.

To:

'to' is used in the 'add' method, and in the 'push' and 'assign' methods. It is a combining token that refers to taking the value on the left, and putting it into, or making it, the value on the right. In assign it is used to tell Stax what data type you want your stack to be. In push it is used to tell Stax what stack or stacks you want to push certain data to. Finally in add it is used to tell Stax what stack or stacks you want to add the value to.

From:

'from' is only used in the 'sub' method, and is used similarly to 'to' in that it will take the value on the left, and put it into the stack, or stacks on the right.

Do:

'do' is a conditional phrase. It is used in the 'until' and 'if' methods. It is used after a conditional and will run the code block denoted by the corrosponding 'end' method.

Is:

'is' is synonymous with the `==` opperator in most other languages. It will simply test if the value on the left is equal to the value on the right. It can only be used in conditional statements and methods.

Or:

'or' will act simply as an or in a conditional. It will return true if either the conditional on the right returns true or the conditional on the left returns true. It can not be combined with and 'and' opperator.

And:

The 'and' opperator will act simply as an and in a conditional. It will return true only if the conditionals on both the left and right of it also return true. Like the 'or' opperator it may be used with itself any number of times, but can not be used with an 'or' opperator.

Above:

This opperator will allow you to test if a number is above another number. It is used directly after 'is' in if statments and until loops.

Below:

This opperator will allow you to test if a number is below another number. It is used directly after 'is' in if statments and until loops.

Not:

This opperator will allow you to test if a value is not another value. It is used directly after 'is' in if statements and until loops.