Skip to content

README: add diagrams for noop and trailing-stop behaviors #87

@mellonis

Description

@mellonis

Motivation

Two PostMachine conventions are mentioned in prose but not visually illustrated. Both are subtle enough that a small Mermaid diagram alongside an example would shorten the path from "I read the docs" to "I understand what the graph looks like."

(1) noop — the fall-through pass-through

noop is the "do nothing, advance to the next instruction" command. Visually it's a state with a single [*] → [K]/[S] self-targeting transition to the next instruction's State. Useful when teaching:

  • The pattern noop(20) as an unconditional jump from any instruction to 20.
  • How grouping interacts with noop (grouped noop becomes a no-op step in the chain).
  • Why noop is sometimes preferred over right(20) etc. — when you don't want to mutate the tape.

Suggested addition: short <details>-collapsed Mermaid block in the Commands or Quick start section showing a { 10: noop(30), 30: mark, 40: stop } machine. Pair with an examples.spec.ts test pinning the salient shape (one outgoing [*] arrow, no tape mutation).

(2) Trailing stop doesn't produce its own state node

Currently the Quick start prose hints at this: "The 40: stop instruction is elided — stop halts the machine, so the transition from 30: mark flows straight to halt rather than through an intermediate state."

But the visual consequence isn't pinned with its own diagram. A reader who tries { 10: mark, 20: stop } and inspects the emit might be surprised to see only ONE non-halt state (s10), not two.

Suggested addition: a tiny Mermaid block alongside the prose showing:

flowchart TD
  s0(((halt)))
  s1["10"]
  idle([idle])
  idle -. enter .-> s1
  s1 -- "[*] → ['*']/[S]" --> s0
Loading

— and an explicit "notice: no s20 for the stop; the engine routes directly to s0" line.

Scope

  • Single-package change (@post-machine-js/machine README).
  • Two added <details> blocks + two test assertions in examples.spec.ts.
  • No code change. Strictly documentation.

Cross-refs

Metadata

Metadata

Assignees

No one assigned

    Labels

    v7Targets v7 release (composition-representation overhaul)

    Projects

    Status
    Done

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions