Text file manual with horrible nonexistant formatting
Get the real one maybe perhaps
It's somewhere on the computer mods discord


Introduction
Metastack is an esolang (esoteric programming language) based on the concept of stacks. A stack is a data structure where data can be pushed to the top or popped from the top. Data can only be accessed from the top of the stack, represented in the debugger as the character with a red background. 
Everything in Metastack revolves around stacks: for example, the instructions given are in a stack where each instruction is popped and evaluated. This stack will from here on be referred to as the ?command stack.? Its ID is 0.
If the command stack is empty or a ? instruction is executed, the program will end, printing its output and also stats.
At any time, there is only one ?working? stack, where instructions will push to and pop from. Some instructions can change the working stack, for example the @ (unconditional change stack) instruction. Other instructions can interact with stacks outside the working one, but we will cover this later.
Tip: If a stack is empty, popping from it will return 0.

First Program: Equality
To understand Metastack better, let us create a program, step by step. This will take three numbers as input, add two of them together, and compare equality with the third, printing ?Equal? if they are equal, and ?Not equal? if they aren?t.
Begin by creating a new file titled ?equal.ms? (if using an external editor, ensure that the encoding is ?UTF-8 without BOM?) and write this into the first line:
@-21
What this will do is change the working stack to the input stack, which is -1. To do this, it pushes 1 and 2 to the stack, and then performs 1 ? 2, which results in -1. Note the character representation of these numbers in the debugger.
So now that we are using the input stack, we will now add together the first two numbers, and then compare equality. At the beginning of the first line, insert:
=+ 
This adds the two numbers on this stack together, and checks if it is equal to the other number on the stack. At the beginning of the first line, insert:
?21
There is a lot to take in here. Let?s take a closer look at that question mark instruction. This is the command if. It allows branching code. It pops three values: a, b, and c. If c is truthy (non-zero), then stack b and the command stack are swapped. If c is falsey (zero), then stack a and the command stack are swapped. Take your time to understand it, as it is the most important instruction in Metastack.
Next, on the second line, insert:
?.....@3
This is the initial state of stack 1. This will change the working stack to stack 3 and prints 5 characters from it into the output. In actuality, these characters are numbers that are converted to their character representation before being printed.

For the third line:
?.........@4
This will change the working stack to stack 4 and print 9 characters from it.
For the fourth and fifth line, insert:
!lauqE
!lauqe toN
Note how this string of characters is reversed. This is due to the nature of stacks, so the last character will be printed, then the second last, third last, and so on. Save the program now.
To run the program, simply type into the shell:
metastack equal.ms [input here]
where [input here] is replaced with the state of the input stack. Don?t worry, this is reversed for you at runtime. For example, this should print ?Equal?
metastack equal.ms 5 3 8
This should print ?Not equal?
metastack equal.ms 7 3 18
Tip: When the program exits, three statistics will be printed as well as the output. These are cycles, size, and area. 
* Cycles is how many instructions the command stack must execute before exiting.
* Size is the amount of instructions at most in the command stack. Fewer instructions equals smaller size.
* Area is the maximum sum of the amount of all numbers in every stack. Smaller stacks across the board equals smaller area.
Tip 2: Numbers can be escaped as text in input using a backslash. Putting \nse as part of input prevents printing of stats at program exit, and \nd disables the debugger. Characters like \10 can be escaped in Metastack programs. \\ escapes a backslash in these cases. Programs that loop infinitely must be viewed in the debugger and may not be launched with \nd.

