kaalang
We be of one blood, thou and I - man and snake together.
Kaa - from Rudyard Kipling's “The Spring Running”, The Second Jungle Book
kaalang is a visual flow dialect of Rust for understanding what a program does and how its parts fit together. Inspired by DRAKON, it makes the structure of an algorithm explicit in code.
You write an algorithm as described steps, decisions, and cycles, with explicit inputs and outputs. Rust expressions implement the computations inside those blocks. The same validated flow becomes ordinary Rust code and a readable diagram.
Whether written by a person or AI, the code keeps its decisions and dependencies explicit, while descriptions explain each step's purpose. That makes the flow easier to read, explain, change, and review.
Work in progress.
A first flow: FizzBuzz
A flow is a Rust function marked with #[kaalang]. Here, it chooses what to say
based on whether a number is divisible by three, five, both, or neither.
use kaalang;
Reading the flow
A wire is a named value passed between blocks. The function parameter
provides the first wire, number. Each block lists the wires it captures
between |...| and names the wires it produces after let.
| In the example | What happens |
|---|---|
let (fizz_buzz, fizz, buzz, plain) = ... |
The choice evaluates its match and provides only the selected output. Cases, outputs, and match arms correspond by position. |
let end = |fizz| ... |
Capturing fizz places this action on the Fizz branch, even though its body does not use that unit value. |
Four declarations of end |
The branches are mutually exclusive. Their results merge into one wire for the shared continuation. |
|end| return end; |
The flow returns whichever branch supplied end. |
For number = 9, only fizz is selected, so only the “Use Fizz for this
number” action runs. The diagram's connections show execution paths; input and
output names appear as labels along those paths.
The #[kaalang] macro translates the capture notation into ordinary Rust
bindings and control flow. Blocks execute in source order along the selected
path. Rust checks types, ownership, borrowing, and lifetimes.
The diagram is generated from the same validated model used to produce the Rust code. kaalang checks that the flow admits a diagram under its visual rules before compiling it.
Anatomy of a block
Here is the last action from FizzBuzz, with its Rust body wrapped in braces:
// kind + description
let end = ;
| Part | In this action | Variations |
|---|---|---|
| Kind and description | #[action("...")] |
Both are required for an action. The description labels its diagram node. |
| Outputs | let end = |
Omit for an effect returning (). Use let (left, right) = to expose two outputs. |
| Inputs | |plain| |
Omit it when there are no inputs. Every wire used by the body must be listed here. |
| Body | { plain.to_string() } |
A Rust expression. An action may omit the braces, as in the full example. |
Actions can also create a value without inputs, consume inputs without producing outputs, or perform an effect with neither:
// No inputs: the capture list can be omitted.
let number = 15;
// No outputs.
|&end| ;
// Neither: the empty capture list can be omitted too.
;
Captures express how an action accesses a wire:
| Input | Access |
|---|---|
name |
Move or copy the value. |
mut name |
Move or copy into a mutable local binding. |
&name |
Borrow the value. |
&mut name |
Mutably borrow a wire declared mutable. |
Formatting descriptions
Descriptions accept a small inline notation, so a label can stress a condition, name a piece of code, or show a formula:
| Write | Shows |
|---|---|
**bold** or __bold__, *italic* or _italic_, ~~struck~~ |
Bold, italic, strikethrough |
`code` |
Inline code |
x^2^, H~2~O |
Superscript, subscript |
> quote at the start of a line |
A quoted line |
$\sqrt{x}$, $$\sum_i x_i$$ |
Inline TeX formula; $$…$$ uses display layout |
<u>…</u>, <mark>…</mark>, <color name="red">…</color> |
Underline, highlight, palette color (red, green, blue, purple, muted) |
The Write column shows the description text. In an ordinary Rust string, double
each backslash and escape each quote, as in "$\\sqrt{x}$", or use a raw string
such as r#"<color name="red">…</color>"#. Formatting changes only the diagram;
the generated Rust is the same. A marker without its pair stays literal, and a
backslash before a marker keeps it literal: \\* in an ordinary string, \* in
a raw one. Diagrams show
the text effects,
formulas,
and
literal fallbacks.
Block kinds
FizzBuzz uses choice, action, and return. The other kinds let a flow ask
a yes/no question, call an existing function, repeat a sequence, or organize
work into named stages:
| Kind | Role in a flow |
|---|---|
action |
Perform a computation or effect with a Rust expression. |
call |
Call one named Rust function. Its path supplies the description if omitted. |
question |
Select one of two branch outputs using a boolean expression. |
choice |
Select one output from the cases of a Rust match. |
cycle |
Repeat a nested kaalang sequence whose blocks capture the surrounding wires. |
stage |
Group blocks into a named step selected by an incoming signal. |
continue |
Start the next iteration of the directly containing loop cycle. |
return |
Complete the root flow and hand back its result. |
Actions, calls, and cycles can have no outputs. Questions and choices always
declare their branch outputs. A cycle takes one of two forms. A loop cycle's
loop { ... } body contains kaalang blocks. A route through it can repeat at
its continue, complete with one of its declared outputs, or diverge in a
nested cycle. A completed output becomes available after the cycle. In the
diagram, continue routes meet at the cycle's back edge, and completing routes
leave through the cycle boundary. A for cycle, written
|items| for item in items { ... }, instead runs its body once per item of a
Rust iterator. It has no continue or early exit and may declare one output,
the signal that its items ran out. Its diagram has no boundary or back edge: a
for-entry node holds the description and hands over the item, and every
iteration ends at a for-end node below it, which repeats the description and
from which the flow continues once the items run out.
Putting it together: binary search
Searching a sorted slice adds state and repetition. Each iteration checks
whether any candidates remain, compares the middle value with the target, and
either narrows the range or finishes with Some(index) or None.
use Ordering;
use kaalang;
The cycle's blocks capture the surrounding left and right, declared mut so
the less and greater branches can update them. Both then produce stepped,
merging before the shared continue that starts the next iteration. The equal
and leave branches instead produce result, the cycle's declared output. They
merge at the end of the body, and the cycle hands result to the flow, which
returns it.
The cycle's description and interface remain visible while its body is hidden.
Both examples are executable gallery tests, with SVGs generated from their source. The gallery also includes swap, a flow that returns its inputs without a computational block, bubble sort, with nested cycles, quicksort, with stages for in-place partitioning and recursion, and KMP search, with stages for comparison, advancement, and prefix fallback.
Stages
Stages make the steps of a state machine explicit. The compiler generates the
dispatch loop, and the diagram labels transitions between stages. A stage's
header names the signal that enters it. A stage moves to another by producing
that stage's signal as one of its declared outputs, and the stage that holds
return comes last.
This empty state machine only follows First → Second → Finish. With stages:
Without stages, the diagram shows the cycle and the choice that selects the current state:
After each state update, control returns to the choice. Selecting Finish
leaves the cycle and reaches the return. Both versions follow the same path.
Stages in practice: quicksort
Quicksort sorts a slice in place. Its stages check whether work remains, partition the range around a pivot, sort the smaller group recursively, and finish:
use Ordering;
use kaalang;
pub
The partitioning cycle groups values below, equal to, and above the pivot. Only
the smaller outer group is sorted recursively. The values signal sends the
larger group back to the first stage, keeping the recursive call stack
logarithmic.
With the partitioning cycle collapsed, the four stages are easier to see:
Try it
Add the macro to a project:
Install the released CLI from crates.io:
Or install the version from the current repository checkout:
From a repository checkout, draw the FizzBuzz example:
Open fizzbuzz.svg in a browser. Replace the source path and flow name to
render another example; add --collapse-cycles for the compact cycle view shown
above. The output is a standalone SVG with no external rendering tools required.
Read more
- RFCs, the source of truth for syntax, semantics, and diagrams.
- Contributing