Terrain

Terrain is an esoteric programming language by Grs (talk) that's meant to resemble (somewhat) natural looking terrain. It's written as text, though, so it could be considered as an ASCII drawing (or multiple) too.
== Code structure ==
The code consists of ASCII drawing(s) of terrain and flowers. It consists of |, /, \, _ and X characters and spaces for alignment. The different changes in height determine the commands and possibly other data. However, the code doesn't have to be as a single terrain parts. There can be multiple in a file under each other. However, each must be the same height (each has to have the same number of lines). In these terrain parts, there can be empty lines without code. But if there are multiple terrain parts, these empty lines can be mandatory.
If there are multiple terrain parts under each other, they will be executed like if they were one single terrain part, top to bottom.
Spaces can be used to align the above mentioned characters in the lines.
If there are lines that have some of those characters but don't end in one of them, you don't have to type spaces until the end of the line.
All other characters than |, /, \, _, X and a space are treated as spaces, except tabs. Tabs are treated as 4 spaces.
=== Flowers ===
Flowers are drawn like this above ground:
 X X X
 | | |
 __________
Or simply just like this above ground:
 X X X
 __________
Flowers cannot be drawn above any thing else other than _.
=== Terrain character alignment ===
Aligning terrain pieces means that the characters kind of make a line appear.
Rules:
* If there are two | next to each other, they are aligned like this:
 |
 |
* If there are two / next to each other, they are aligned like this:
 /
 /
* If there are two \ next to each other, they are aligned like this:
 \
 \
* If there are two _ next to each other, they are aligned like this:
 __
* / and _ (2 cases)
 _/
 _
 /
* _ and \ (2 cases)
 \_
 _
 \
Note: As you can see, some of these take up 2 lines, while some only take up 1 line. This can influence the change in height.
* / and \ (2 cases)
 /\
 \/
* / and | (2 cases)
 /
 |
 |
 /
* \ and | (2 cases)
 \
 |
 |
 \
* _ and | (4 cases)
 _|
 |_
 _
 |
 _
 |
Any other combinations are not allowed and an exception will be thrown.
=== Change in height explanation ===
Changes in height determine the commands and possibly other data.
The change in height is determined in the following way.
1. Go forward until you hit a |, / or a \.
2. Count how many lines do you have to go up or down to hit at least 5 _ characters in a row (_____). Count upwards movement as +1 and downwards movement as -1.
3. The number you got is a change in height. It's a sum.
==== Examples ====
Thus this terrain part has a height change of 5:
 _________ 5
 / 4
 / 3
 / 2
 / 1
 _________/ 0
This also has a height change of 5:
 _________ 5
 / 4
 ___/ 3
 / 2
 / 1
 _________/ 0
This also has a height change of 5:
 _________ 5
 / 4
 ___ / 3
 / \ / 2
 / \____/ 1
 _________/ 0
This has a change of -2:
 _____ 0
 \ -1
 \ _____ -2
 \ /\ / (-3)
 \ / \_/ (-4)
 \____/ (-5)
Note: By the way, you don't have to write out those numbers when coding.
Multiple of these "changes in height" can be "chained" together.
Example:
 _____
 __ / \ ___________
 \ / \________/
 \_____/\__/
=== Where changes in height start and end? ===
Every change in height (thus commands and possibly other data) ends at _____ and those characters are in the command too. The characters directly after these count to the next command. The first some characters are always included in the first change in height, even if these characters are _____.
==== Example ====
In the example, < and > determine the start and the end of changes in height. The characters under < and > are also included in the specific change in height. The numbers are the change in height. -4 means 4 lines down in total. 8 means 8 lines up in total.
 < -4 >< -2 >< 1 >< 2 >< 8 >< -3 >< 1 >< -1 >
 _____
 / \
 / \ _____
 / \_____/ \_____
 /
 _ /
 \ /
 \ /
 \ _____/
 \_____ /
 \ _____/
 \_____/
== Data and data storage ==
Terrain has a stack to which it can push data to and pop elements from. This stack can also be reversed.
Only numbers are stored on this stack.
Terrain can, however, output characters according to a character's ASCII value.
== Programming ==
Commands are determined from the changes of height in the terrain when going from left to right in the file. When encountering a change in height and it's known that currently not an argument is being entered, it is interpreted as a command.
Every command must have at least 2 flowers. They, however, don't execute anything, except maybe serving as decoration.
Commands can also take arguments. Arguments can only be numbers. Arguments come directly after the command.
Unrecognized commands don't throw an error. The program just goes to the next command. However, you shouldn't give unrecognized commands arguments, because the program doesn't look for arguments after these commands and these arguments may make your program run incorrectly.
=== Commands ===
Argument requirements are shown between < and > characters.
 Commands
