# Toi (programming language)

Toi is an imperative, type-sensitive language that provides the basic functionality of a programming language. The language was designed and developed from the ground-up by Paul Longtine. Written in C, Toi was created with the intent to be an educational experience and serves as a learning tool (or toy, hence the name) for those looking to familiarize themselves with the inner-workings of a programming language.

## Specification
### Runtime
#### Runtime context definition

The runtime context keeps track of an individual threads metadata, such as:
* The operating stack
** The operating stack where current running instructions push/pop to.
** refer to STACK DEFINITION
* Namespace instance
** Data structure that holds the references to variable containers, also proving the interface for Namespace Levels.
** refer to NAMESPACE DEFINITION
* Argument stack
** Arguments to function calls are pushed on to this stack, flushed on call.
** refer to STACK DEFINITION, FUNCTION DEFINITION
* Program counter
** An interface around bytecode to keep track of traversing line-numbered instructions.
** refer to PROGRAM COUNTER DEFINITION
This context gives definition to an 'environment' where code is executed.

#### Namespace definition

A key part to any operational computer language is the notion of a 'Namespace'. This notion of a 'Namespace' refers to the ability to declare a name, along with needed metadata, and call upon the same name to retrieve the values associated with that name.
In this definition, the namespace will provide the following key mechanisms:
* Declaring a name
* Assigning a name to a value
* Retrieving a name's value
* Handle a name's scope
* Implicitly move in/out of scopes
The scope argument is a single byte, where the format is as follows:
Scopes are handled by referencing to either the Global Scope or the Local Scope. The Local Scope is denoted by '0' in the scope argument when referring to names, and this scope is initialized when evaluating any new block of code. When a different block of code is called, a new scope is added as a new Namespace level. Namespace levels act as context switches within function contexts. For example, the local namespace must be 'returned to' if that local namespace context needs to be preserved on return. Pushing 'Namespace levels' ensures that for every n function calls, you can traverse n instances of previous namespaces. For example, take this namespace level graphic, where each Level is a namespace instance:
When a function is called, another namespace level is created and the local level increases, like so:
Global scope names (LSB == 1 in the scope argument) are persistent through the runtime as they handle all function definitions, objects, and names declared in the global scope. The "Local Level" is at where references that have a scope argument of '0' refer to when accessing names.
The Namespace argument refers to which Namespace the variable exists in. When the namespace argument equals 0, the current namespace is referenced. The global namespace is 1 by default, and any other namespaces must be declared by using the

#### Variable definition

Variables in this definition provide the following mechanisms:
* Provide a distinguishable area of typed data
* Provide a generic container around typed data, to allow for labeling
* Declare a set of fundamental datatypes, and methods to:
** Allocate the proper space of memory for the given data type,
** Deallocate the space of memory a variables data may take up, and
** Set in place a notion of ownership
For a given variable V, V defines the following attributes
Each variable then can be handled as a generic container.
In the previous section, the notion of Namespace levels was introduced. Much like how names are scoped, generic variable containers must communicate their scope in terms of location within a given set of scopes. This is what is called 'Ownership'. In a given runtime, variable containers can exist in the following structures: A stack instance, Bytecode arguments, and Namespaces
The concept of ownership differentiates variables existing on one or more of the structures. This is set in place to prevent accidental deallocation of variable containers that are not copied, but instead passed as references to these structures.

#### Function definition

Functions in this virtual machine are a pointer to a set of instructions in a program with metadata about parameters defined.

#### Object definition

In this paradigm, objects are units that encapsulate a separate namespace and collection of methods.

#### Bytecode spec

Bytecode is arranged in the following order:
Where the <opcode> is a single byte denoting which subroutine to call with the following arguments when executed. Different opcodes have different argument lengths, some having 0 arguments, and others having 3 arguments.

##### Interpreting Bytecode Instructions

A bytecode instruction is a single-byte opcode, followed by at maximum 3 arguments, which can be in the following forms:
* Static (single byte)
* Name (single word)
* Address (depending on runtime state, usually a word)
* Dynamic (size terminated by NULL, followed by (size)*bytes of data)
** i.e. FF FF 00 <0xFFFF bytes of data>,
** 01 00 <0x1 bytes of data>,
** 06 00 <0x6 bytes of data>, etc.
Below is the specification of all the instructions with a short description for each instruction, and instruction category:

### Opcode

Keywords:

#### Type management

Types are in the air at this moment. I'll detail what types there are when the time comes

#### Binary Ops

OPS take the two top elements of the stack, perform an operation and push the result on the stack.

#### Conditional Expressions

Things for comparison, < > = ! and so on and so forth. Behaves like Arithmetic instructions, besides NOT instruction. Pushes boolean to TOS

#### Code flow

These instructions dictate code flow.

#### Special Bytes
### Compiler/Translator/Assembler
#### Lexical analysis

Going from code to bytecode is what this section is all about. First off an abstract notation for the code will be broken down into a binary tree as so:
node> can be an argument of its parent node, or the next instruction. Instruction nodes are nodes that will produce an instruction, or multiple based on the bytecode interpretation of its instruction. For example, this line of code:
would translate into:
Functions are expressed as individual binary trees. The root of any file is treated as an individual binary tree, as this is also a function.
The various instruction nodes are as follows:
* def <type> <name>
** Define a named space in memory with the type specified
*** See the 'TYPES' section under 'OVERVIEW'
* set <name> <value>
** Set a named space in memory with value specified

##### Going from Binary Trees to Bytecode

The various instruction nodes within the tree will call specific functions that will take arguments specified and lookahead and lookbehind to formulate the correct bytecode equivalent.

## Developer's Website

The developer of the language, Paul Longtine, operates a publicly available website and blog called banna.tech, named after his online alias 'banna'.