Language Reference

Phograph is a visual, object-oriented, dataflow programming language descended from Prograph. This reference covers its core concepts, data types, primitives, and control flow.

Contents

• Dataflow Model
• Program Structure
• Data Types
• Node Types
• Primitives Reference
  • Arithmetic
  • Comparison
  • Logic
  • String
  • List
  • Higher-Order List
  • Dict
  • Console / Debug
  • Type Checking
  • Enum
  • Method References
  • Networking
  • JSON
  • Date/Time
  • Observables
• Control Flow
• Loops and List Annotations
• Classes and Objects
• Protocols
• Actor Classes
• Front Panel
• Error Handling
• Concurrency and Async

Dataflow Model

Data flows from top to bottom through a directed acyclic graph of operation nodes. A node executes when all its input data is available (data-driven firing rule). Execution order depends solely on data dependencies, not spatial position.

Phograph has two kinds of wires:

• Data wires (solid lines) — carry values between nodes.
• Execution wires (dashed lines) — enforce ordering for side-effecting operations.

A node with an execution-in pin fires only after the upstream execution wire has triggered, even if all data inputs are already available. Execution wires are optional — pure-dataflow graphs need none.

Program Structure

A Project contains one or more Sections. Each section has three compartments:

• Classes — object-oriented code and data
• Universal Methods — standalone functions
• Persistents — global persistent variables

Methods and Cases

A method has one or more cases. Each case is a separate dataflow graph with an input bar (parameters) and an output bar (return values). When a method is called, case 1 runs first. If a control annotation triggers “next case,” case 2 runs, and so on.

Every method has a defined arity — a fixed number of inputs and outputs. Inputs can be marked optional (with a default value) or variadic (collects into a list).

Data Types

Phograph has thirteen data types:

Phograph is dynamically typed. Types are checked at runtime. Optional type annotations can be added to pins for documentation and validation.

Lists are 1-indexed (the first element is at position 1), following the original Prograph convention.

Node Types

Pin Types

Nodes have input pins at the top and output pins at the bottom. Pin shapes indicate type compatibility: circles for scalars, hexagons for booleans, squares for collections, diamonds for optionals, pentagons for objects, triangles for execution flow.

Pins have additional properties:

• Hot pins — trigger node evaluation when data arrives. By default all data inputs are hot.
• Cold pins — supply data but do not trigger evaluation. The node fires only when a hot pin receives data.
• Optional pins — have a default value and do not need a wire connected. If unwired, the default is used.

Wire Types

• Data wires (solid lines) — carry values between nodes.
• Execution wires (dashed gray lines, is_execution) — enforce ordering for side-effecting operations without carrying data. A node with an execution-in pin fires only after the upstream execution wire has triggered.

Node Annotations

In addition to control-flow annotations (see Control Flow), nodes support structural annotations that change how they process data:

Pattern Matching Guards

Cases in a method support pattern matching guards that control which case fires based on the input values. Guard types:

• Type guard — matches when the input is a specific type (e.g., Integer, String, a class name).
• Value guard — matches when the input equals a specific literal value.
• Wildcard guard — matches any value (used as a default / catch-all case).

Primitives Reference

Arithmetic

Comparison

Logic

String

List

Higher-Order List

These primitives take a method-ref as a callback argument (see Method References).

Dict

Console / Debug

Type Checking

Enum

Method References

Method references are first-class values that point to a method. They can be passed to higher-order primitives like map, filter, and reduce, or called dynamically with call.

Networking

JSON

Date/Time

Duration Helpers

Convenience primitives for creating durations in seconds, suitable for use with date-add:

Observables

Observables let you watch for changes to object attributes and react automatically. They are the foundation for reactive data binding in front panels and between objects.

Control Flow

Success and Failure

Every node execution has one of three outcomes:

1. Success — completed normally, produced output.
2. Failure — a controlled outcome that triggers a control annotation. Not an error.
3. Error — an unrecoverable problem.

Control Annotations

An annotation on a node tells the engine what to do on success or failure. The most important annotations:

The if Primitive

For simple conditionals within a single case: if(condition, then-value, else-value) outputs whichever value matches the condition.

Loops and List Annotations

Loop (counted)

Created by wrapping a method call. The output of each iteration feeds back as input for the next. A terminate annotation ends the loop.

Repeat (indefinite)

Executes repeatedly with no counter until a terminate or finish annotation fires inside.

List Annotation (ellipsis)

Mark an input with an ellipsis: the operation runs once per list element. Mark the output too: results are gathered into a list. This turns any scalar operation into a map over a list — no explicit loop needed.

Spreads (automatic broadcasting)

A scalar operation that receives a List on an input automatically executes once per element, producing a List of results. Multiple list inputs are zipped. This makes most explicit loops unnecessary.

Classes and Objects

Defining a class

A class has attributes (data) and methods (behavior). Attributes can be instance-level or class-level. Methods receive the object as their first input (self).

Instance generators

An octagonal node creates a new object. If the class has an init method, it runs automatically. Extra inputs on the generator are passed to init.

Get and Set

Get reads an attribute: 1 input (object), 2 outputs (object pass-through, value). Set writes an attribute: 2 inputs (object, value), 1 output (modified object).

Inheritance

Single inheritance. A child class inherits all attributes and methods from its parent. Methods can be overridden. Use /methodName for dynamic dispatch based on the object’s class.

Method call syntaxes

Protocols

A protocol defines a set of method signatures that a class must implement to conform. Protocols enable polymorphism without inheritance — any class can conform to any protocol by providing the required methods.

Use conforms-to? to test at runtime whether an object’s class conforms to a given protocol. Protocol conformance is declared on the class definition and checked by the runtime.

Actor Classes

An actor class is declared with the actor keyword in its class definition. Actors provide concurrency safety: all method calls on an actor are serialized, ensuring that only one method executes at a time on a given actor instance. This eliminates data races without manual locking.

Actor methods are implicitly asynchronous — calls from outside the actor return a Future that resolves when the method completes. Calls within the same actor execute synchronously.

Front Panel

A front panel is a SwiftUI interface automatically generated from a class’s attributes. Each attribute with a front-panel annotation becomes an interactive control (slider, text field, toggle, color picker, etc.) bound to the attribute’s value via the observable system.

When the user changes a control, the bound attribute updates. When code changes the attribute, the control updates. This two-way binding is established automatically using bind.

Error Handling

An Error is a value (not an exception) with a message, code, and optional details dict.

The try annotation catches failures and converts them to Error values on a dedicated error output pin (visually a dashed red wire).

Error cluster wiring: fallible operations can chain an error-in/error-out pin. If any operation fails, subsequent operations skip and the error flows through to the end.

Concurrency and Async

Async operations return Futures. A Future resolves later; downstream operations automatically wait for the value (no explicit await needed — it falls out of the firing rule).

Channels enable producer-consumer patterns: channel-create, channel-send, channel-receive.