--explain: Reading a Language You Don't Know - Writing

ilo is dense. sq x:n>n;*x x is a complete function definition, but if you haven’t seen ilo before you’d have no idea what each piece does. --explain annotates it.

What it produces

ilo 'sq x:n>n;*x x apl fn:F n n x:n>n;fn x' --explain

sq x:n>n              -- fn start
   x:n                -- param → number
   >n                 -- returns number
   *x x               -- return

apl fn:F n n x:n>n    -- fn start
   fn:F n n           -- param → fn(number) → number
   x:n                -- param → number
   >n                 -- returns number
   fn x               -- return

Each statement gets its structural role as a comment, aligned at a consistent column. The body is expanded to one statement per line regardless of how the source was written.

Why this matters for agents

ilo programs can be written as a single line - that’s the whole point. But a single-line program is opaque to an agent trying to understand or modify it. --explain gives the agent a structured view without changing the source.

A typical workflow: agent receives an ilo program, runs --explain to understand the structure, identifies which function and statement to modify, then generates the updated program. The annotation is the map.

What the roles mean

fn start - the function signature: name, params, return type
param → type - a parameter with its type expanded to plain English
returns type - the return type
bind → name - a let binding (x=expr)
guard - an early-return condition (>=x 0 val)
match - a pattern match
foreach → binding - a loop over a collection
return - the last expression in a function body (implicit return)

The roles map directly to the ilo constructs.

For humans too

--explain was designed for agents but it turns out to be the best way to introduce ilo to people. The dense format is efficient but opaque - the expanded, annotated view is what you want when reading someone else’s code or coming back to your own after a week.

ilo program.ilo --explain

Works on files too. Shows the filename as a header, then each function in expanded form.

The file header

file: program.ilo

sq x:n>n              -- fn start
   ...

When run on a file, --explain prepends the filename. Useful when an agent is working across multiple files and needs to keep track of context.