Chainlang

Chainlang Specification

Chainlang is a graph-based esolang where each link holds exactly one atomic instruction. Links are connected through explicit references, forming an execution graph that drives program logic. NOTE: I made an AI make this spec, don't expect it to be perfect

General Principles

• Each link must contain exactly one command
• Link names can be any valid identifier (numbers, letters, symbols)
• Execution begins with a `jump` into a link
• Control flows through `connect`
• Links can be dynamically created, deleted, and mutated using stack values and symbolic references
• Conditionals and loops are formed through stack-driven jumps

Core Commands

Stack Manipulation

• `push VALUE` — Pushes a numeric value onto the stack
• `pop` — Pops the top value off the stack
• `print` — Prints the top stack value
• `input` — Asks the user for a numeric input and pushes it to the stack

Arithmetic

• `add` — Adds the top two values (`A + B`)
• `subtract` — Subtracts (`A - B`)
• `multiply` — Multiplies (`A * B`)
• `divide` — Integer division (`A / B`)
• `mod` — Remainder of (`A % B`), where second-from-top mod top

Symbol and Variable Handling

• `ref SYMBOL` — Assigns the top stack value to SYMBOL or retrieves the value of SYMBOL onto the stack
  • Usage depends on context; most often used for variables

Control Flow

• `jump LINKNAME` — Immediately jumps into the given link
• `connect A -> B` — Connects link A to B so execution flows into B after A
• `return` — Ends execution if entered from a `jump`; returns control

Conditional Execution

• `if LINKNAME` — If the top stack value is zero, jumps to LINKNAME; otherwise continues

Metaprogramming

• `create NAME as: COMMAND` — Creates a link called NAME with the given one-command instruction
• `delete NAME` — Deletes the specified link

Execution Behavior

• Links are executed one by one following `connect` relationships
• Only links created with `create` are valid entry points
• Stack values control dynamic logic and memory
• You can simulate structured behaviors (e.g., loops, memory access, function calls) through graph composition

Example Program

Print the number 5:

A: create print5 as: push 5
B: create linkB as: print
C: create linkC as: return
D: connect print5 -> linkB
E: connect linkB -> linkC
F: jump print5

Advanced Constructs

Stack Simulation (Symbolic)

G: push 42
H: ref value
I: ref stackIndex
J: create stack_stackIndex as: push value
K: push stackIndex
L: push 1
M: add
N: ref stackIndex
O: pop

To pop:

P: push stackIndex
Q: push -1
R: add
S: ref stackIndex
T: delete stack_stackIndex

Tape (Memory Cell Simulation)

• Store pointer index in `ptr`
• Create cells dynamically as `cell_0`, `cell_1`, etc.
• Access by:

U: push ptr
V: ref cell_ptr
W: push cell_ptr

Update cell:

X: push NEW_VALUE
Y: ref cell_ptr
Z: pop

Pointer Wraparound

When `ptr < 0`, wrap to end:

AA: push ptr
AB: push 0
AC: subtract
AD: push 0
AE: if wrapToEnd
AF: jump continue
AG: create wrapToEnd as: push tapeLength
AH: ref ptr

When `ptr >= tapeLength`, wrap to start:

AI: push ptr
AJ: push tapeLength
AK: subtract
AL: push 0
AM: if wrapToStart
AN: jump continue
AO: create wrapToStart as: push 0
AP: ref ptr

=== Equality (Simulated) Check if `A == B`:

AQ: push A
AR: push B
AS: subtract
AT: push 0
AU: if equalBranch

=== Loop Stack Simulation Push to loop stack:

AV: ref loopIndex
AW: create loop_loopIndex as: push LOCATION
AX: push loopIndex
AY: push 1
AZ: add
BA: ref loopIndex

Pop from loop stack:

BB: push loopIndex
BC: push -1
BD: add
BE: ref loopIndex
BF: delete loop_loopIndex

=== Command Dispatch Interpreter uses numbered commands:

BG: create command_0 as: jump bf+_1
BH: create command_1 as: jump bf+_1
BI: create command_2 as: jump bf._1

=== Brainfuck Command Chain (e.g. `+`)

BJ: create bf+_1 as: push ptr
BK: create bf+_2 as: ref cell_ptr
BL: create bf+_3 as: push cell_ptr
BM: create bf+_4 as: push 1
BN: create bf+_5 as: add
BO: create bf+_6 as: ref cell_ptr
BP: create bf+_7 as: return
BQ: connect bf+_1 -> bf+_2
BR: connect bf+_2 -> bf+_3
BS: connect bf+_3 -> bf+_4
BT: connect bf+_4 -> bf+_5
BU: connect bf+_5 -> bf+_6
BV: connect bf+_6 -> bf+_7

Error Messages (Optional, Stylized)

• `"That link already exists. You summoned it twice."`
• `"You tried to ref nothing. Void cannot be reasoned with."`
• `"Modulo by zero? I'm not dividing by dreams."`
• `"That link doesn’t exist. Try inventing it first."`

Summary

Chainlang is a minimalist esolang built around atomic execution links, composable logic, and dynamic modification. With stack control, symbolic references, conditionals, and metaprogramming, you can construct interpreters, puzzles, and even nested languages like Brainfuck inside Chainlang itself.