PCB
Language Reference

Interpreter Pipeline

Every PCB program passes through five stages before a single line executes. Click any stage for details.

Bidirectionality

A PCB program runs in both directions simultaneously — not as a mode but as two concurrent strands on shared data. KnotRunner uses an oscillation model: at each loop boundary the direction flips while the condition holds, so forward statements fire on forward passes and backward statements (tnirp, xob, rav, etc.) fire on backward passes — within the same loop body. Flow processing (tkp/pkt tick loops) runs independently on its own threads. Lexical reversal (keywords spelled backward, dot-chain mirrored) is the surface projection of directional traversal. The dot-chain is a directional composition operator — print.("x") and ("x").tnirp are the same execution graph node traversed from opposite ends.

Keyword Explorer

Search and filter all PCB keywords. Click any card to see syntax, description, and examples. Cyan = forward form. Amber = reverse form.

Container Types

PCB has six container types in two mirrored hierarchies. Forward: box → cup → pkt. Backward mirror: xob → puc → tkp. Each pair is not merely a syntactic mirror — each backward type has distinct execution semantics: xob is structurally opaque (inspection ops blocked); puc inverts every operation in its body at execution time; tkp has an independent tick-based lifecycle that seam-crosses to pkt. knt/tnk stand apart — they act as container, orientation, and operator simultaneously. Everything in PCB is a box — every container implements IBox, and every primitive is automatically wrapped in a single-item BoxInstance at storage boundaries. Variables are containers all the way down.

Primitive Boxing

Primitives are never stored raw. At every storage boundary the runtime wraps them in a single-item BoxInstance. Computation may produce raw values, but storing them always boxes them. Reading them for arithmetic auto-unboxes transparently.

Storage Boundaries

Boxing happens automatically when a value crosses any of these boundaries:

Boxer Rules

Auto-Unboxing

Binary operators (+ - * / % ^ and comparisons) automatically unwrap a BoxInstance on either operand before computing. The result is raw; it is re-boxed only at the next storage boundary. You never need to manually unbox for arithmetic.

Interface Type Hierarchy

Every container implements IBox. The marker interfaces form the runtime type tree:

IBox
 ├── ICup  extends IBox
 │    └── IPkt  extends ICup
 │         ├── ITkp  extends IPkt    →  TkpInstance
 │         ├── IKnt  extends IPkt    →  KnotInstance
 │         └── ITnk  extends IPkt    →  TonkInstance
 └── IXob  extends IBox
      └── IPuc  extends IXob, ICup

BoxInstance    implements IBox
CupInstance    implements ICup
PocketInstance implements IPkt
XobInstance    implements IXob  (also extends BoxInstance)
PucInstance    implements IPuc  (also extends CupInstance)

Pocket Ecosystem

pkt and tkp are self-contained execution ecosystems — they hold elements, run Flow tick loops on independent daemon threads, and manage their own lifecycle. They are the only containers with autonomous execution.

Flow Tick Loop

On each tick, every active Flow scans the body in its current direction. Priority order of what Flow acts on:

Bootstrapping vs Routing

These are separate concerns. Flow bootstraps — it starts execution. Routing is where the output goes — handled entirely by KnotRunner using interp.environment to look up the target container by name. Flow does not participate in routing.

Period as Direction Signal

A standalone . flips the active flow's direction in place. When a . appears inside a knt/tnk body, it becomes a routed result — injected into the target container by runWithRouting(). If the target is a pkt/tkp, the tick loop flips that container's flow direction. A knot can remotely flip flow direction in another pocket. In box/cup targets, "." lands inertly.

Heat Death

Heat death is reached when all Flow chain tokens are spent and no actionable items remain — no dormant Flow objects, no unexecuted cups or knots, no bracket signals. tkp at heat death seam-crosses to pkt. pkt at heat death simply stops ticking.

Seam Crossing

Lifetime budget transfers through every crossing. TRAVERSAL carries remaining count. Body and flows transfer; seam-crossed container starts its own tick loop if it has flows.