Change in height	Command name	Short description with parameters 	Additional info
0 	JMP 	Define jump point <number> 	Defines a jump point with a specified number.
-1 	JMPO 	Define ordered jump point 	Defines an ordered jump point. Ordered jump points are numbered starting from the start of the code going towards the end of the code. The ordering starts at 0. Each ordered jump point gets: the previous ordered jump point's number + 1.
-2 	JMPT 	Jump to jump point with number <number> 	Jumps directly to the next command after the jump point with the specified number. The jump point is specified by the "Define jump point <number>" command.
1 	JMPTO 	Jump to ordered jump point with place <number>	Jumps directly to the next command after the jump point with the specified number. The jump point is specified by the "Define ordered jump point" command.
9 	BACK 	Return 	Jump to the command after the last "Jump to jump point with number <number>" or "Jump to ordered jump point with place <number>". These jumps are stored in a stack too. Thus, you can call this multiple times without jumping if ou have jumped multiple times before. Like: jump jump jump return jump return return return
2 	PUSH 	Push value <number> 	Pushes the specified number onto the stack.
-3 	POP 	Pop 	Pop a value from the stack and discard.
4 	POPNUM 	Pop and print number 	Pop a value and print as number.
5 	POPCHR 	Pop and print ASCII 	Pop a value and print the ASCII character with that value.
-4 	INNUM 	Take number input from the user 	Takes input from the user and interprets it as a number and pushes this number onto the stack.
-5 	INCHR 	Take character input from the user 	Takes a character of input from the user and pushes the character's corresponding ASCII value onto the stack.
10 	INLRSTR 	Input left to right string 	Take a string of characters from the user and push them to the stack from left to right.
-10 	INRLSTR 	Input right to left string 	Take a string of characters from the user and push them to the stack from right to left.
7 	SKGT 	Skip if greater than 	Pop two values off the stack (first is a, second is b), if a > b, jump over next command.
8 	SKLT 	Skip if less than 	Pop two values off the stack (first is a, second is b), if b > a, jump over next command.
11 	ADD 	Addition 	Pop two values, add them, push result.
-11 	SUB 	Subtraction 	Pop two values (first is a, second is b), push b - a
12 	MUL 	Multiplication 	Pop two values, multiply them, push the result.
-12 	DIV 	Division 	Pop two values (first is a, second is b), push b / a
-9 	MOD 	Modulo 	Pop two values (first is a, second is b), push b % a
13 	EXP 	Exponentiation 	Pop two values (forst is a, second is b), push b ^ a
-13 	ROOT 	Root 	Pop two values (first is a, second is b), push the bth root of a (bva̅)
3 	DUP 	Duplicate 	Duplicate the top value on the stack. (Has the effect of popping the value then pushing it twice.)
14 	REV 	Reverse 	Reverse the stack
-14 	SWT 	Switch places 	Reverse the top 2 values on the stack. (Has the effect of these "switching places" in the stack.)
-15 	END 	End 	Stop the execution of the program.
=== Defining numbers ===
Numbers are defined by multiple changes in height and these definitions are only accepted at some places (see the Commands section below).
The first change in height defines the base.
 Defining the base
Change in height	Base
-3 	2 (binary)
-4 	10 (decimal)
-5 	16 (hexadecimal)
If omitted, base 10 is used.
The second (possibly first if base is omitted) change in height defines the sign.
 Defining the sign
Change in height	Sign
-2 	- (minus)
-1 	+ (plus)
If omitted, plus is used.
Then comes the number itself. The number is defined by multiple changes in height. These represent digits in the number or a floating point or the end of the number. You cannot start this part with a floating point and cannot end it with a floating point either.
 Defining the number
Change in height 	Meaning
0 - 16 (depending on base what is allowed)	Here is a digit with the value of the amount of changes in height
-2 - -∞ 	A floating point should be placed here
-1 	Here is the end of the number
At least one digit should be given, the floating point can be omitted.
==== Examples of numbers ====
-128.1 in decimal (all parts defined)
 _____
 / \
 / \ _____
 / \_____/ \_____
 /
 _ /
 \ /
 \ /
 \ _____/
 \_____ /
 \ _____/
 \_____/
 ---- -- - -- -------- --- - -
 BASE SIGN 1 2 8 POINT 1 END
== Example programs ==
Note: Since there is no implementation yet, some or all of these programs may not be correct. Rather, take these as help for how a program MAY look like.
=== Truth-machine ===
UNFINISHED
TODO: Add flowers
 _____
 / \
 / \
 _____ _____ / \
 _____/ \/ \_____/ \
 / \
 / \
 / \
 / \
 / \
 / \
 _____ _____ / \
 _____/ \/ \_____/ \
 / \
 / \
 / \_____
 _____/
 _____ /
 _____/ \_____ /
 _ / \_____/
 \ _____/
 \ /
 \ /
 \_____/
Category:Unimplemented
Category:Languages