COSOL

The Common Stack Oriented Language (COSOL) is a stack based esoteric programming language. It is written in Java and will have the best features of all your favourite esolangs. It is currently being worked on, meaning it is still a work in progress.
== Features ==
* Multiple Stacks
* The informative error Messages of Argh!
* The syntax and intuitivity of BF
* The unnecessary complexity of COBOL (Not the Esolang)
* Pointers (because everyone loves those)
* And much more...
== Stacks and their uses ==
* String Stack: Stores every String in the Program
* Math Stack: Is used to store Numbers and perform mathematical operations on said numbers
* Control Stack: Is used to implement control-flow (only holds ones and zeros)
* Argument Stack: Currently has no use
=== Value formatting ===
* If a number is being defined the following Syntax must be used:
 #your number#
The number is then automatically pushed onto the Math Stack
* If a string is being defined the following Syntax must be used:
 "your string"
The string is then automatically pushed onto the String Stack
* If an argument is being defined, this Syntax must be used:
 $your Argument$
The argument is then automatically pushed onto the Argument Stack
=== The stack index ===
The Stack Index is used by certain instructions to address certain stacks:
* A Stack Index of 0 means, that the String Stack should be referenced
* A Stack Index of 1 means, that the Math Stack should be referenced
* A Stack Index of 2 means, that the Argument Stack should be referenced
* A Stack Index of 3 means, that the Control Stack should be referenced
== Comparisons ==
Operation	Description
= 	Pops the top two values of the Math Stack: If they are equal, push a one to the Control Stack, If not, push a zero
< 	Pops the top two values of the Math Stack: If the first value that was popped is lesser than or equal to the second value, push a one to the Control Stack, If not, push a zero
> 	Pops the top two values of the Math Stack: If the first value that was popped is greater than or equal to the second value, push a one to the Control Stack, If not, push a zero
! 	Pops the top two values of the Math Stack: If they are not equal, push a one to the Control Stack, If not, push a zero
To make a comparison, the Operation must be wrapped in brackets.
In said brackets, no instruction other than the comparison-operators can be executed.
=== Examples of conditionals ===
Would push a one onto the Control Stack, because the values are equal:
 #1# #1# (=)
Would push a zero onto the Control Stack, because the values aren't not equal:
 #1# #1# (!)