Instruction Reference
The following pages contain all possible instructions that the command stack can evaluate. Any character or number outside of these are nop instructions (that do nothing when evaluated). Note that some character representations may not be able to be copied and pasted into an actual Metastack program.
Char
Num
Name
Behavior
?
11
Seek bottom
Seeks a value starting from the bottom and moves it to the top. Pop 1: offset from bottom
?
12
Seek top
Seeks a value starting from the top and moves it to the top. Pop 1: offset from top
!!
19
Not not
Turns a truthy value into 1 and a falsey into 0.
?
20
Stack length
Pushes the length of the stack.
!
33
Not
Turns a truthy value into 0 and a falsey into 1.
%
37
Modulo
Pops a and b and pushes the remainder of b/a. If a is 0, pushes 0 instead.
*
42
Multiply
Pops a and b and pushes the result of b * a.
+
43
Add
Pops a and b and pushes the result of b + a.
,
44
Input text
Asks the user for text input, pushing each character as a number onto the input stack.
-
45
Subtract
Pops a and b and pushes the result of b-a.
.
46
Print text
Prints the character representation of a number.
/
47
Divide
Pops a and b and pushes the result of b/a. If a is 0, pushes 0 instead. Note that the result is not rounded down.
0
48
Push 0
Literally pushes the value 0 onto the stack.
1
49
Push 1
Literally pushes the value 1 onto the stack.
2
50
Push 2
Literally pushes the value 2 onto the stack.
3
51
Push 3
Literally pushes the value 3 onto the stack.
4
52
Push 4
Literally pushes the value 4 onto the stack.
5
53
Push 5
Literally pushes the value 5 onto the stack.
6
54
Push 6
Literally pushes the value 6 onto the stack.
7
55
Push 7
Literally pushes the value 7 onto the stack.
8
56
Push 8
Literally pushes the value 8 onto the stack.
9
57
Push 9
Literally pushes the value 9 onto the stack.
:
58
Print number
Prints the number value literally.
;
59
Input number
Asks for a number and pushes it literally into the input stack.
<
60
Less than
Pops a and b and pushes 1 if b < a, else 0.
=
61
Equals
Pops a and b and pushes 1 if b = a, else 0.
>
62
Greater than
Pops a and b and pushes 1 if b > a, else 0.
?
63
Command If
Pops a, b, c. If c is truthy, swap command stack and stack b. Else, swap command stack and stack a.
@
64
Change stack
Pop a and change to stack a.
E
69
Super Eval
Pop x, and pop & push x instructions onto the command stack.
G
71
Grab
Pop a and b, grab the value at position b (from the bottom) in stack a and push it to the working stack.
I
73
Grab input
Grab a value from the input stack, push to the working stack.
\
92
Void
Pop 1 and void it.
_
95
Floor
Pop 1, round it down, then push the result back.
e
101
Evaluate
Pop 1 and push to the command stack.
g
103
Grab
Pop a and b, grab the value at position b (from the bottom) in stack a and push it to the working stack.
i
105
Grab input
Grab a value from the input stack, push to the working stack.
?
182
Stack length
Pushes the length of the stack.
?
191
Stack If
Pops a, b, c. If c is truthy, change the working stack to b. Else, change the working stack to a.
?
236
Clone from
Pop a, clone stack a to the working stack.
?
237
Clone to
Pop a, clone the working stack to stack a.
?
238
Recurse
Pop a, clone from stack a, and push to the bottom of the command stack.
?
239
Clone a to b
Pop a and b. Clone stack a onto stack b.
?
247
Dupe Top
Duplicate the value at the top of the stack.
?
255
Exit
End the program, printing stats and output.



Example program: cat
This program takes its input and prints it back out. It can take input of infinite length and replaces -1 (word endings) with spaces.
?4.?01=-21??02=0?@-21
?111?3.*48
?
?111?3.*48
?4.?01=-21??02=0?


Example program: Truth Machine
This program asks for a number. If the number is falsey, print 0 and exit. Else, print 1 ad infinitum.
?:0?01;@-21
?2:1
?2:1

Example program: Hello, World!
This program prints ?Hello, World!?
?.............
!dlroW ,olleH


Example program: Fibonacci
This program loops forever, printing each number of the Fibonacci Sequence separated by a comma and a space. Well, until number overflow happens.
Note that the male symbol ? does not copy well. Copy and paste the character representation of then number 11 instead.
?2.*48.*4+92:.*48.*4+92:.*48.*4+92:
\1\1\1\1\0
?2.*48.*4+92:?+?0?


Example program: Powers of Two
This program loops forever, printing each power of two, separated by a comma and a space. Well, until number overflow happens. Eventually.
?2.*48.*4+92:?+
\1\1\0
?2.*48.*4+92:?+?


Debugger
By default, the Metastack interpreter runs programs with a debugger, which lets the user view the program step by step, with all stacks exposed. 
The current working stack is represented by having a greater than symbol (?>?) rather than a colon (?:?). 
Stack 0 and stack -1 are rendered specially, being at the bottom and with a different label to show their special meaning.
The output is rendered character-by-character.
The statistics are shown on a single line.
In a stack, there are two special notions of value:
* The number at the top of the stack has a red background color.
* Numbers outside of the character range, eg. 0, whitespace, negative numbers, numbers bigger than 255... are shown with a blue text color and with their number value inside square brackets.
Controls:
* Press the backspace key to terminate the program instantly.
* Press any other key to advance the program by one step. We recommend pressing the shift button, as it will have no effect after the program exits.