Control Flow

Loops and conditionals have bidirectional forms. Labeled loops allow complex nested structures to reference each other.

Operators

PCB supports standard arithmetic, comparison, and logical operators plus two unique stream operators for direct file I/O.

Program Examples

Real programs from source files, plus authored examples demonstrating common patterns.

Math Examples

PCB has built-in trig, log, arithmetic, rounding, inverse trig, bitwise, and vector/matrix keywords. A separate symbolic math subsystem (BoxMath) with derivatives, integrals, and the Fresnel S/C integrals exists internally. The examples here cover all math keywords available in PCB programs.

FlatLand Commands

PCB includes first-class commands for interacting with the FlatLand 2D game engine. Scripts attached to game objects can create, move, and destroy entities in the world.

Links & Templates

Links are interfaces — named sets of method signatures declared with !-tagged cup labels. Templates are named types — cups with fields and methods, declared with #-tagged labels. Instances are created with @. When a template declares link conformance the runtime checks it at registration time and runs instantiation in a contract context.

Link Declaration

A link is a cup whose open label is prefixed with ! and whose close label uses the reversed name suffixed with ! — e.g. !Drawable{ … }elbawarD!. Method bodies inside a link are omitted — they are signatures only. Calling an unimplemented method throws RuntimeError.

!Drawable{
    fun draw(x, y)
    fun resize(factor)
}elbawarD!

!Serializable{
    fun  encode()
    nuf  edocne()
}elbazilaireS!

Template Declaration

A template is a cup whose open label is prefixed with # and whose close label uses the reversed name suffixed with #. All names on the close label are reversed — the template name, any &Link names, and the <Base name. Conformance against declared links is checked at registration time.

#Point{
    box x = 0
    box y = 0
    fun dist()
        return.(sqrt.(x*x + y*y))
}tnioP#

#Circle&Drawable{
    box radius = 5
    box color  = "red"
    fun draw(x, y)
        print.("circle r=" + radius + " at " + x + "," + y)
    fun resize(factor)
        radius = radius * factor
}elcriC&elbawarD#

#Widget&Drawable&Serializable{
    box id = 0
    fun  draw(x, y)   print.("widget " + id)
    fun  resize(f)    id = id + 1
    fun  encode()     return.(id)
    nuf  edocne()     nruter.(id)
}tegdiW&elbawarD&elbazilaireS#

#ColoredCircle&Drawable>Circle{
    box borderColor = "black"
    fun draw(x, y)
        print.("colored circle, border=" + borderColor)
    fun resize(factor)
        borderColor = "scaled"
}elcriCdereloC<elcriC&elbawarD#   // close: reversedName <reversedBase &reversedLinks #

Instantiation ( @ )

TypeName @ instanceName creates a new instance of the template and binds it to instanceName. The backward form swaps the order.

// forward
Circle @ c
draw.c.(10, 20)
resize.c.(2)
print.(c.radius)    // 10  (5 * 2)

// backward
c @ Circle

// two independent instances
Circle @ big
Circle @ small
resize.big.(10)
resize.small.(1)
print.(big.radius)    // 50
print.(small.radius)  // 5

Conformance Rules

Contract Context & Confidence

When a template declares at least one link, instantiation runs inside a contract context. Field initializers whose value chain-roots back to a seed global are preserved lazily — stored unevaluated rather than computed immediately. Literals and self-contained expressions evaluate eagerly as normal.

contractConfidence on the resulting instance is the ratio of lazy bindings to total bindings:

box globalTheme = "dark"   // seed global (tagged at startup)

#Button&Drawable{
    box label = "click me"     // eager — literal
    box theme = globalTheme.0  // lazy  — chain root is seed global
    box width = 100             // eager — literal
    fun draw(x, y)
        print.(label + " [" + theme + "]")
    fun resize(f)
        width = width * f
}nottuB&elbawarD#

Button @ btn
// btn.contractConfidence == 0.33  (1 lazy out of 3 total bindings)

Syntax Summary