PROTOCOL FOR ESOTERIC MINIMALISM AND AVOIDANCE OF THE TURING TARPIT (PEMATT)
										PROTOTYPE
										 DRAFT-III


CONTENTS:
	
	*BASIC STRUCTURE
	*INSTRUCTIONS
	*PREPROCESSOR
	*GARBAGE COLLECTION


BASIC STRUCTURE:

The system consists of a stack, which shall be used for storing data. The data, on the other hand, can be of five types: 

* Integer-type
	* Integers can be of fixed length as well:
		*i8, i16, i32, i64, i - Signed 8/16/32/64/independent bit numbers
		*u8, u16, u32, u64, u - Unsigned 8/16/32/64/independent bit numbers.
* Floating Point-type (Double precision)
* ASCII String-type
* Code-type
* Array-type (1-indexed, for *now*)

The code shall have the ability through various instructions to act on these values, and also to act on the stack.
There shall be no registers in the esoteric CPU, with the exception of the instruction pointer, and the stack pointer. 
The CPU instructions shall be only of one-byte length and in ASCII only.

There must be strict type checking, implemented within the CPU. All type errors must be handled like exceptions. 
(which shall be discussed later)

INSTRUCTIONS:
	CHARACTER (ASCII)					DESCRIPTION
	-------------------------------------------------------------------
	>							Increase top stack pointer by 1
	-------------------------------------------------------------------
	<							Decrease top of stack pointer by 1
	------------------------------------------------------------------
	~							Toggle INSERT/OVERWRITE modes. Under INSERT mode, if the stack pointer
								does not point to the *actual* top of stack, and an item is pushed, the interpreter
								is expected to "insert" the newer item between the stack pointer, and the item
								after it. Under OVERWRITE mode, the item right after the top of stack is replaced
								with the new pushed item. The mode on initialisation is guaranteed to be INSERT.
								The stack pointer is incremented in both modes on push.
								
								During a pop operation in INSERT mode, the item from the stack will be purged, and the
								items below it will be shifted up one (or the number of items popped), and the stack 
								pointer will be decremented. On the other hand, during OVERWRITE mode, the stack pointer 
								will only be decremented, the items will not be removed. 
								(This applies to all instructions which do pop operations as well.)
	------------------------------------------------------------------
	(...)							Push string, float, integer or code to stack and increment the stack pointer.
								enclosed in '()'.
								Integers must be prefixed with i/u/i8/i16/i32/i64/u8/u16/u32/u64, e.g.: (i:247) 
								to push the integer 247. They can also be prefixed with 'x' or 'b' to indicate 
								hexadecimal or binary. e.g: (u16:xEFF) or (u8:b1110111). You can also push the 
								address of labels, simply by using the 'l' prefix e.g: (l:"mylabel"). Strings 
								must be prefixed with 's' and enclosed in '"'. e.g: (s:"Hello, World!"), to push
								the string "Hello, World!".
								Floats must be prefixed with 'f', the non-whole part is to be separated from the whole by a
								'.'. All floats MUST use the decimal system. e.g: (f:23.7)
								The 'Code' type contains code, which can be called through various instructions explained later 
								on, they must be prefixed with 'c' and be enclosed within '"', e.g: (c:"<<(i247)")
								An array can be pushed by enclosing it within brackets, e.g: ([1,2,3]) or ([[]]) (jagged empty array)
	------------------------------------------------------------------
	+							Add/Concatenate items. Depending upon type, do an add or concatenate, and pop both the items,
								pushing the result.
								Let a be the item right on stack pointer, and b be the item right on stack pointer - 1.
								*If both a and b are integers, then push: b+a
								*If both a and b are floats, then push: b+a
								*If a is an integer and b is a float, then convert a to float, and push b+a
								*If a is a float and b is an integer, round of a to an integer, and push b+a
								*If both a and b are strings or code, concatenate a and b, and push result.
								*If a is a string, and b is a integer, attempt to convert a to integer, and push b+a. If there
								is an error in conversion, cause an exception.
								*If a is an integer or float and b is a string, convert a to string, and concatenate a and b, pushing
								the result
								*If a and b are arrays of the same type, pop a and b, concatenate a into b, and push result else error out.
								*If 'a' is a non-array object of type b[n] (b is an array), pop a and b, then append a into b, and push b. 
								Error out on all other circumstances.
								*If a is code and b is an integer or float, error out.
								*If b is code, and a is an integer or float, error out.
								*Note that the type of b (what type of integer/float it is), determines the type of the
								result pushed after an arithmetic operation. If there is an overflow, it would wrap back.
								This applies to everything and every operation not just the add operator (+).
	------------------------------------------------------------------
	-							Subtract/Remove items. Depending upon type, do a subtract or removal operation, and pop both items,
								pushing result.
								Let a be the item right on stack pointer, and b be the item right on stack pointer - 1.
								*If both a and b are integers, then push: b-a
								*If both a and b are floats, then push: b-a
								*If a is an integer and b is a float, then convert a to float, and push b-a
								*If a is a float and b is an integer, round off a to an integer, and push b-a
								*If both a and b are strings or code, remove all instance of 'a' from 'b' and push the result.
								*If a is a string, and b is a integer, attempt to convert a to integer, and push b-a. If there
								is an error in conversion, cause an exception.
								*If a is an integer or float and b is a string, convert a to string, and remove all instance of a
								from b, pushing the result
								*If a is an array and b is an array of the same type, pop a and b, and remove all instances of
								items in a, from b, and push b.
								*If a is a non-array object of type b[n] (b is an array), pop a and b, and append a to b, and push b.
								Error out on all other circumstances.
								*If a is code and b is an integer or float, error out.
								*If b is code, and a is an integer or float, error out.
	------------------------------------------------------------------
	*							Multiply operation.
								Let a be the item right on stack pointer, and b be the item right on stack pointer - 1.
								*If both a and b are integers, then push: b*a
								*If both a and b are floats, then push: b*a
								*If a is an array of type integer/float and b is an array of type integer/float,
								pop a and b, and multiply each instance of a with it's corresponding index of b, pushing
								the result. e.g: ([1,2,3])([5,6,7])* should yield: [5, 12, 21]. If the length of a 
								is less than b, then keep multiplying through wrapping the multipliers. e.g: [1,2,3][5,6]*
								should yield: [5, 12, 15]. If length of a is greater than b, then keeping wrapping multiplicands.
								e.g: [1,2][5,6,7,8]* should yield: [5, 12, 7, 16]. Also, if the arrays multipled are of either type
								(integer and float), then the type of b shall be the type of the new array created. Error out if
								the items are not of integer or float type.
								*If a is a value of type float/integer and b is an array of type float/integer, pop a and b then
								multiply each item in b with a, and push b. Error out on all other circumstances.
								*If a is an integer and b is a float, then convert a to float, and push b*a
								*If a is a float and b is an integer, round off a to an integer, and push b*a
								*Error out on all other circumstances
	------------------------------------------------------------------
	/							Divide operation.
								Let a be the item right on stack pointer, and b be the item right on stack pointer - 1.
								*If both a and b are integers, then push: b/a
								*If both a and b are floats, then push: b/a
								*If a is an array of type integer/float and b is an array of type integer/float,
								pop a and b, and divide each instance of b by it's corresponding index of a, pushing
								the result. e.g: ([25,30,35])([5,6,7])* should yield: [5, 5, 5]. The rules of array multiplication
								given in the '*' section, apply here as well.
								*If a is a value of type float/integer and b is an array of type float/integer, pop a and b then
								divide each item in b by a, and push b. Error out on all other circumstances.
								*If a is an integer and b is a float, then convert a to float, and push b/a
								*If a is a float and b is an integer, round off a to an integer, and push b/a
								*Error out on all other circumstances
	------------------------------------------------------------------
	%							Modulo operation. (Remainder Operation)
								Let a be the item right on stack pointer, and b be the item right on stack pointer - 1.
								*If both a and b are integers, then push: b%a
								*If both a and b are floats, then push: b%a
								*Do the same as expected in multiplication/division, except, of course, the operation done should
								be modulus, if a and b are both arrays, or a is a non-array object of type b[n]. Error out
								on all other circumstances.
								*If a is an integer and b is a float, then convert a to float, and push b%a
								*If a is a float and b is an integer, round off a to an integer, and push b%a
								*Error out on all other circumstances
	------------------------------------------------------------------
	^							Power operation.
								*Let a be the item right on stack, and b be the item right on stack pointer - 1
								*If a and b are both integers, push b^a, in raw integer format to stack. And pop b and a.
								*If a and b are both floats, push b^a, in floating point format to stack. And pop b and a.
								*If a is an array and b is an array, of the integer/float type, pop a and b, and replace all
								items in b, with b[n]^a, respectively. The rules of multiplication and division apply here as well.
								*If a is float, and b is an integer, convert a to integer (round off), and push b^a as integer.
								*If a is integer, and b is float, convert a to float, and push b^a as float.
	------------------------------------------------------------------
	R							Right Shift operation (>>)
								Let a be the item right on stack pointer, and b be the item right on stack pointer - 1.
								*If both a and b are integers, then push: b>>a
								*If both a and b are floats, then push: b>>a
								(NOTE: FLOATS WILL BE CONVERTED TO IEEE-754 ENCODING PRIOR TO BITWISE OPERATION, AND WOULD
								THEN BE CONVERTED BACK TO FLOATING POINT DECIMALS AFTER THE OPERATION HAS BEEN DONE.)
								*Error out on all other circumstances
	------------------------------------------------------------------
	L							Left shift operation (<<)
								Let a be the item right on stack pointer, and b be the item right on stack pointer - 1.
								*If both a and b are integers, then push: b<<a
								*If both a and b are floats, then push: b<<a
								(NOTE: FLOATS WILL BE CONVERTED TO IEEE-754 ENCODING PRIOR TO BITWISE OPERATION, AND WOULD
								THEN BE CONVERTED BACK TO FLOATING POINT DECIMALS AFTER THE OPERATION HAS BEEN DONE.)
								*Error out on all other circumstances
	------------------------------------------------------------------
	A							Do a bitwise AND (&) operation						
								Let a be the item right on stack pointer, and b be the item right on stack pointer - 1.
								*If both a and b are integers, then push: b&a
								*If both a and b are floats, then push: b&a
								(NOTE: FLOATS WILL BE CONVERTED TO IEEE-754 ENCODING PRIOR TO SHIFT OPERATION, AND WOULD
								THEN BE CONVERTED BACK TO FLOATING POINT DECIMALS AFTER THE OPERATION HAS BEEN DONE.)
								*Error out on all other circumstances
	------------------------------------------------------------------
	O							Do a bitwise OR (|) operation						
								Let a be the item right on stack pointer, and b be the item right on stack pointer - 1.
								*If both a and b are integers, then push: b|a
								*If both a and b are floats, then push: b|a
								(NOTE: FLOATS WILL BE CONVERTED TO IEEE-754 ENCODING PRIOR TO BITWISE OPERATION, AND WOULD
								THEN BE CONVERTED BACK TO FLOATING POINT DECIMALS AFTER THE OPERATION HAS BEEN DONE.)
								*Error out on all other circumstances
	------------------------------------------------------------------
	X							Do a bitwise XOR(^) operation.
								Let a be the item right on stack pointer, and b be the item right on stack pointer - 1.
								*If both a and b are integers, then push: b^a
								*If both a and b are floats, then push: b^a
								(NOTE: FLOATS WILL BE CONVERTED TO IEEE-754 ENCODING PRIOR TO BITWISE OPERATION, AND WOULD
								THEN BE CONVERTED BACK TO FLOATING POINT DECIMALS AFTER THE OPERATION HAS BEEN DONE.)
								*Error out on all other circumstances
	------------------------------------------------------------------
	!							Do a bitwise NOT. If a is the item right on stack pointer, pop a, and push '!a'.
								(i.e. if a is equal to 0, push 1, else push 0)
	------------------------------------------------------------------
	D							Duplicate value. If a is the item right on stack pointer, pop a, and push a twice.
	------------------------------------------------------------------
	W							sWap values on top of stack. Let a be value right on stack pointer, and b be value on
								stack pointer - 1. Then, pop a, then b, and then push a and b, hence reversing the order.
	------------------------------------------------------------------
	?							Push random value on stack.
	------------------------------------------------------------------
	$							Pop from stack, decrease top of stack pointer by 1.
	------------------------------------------------------------------
	J							Set instruction pointer to the integer pushed last to stack.
								If instead of an integer, the top of stack contains 'code', prepare
								a new execution instance and copy the code popped from stack, and duplicate the stack of the current
								instance, and execute the code on the newer execution instance. Once the newer
								instance has quit, copy it's stack, and place it on the main execution instance, and continue. 
								Error out, if string or float is found.  Pop the value.
	------------------------------------------------------------------
	C							Call from class. A class is a mere set of functions.
								The 'C' instruction works similar to 'J', except it takes the argument as a string pushed
								last to stack in the form of: "classname.function"
								Where 'classname' is the name of the class (file) with the extension '.pt', and 'function'
								is a function defined in that file. The 'C' instruction calls that function in the same way
								as 'J' does. If you want to call a function from the current module, simply use: 'self.function'.
								The function name will be popped from stack. Errors out if the function is not found, or the value
								pushed to stack is not string.
	------------------------------------------------------------------
	Z							If top of stack is 0, do what instruction 'J' does. Else, skip to next instruction.
	------------------------------------------------------------------
	=							Let a be the item right on stack pointer, and b be the item right on stack pointer - 1.
								If a is equal to b, push 0, else push 1. Pop the values.
	------------------------------------------------------------------
	G							Let a be the item right on stack pointer, and b be the item right on stack pointer - 1.
								If b is greater than a, push 0, else push 1.
	------------------------------------------------------------------
	L							Let a be the item right on stack pointer, and b be the item right on stack pointer - 1.
								If b is lesser than a, push 0, else push 1.
	------------------------------------------------------------------
	E							External call. Call function from the environment, whose name is pushed to stack. Pop the name,
								and push the result from the function. (List of functions available coming up!)
	------------------------------------------------------------------
	l							Load from memory address. The memory address must be on top of stack. The address will be
								popped from stack and the value at the address will be pushed.
	------------------------------------------------------------------
	s							Store to memory address. The memory address should be on stack pointer - 1 and MUST be
								an integer and valid memory address, while the value to be stored must be right on stack pointer. 
								Depending upon type (integer, string, code or float) would be stored appropriately.
								Both should be popped out after store.
	------------------------------------------------------------------
	F							Fetch an item from array on top of stack - 1. The index must be on top of stack.
								The index is popped out and replaced with the item on stack.
	------------------------------------------------------------------
	S							Set an item. The array must be on top of stack - 2, and the index must be on top of stack - 1,
								and the item to be set must be on top of stack. If the item is of the same type as array[n], then
								array[index] = item. Else it errors out. If index is equal to -1, then the interpreter shall append
								the item to the array. If index is 0, then all instances from item are removed from array.
	------------------------------------------------------------------
	P							Pops the last item from array. The array must be on top of stack.
								The array is popped, and the item is removed, and the array is pushed to stack.
								After the array is pushed, the purged value is also pushed to stack.
	------------------------------------------------------------------
	K							Get indexes of instances of an item in an array pushed to stack. The item must be on
								top of stack and the array must be present on top of stack - 1. The item is popped from stack,
								and the result is an integer array containing the indexes of items in array. The array is
								then pushed to stack.
	------------------------------------------------------------------
	B							Bulk. Get bulk (length) of an array on top of stack. The length is pushed to stack.
								The array is popped.
	------------------------------------------------------------------
	I							Get current instruction pointer and push to stack.
	------------------------------------------------------------------
	@							An 'END' statement. Ends the current execution instance.
	------------------------------------------------------------------
	o							Output string/float/integer pushed to stack (depending upon type) and pop it.
	------------------------------------------------------------------
	i							Take input from user, until a '\n' is received and push string to stack.
	------------------------------------------------------------------
	g							Set global variable whose name is right on stack pointer - 1 and value on stack pointer.
								If types don't match, the interpreter shall error out. The name must be in the format:
								'classname.variable'; If the interpreter does not find such a variable, it must error out.
								After the assignment, the name and the value assigned must be popped from stack.
	------------------------------------------------------------------
	y							Get global variable value. The name of the variable must be on top of stack. 
								The value is pushed and the name of variable is popped out.