This would also be valid syntax:
 (#1# #1# =)
As long as there are at least two values on the Math Stack the comparison will work.
== Loops ==
A loop does the same instructions a given amount of times. In COSOL this is achieved by putting square brackets around the instructions that should be looped, like this:
 [instructios go here]
To set how many times the loop has to iterate, this syntax is used:
 #number of iterations#;[instructions go here]
The semicolon is used to assign the top value of the Math Stack as the number of iterations (Do note that said value is popped off the Stack!)
=== Examples of loops ===
This Example would print the String "Hello World" two times:
 #2#;["Hello World".]
== Labels ==
Labels can be used similarly to functions in other programming languages. Label definitions must be wrapped in curly brackets:
 {instructions go here}
To Assign a Name to the label, this syntax must be used:
 "name of the label":{instructions go here}
The colon pops the top value off the String Stack and uses it as the name of the label.
=== Accessing Labels ===
To jump to a label, this syntax must be used:
 "name of the label"^
And to jump to a label only if a condition is met (meaning that a one is on top of the Control Stack), use this syntax:
 "name of the label"'
=== Examples of labels ===
This is a simple example of a label that, when called prints "hello world":
 "hello-label":{"Hello World".} Defining the Label
 "hello-label"^ Jumping to the Label
== Header files ==
COSOL header files are used to implement labels via other files. This allows COSOL-libraries to exist. To clarify, header files can only contain Label definitions.
To Implement a header file, use this Syntax:
 "Path to your header file"@
=== Header file prefixing ===
To have a more structurized Header file implementation, COSOL offers Header file Prefixing: Every Label in the headerfile would get a specified prefix before being implemented. To implement this in headerfiles, use this syntax:
 "YourPrefix"$
The Resulting Labels will all look like this: "YourPrefix.ActualLabelname". Those labels can be called via the normal call Syntax:
 "YourPrefix.ActualLabelname"^
=== Examples of header files ===
This Headerfile (Saved as "headerfile.cosh"):
 "HelloLabelFromHeader":{"Hello from the header file!".}
Can be implemented and used by using this syntax:
 "Yourpath/Headerfile.cosh"@
 "HelloLabelFromHeader"^
And would then produce this output:
 Hello from the header file!
== Standard Library ==
COSOL offers a standard library to do (currently) the following things:
* File I/O
* Threading
It is directly embedded in the COSOL interpreter and can be implemented by using this syntax:
 "stdlib"@
Do note that no path or file ending must be specified.
== Instructions ==
Instruction 	Meaning
+ 	Pops the top two values of the Math Stack, adds them and pushes the result onto the Math Stack
- 	Pops the top two values of the Math Stack, subtracts them and pushes the result onto the Math Stack
* 	Pops the top two values of the Math Stack, multiplies them and pushes the result onto the Math Stack
/ 	Pops the top two values of the Math Stack, divides them and pushes the result onto the Math Stack
. 	Pops the top value of the String Stack and prints it
< 	Move Values from Stacks to the Stack pointed at by the Stack index
> 	Try to put the top value on the String Stack onto the Math Stack
_ 	Get user input and push it to the String Stack
? 	Clears the entire Stack, selected by the Stack Index
| 	Pops the top value of the Math Stack and sets it as the Stack Index
/ 	Duplicate the top value on the Stack addressed by the Stack pointer
~ 	Flips the top two values on the Stack addressed by the Stack Index
@ 	Pops the top value of the String Stack and uses it as the path to the Headerfile that it will then decode and implement
\ 	Pops the top value of the Math Stack and uses it as an Exit Code to terminate the Program
^ 	Pops the top value of the String Stack and jumps to the label with the same name (if there is one)
' 	Pops the top value of the String Stack and jumps to the label with the same name (if there is one), if the top value on the Control Stack is one
! 	Pops the top value of the Math Stack and jumps to the letter in that position if the top value on the Control Stack is a one
; 	Pops the top value of the Math Stack and uses it as the number of iterations the next loop has to go trough
: 	Pops the top value of the String Stack and uses it as the name for the next label
$ 	(Headerfiles only!) Used to assign a prefix to all Labels in the Headerfile
Any character that isn't already an instruction	Is ignored and can be used as comment
== Errorcodes ==
The informative Errorcodes are one of the key features of COSOL. You may encounter one of the following error Codes.
Code 	Meaning
>? 	Something went wrong with the input the user has supplied
"?":{}	An invalid name has been assigned to a label
ctrl? 	While popping a value off the Control Stack, an error occured
'?' 	An error involving strings occured
¬? 	An error occured while shifting a value to the control stack
#?# 	An error involving numbers has occured
|? 	The Stack Index was out of bounds
{?} 	The Label does not exist
!? 	Something went wrong with the goto-Function (Out-of-bounds goto)
$? 	Bad Header File Prefix
== Examples ==
=== Hello World ===
 "Hello World" Push the Hello World String onto the String Stack
 . Print the top Value of the Stack
=== Truth Machine ===
 "1":{ Define the 1-Label:
 "1". Print the String 1
 "1"^ Jump to the Label 1
 }
 
 "0":{ Define the 0-Label:
 "0". Print the String 0
 #0#\ Exit the Program with the exit code 0 (success)
 }
 _ > Take user input and move it to the Math Stack 
 (#0# =) Compare the user input to a Zero
 "0"' If they are equal, go to the 0-Label
 "1"^ If they are not, go to the 1-Label
=== Cat Program ===
 _ Take user input
 . Print user input
== External Resources ==
* GitHub repository with Implementation
Category:Languages Category:Stack-based