NodeProcessor/README.md

Inner Platform (Working Title)

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.