PREPROCESSOR:
	
	The preprocessor forms a very important part of the PEMATT protocol, through this, programs can use features
	that are not available in most esoteric languages. After preprocessing the preprocessor directives are removed
	from code, and their infromation is stored internally.
	
	PHRASE						DESCRIPTION
	----------------------------------------------------------------
	#import "classname.pt"				Import a class. (Just like include)
	----------------------------------------------------------------
	:...:						Declare label. The interpreter is supposed to remove this from code during the preprocessing, 
							and assign the name to it's address internally. It shall function as a indicator of the memory
							address right after the second ':'. NOTE: The label MUST not be a part of the memory during execution.
							This works exactly like the label system in assemblers.
	----------------------------------------------------------------
	#def "functionname" { code }			Assign a name (functioname) to the code between '{' and '}' blocks, internally.
							This can then be called using the 'C' instruction.
	----------------------------------------------------------------
	#global "varname"				Declare a global variable with name
	----------------------------------------------------------------
	#init						Compulsory. Indication of where the execution is supposed to begin in script.
	
	
GARBAGE COLLECTION:
	
	The stack style of PEMATT allows for the most basic garbage collection to happen. The interpreter is supposed to subsequently
	free items that have been popped from stack.


Footnote:
	This document is simply a draft, and will be subject to changes in the near future. And since it's a draft, it may contain logical or grammatical errors.
	Please do not assume this as a final document without any fallacies.