A visual graph-based hacking language made for stupid purposes.
## Applications
This repository contains the source for three applications:
`inner-platform`, the runtime for executing programs
`inner-server`, a daemon for managing, debugging, and deploying your programs
`inner-editor`, a GUI application for editing programs
## Specification
A basic and rubbish spec for the Inner Platfom Hacking Language (IPHL)
### Concepts
The executable unit of IPHL code is the **program**, which lives in a .iphp file. Non-executable code (i.e libraries) is a **module** which lives in a .iphm file.
These are mostly the same and so the word program will be used for both cases; maybe I'll have to come up with a generic name for both at some point.
A program is made up of **nodes** and **pipes**. A node represents a function, object, or other thing-that-does-processing. A **pipe** carries **values** in one direction between nodes, and also carry **signals** in either direction which transfer control.
Each node has a number of **ports**, which can be either input or output ports. A pipe always connects one output port to one input port. Normally, any port may have zero to many pipes connected to it, although some nodes may impose a uniqueness rule on their ports (see Ports).
### Nodes
A node's purpose is to take input from it's input ports, process it, and send it to the output ports. It may also communicate with other sources it owns (such as a websocket, external process), although it should not cause side effects that are observable from other nodes, unless the programmer sets this up deliberately.
#### Representation
A node is visually represented by a box.
#### Properties
Things a node has:
- A name, which can be changed but defaults to a value
- A class, see below
- Zero or more input ports
- Zero or more output ports
- A reset function, which clears any internal state from a node
- A check function, which tests if a node has enough input data for it's process function to complete
- A process function, which takes values from the input ports and turns them into values in the output ports.
Nodes should have at least one port (of either type) otherwise they're useless.
#### Node classes
### Ports
#### Properties
A port has:
- A name
- A type
- A mode (see Ports#Modes), for output ports
- Zero or more connected pipes
#### Modes
Output ports can operate in one of three modes, which defines the mechanics of when and how new values are passed to a connected pipe:
- **Push ports**: these push a new value into the pipes at the prompting of the node they belong to; they also signal the node at the other end of the pipe when they do. These are used for nodes that provide spontaneous input to the program, such as receiving button press or IM messages.
- **Pull ports:**: these provide a value at the prompting of the node at the other end of the pipe (the one with a connected input port). They may block while waiting for a value, or may indicate that there is no value available, which prevents the pulling node from processing. If a pull-port is connected to multiple pipes, pulling a value from one causes the same value to get pushed to all the others.
- **Static ports**: these hold a single value that is infinitely copied, and is not expected to change often. They function like push-ports in most respects, but they only push a value when the value they hold changes. They always have a value available to be pulled, and pulling this value does not change the state.
#### Representation
A port is visually represented by a small shape, such as a circle. The colour of a port represents its type, a listing of suggested colours is below:
- Red: boolean values
- Orange: signal only (see Pipes)
- Blue: integers
- Cyan: floats
- Green: strings
- Yellow: complex objects
- Black/white (depending which way up your colour scheme is): any type, or unknown
If a port's type is an array (or collection, etc), it's colour is that of the array type, but the port icon is double-lined.
An output port's mode determines its shape:
- Push ports are circles;
- Pull ports are diamonds;
- Static ports are squares.
All input ports are circles.
### Pipes
Pipes connect an output port to an input port, and carry values between them.
### Program Flow
#### Node Deque
Internally, each program thread maintains a deque of nodes. At each step of the program, the node at the front of the deque is removed, and this node is processed; it reads or takes values from its input ports, and writes new values to its output ports. When a new value is written to an output port, a signal is sent through any connected pipes.
#### Signalling
To transfer control between nodes, there is a process called **signalling**; when a node is signalled, its check function is called to determine if the node can be processed. If so, this node is added to the node deque, normally at the back.
A node is signalled under the following conditions:
- When a signal arrives at an input port from another node, indicating that a new value is available in the pipe.
- When another node wants to pull a value from a pull-port of a node. **Note that** in this case, the signalled node goes to the front of the node deque, not the back; this is so a chain of nodes with pull-ports will be processed in the reverse order that they were signalled.
- Whenever a node has just finished processing, that same node is signalled again.
- A node may signal itself when an object it controls (running in another thread) receives new data. For example, a node implementing a bot on an IM program will signal itself when a new message arrives; a node representing a button will signal itself when the button is pressed.
- At the start of the program, the start nodes are signalled.
#### Program Start
At the start of the program, the following things happen in order:
- All nodes are asked to reset; this means to clear any volatile state information they hold. Nodes may keep persistent state between runs of the program, but only if this is an obvious part of their function.
- Start nodes are signalled in an arbitrary order.
### File Types
IPHL code is stored in YAML format, although with renamed file extensions. Programs themselves are stored in .iphp files (for Inner Platform Hacking Program) while modules (parts of programs) are stored in .iphm files (Inner Platform Hacking Module). Besides their different contents, the two file types are identical.
The exact structure of these files isn't defined yet, but each one is composed of a number of sections. Most sections are optional; if a IPHL editor doesn't know what to do with an section, it should pass it through without touching it.
- shebang: files always begin with #!/bin/innerplatform, which identifies them to the shell.
-`metadata:` contains metadata: what this file is, who made it, and so on.
-`code:` contains the actual nodes and pipes. This is the only mandatory section.
-`layout:` contains layout information: chiefly, where the nodes are positioned on screen, and what routes the pipes take.
