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, and Rust expressions implement the computations inside those blocks. The same validated flow becomes ordinary Rust code and a readable diagram, whether a person or AI wrote it.
Work in progress.
A first flow: FizzBuzz
A flow is a Rust function marked with #[kaa].
use kaa;
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 #[kaa] 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. 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 | #[kaa::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:
| 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
| 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
use Ordering;
use kaa;
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
gallery examples,
with SVGs generated from their source through cargo kaalang. 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:
Both versions follow the same path.
Stages in practice: quicksort
use Ordering;
use kaa;
pub
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:
Types
A struct, enum, union, or type alias marked #[kaa] is a datatype. Its fields
carry descriptions, and a field can name the type it stands for, even when Rust
stores only a key:
value describes a field. refer also names the type the field refers to:
Payment stores the order's number, and refers to Order. The annotations do
not change the Rust declaration, and Rust checks that each target exists.
A type's diagram draws it under every type that refers to it:
The diagram combines self-references, a tuple identifier with
repr(transparent), generic events, a borrowed receipt, an enum with repr(u8)
and both tuple and named fields, and an alias.
A type's name and its fields, like a flow's name in its start node, carry a UML
visibility marker: + for pub, ~ for pub(crate) and other restricted
forms, and - for private.
Try it
Add the macro to a project:
Install the released CLI from crates.io:
Or install the version from the current repository checkout:
Run the gallery and its checks from a repository checkout.
Draw the FizzBuzz diagram through the CLI.
The flow is named by its path from the crate root; --collapse-cycles draws the
collapsed cycle view. The output is a standalone SVG that needs no external
rendering tools.
Draw the Order type the same way, by its path:
Read more
- RFCs, the source of truth for syntax, semantics, and diagrams.
- Contributing