MLPL Basics – a Literate Tour
the web "Basics" demo, recreated as runnable Org-babel
Table of Contents
This document recreates the Basics demo from the MLPL web playground as a literate program. Every step below is a live MLPL source block: when this file is published (see Publishing this document) each block is evaluated in order, the output is captured beneath it, and the prose ties the steps together.
The blocks share one :session basics, so a variable bound in an early
block is still in scope later – exactly like typing successive lines
into the REPL. That session is the whole point of this tour: MLPL state
persists across "REPL lines", and Org-babel lets us narrate each line.
1. Scalar arithmetic
MLPL starts where every language does: arithmetic. Operators are ordinary infix; a bare expression on its own line echoes its value.
1 + 2
3
Multiplication is the same shape:
3 * 4
12
One thing that surprises NumPy refugees: every number is an f64.
There is no integer type and therefore no integer division – 10 / 3
is a true ratio, not a floored 3.
10 / 3
3.3333333333333335
2. Arrays and broadcasting
Arrays are written with brackets. Binary operators apply elementwise, so two equal-length vectors add position by position:
[1, 2, 3] + [4, 5, 6]
5 7 9
When one side is a scalar it broadcasts across the whole array – the
10 below is applied to each element rather than requiring a vector of
tens:
[1, 2, 3] * 10
10 20 30
3. Variables persist across blocks
Here is where the session earns its keep. Binding x produces no
output – assignment is silent – but the name is now part of the
session.
x = [10, 20, 30]
The next block is a separate source block, evaluated as its own step,
yet x is still in scope. y is a new vector; x is untouched
(arrays are values, not mutated in place):
y = x + 1 y
11 21 31
To prove x survived unchanged, echo it again from yet another block:
x
10 20 30
4. Unary negation
Finally, the unary minus negates every element – a one-character demonstration that prefix operators broadcast just like the binary ones:
-[1, 2, 3]
-1 -2 -3
And because the session is still live, we can negate the x we bound
three blocks ago:
-x
-10 -20 -30
5. Takeaway
Operators apply elementwise; scalars broadcast; variables persist
across blocks (REPL lines). That is the substrate every other MLPL demo
builds on. The same :session mechanism scales to the larger demos –
loss curves, autograd training loops, attention maps – where each step
depends on state the previous steps established.
Publishing this document
To run every block and produce a standalone HTML file, in batch, with no interactive Emacs:
./examples/literate/publish.sh examples/literate/basics.org
That script launches emacs -Q --batch, loads the MLPL Org-babel
support via elisp/mlpl-all.el (which resolves the mlpl-repl binary
for you), resets the session, evaluates the buffer top to bottom, and
exports basics.html next to this file.