How osen evaluates

Implementation — for embedders and module authors

Implementation

A program is a bundle

Everything the machine holds is OpenSoundControl. A value is a message, a program is a bundle. When you type

/r : (/q, 2) /o/add

the parser does not build a syntax tree. It builds an OSC bundle, and the pieces you wrote turn into string items inside it:

/r  …  "/q"  "/!/$"  …  "/o/add"  "/!/$"  "/!/o/apply"

Two things are worth seeing there. /r became a message address — that is what an assignment looks like. And /q became a string followed by "/!/$", which is the instruction look this name up. Reading a name and binding one are different shapes in the bundle, which is why a tool can tell them apart without re-parsing anything.

One line, start to finish

(1, 2) /o/add
# → : 3

The cycle is: take the next element from /_i, put it in /_c, dispatch on its address, drop it, repeat. Dispatching (1, 2) pushes a bundle on the stack; dispatching /o/add’s lookup-and-apply pair finds the function and runs it; the answer is left on /_s, and the REPL prints what is there.

Quotations — { … }

A quotation is a deferred bundle expression, evaluated in the ambient environment, whose results become the elements of the bundle it returns. It reads dynamically and writes nowhere. These are its four properties.

It does not run when you write it:

/q : { (1,2) /o/add }, /q

A box prints : { : <thunk> }; a prompt prints the instructions inside the braces instead.

To run one, convert it to a bundle element and execute it:

/q : { (1,2) /o/add },
(/q /!/toelem/fromblob) /!/o/exec
# → ( ( : 3 ) )

It reads where it runs, not where it was written:

/x : 42, /q : { /x }, /x : 99,
(/q /!/toelem/fromblob) /!/o/exec
# → ( ( : 99 ) )

Its bindings do not escape, but they are elements of what it returns:

/g : { /z : 5 }, (/g /!/toelem/fromblob) /!/o/exec, /z
# → /z is not bound

/g : { /z : 5 }, (/g /!/toelem/fromblob) /!/o/exec
# → ( ( /z : 5 ) )

/h : { /a : 1, /b : 2, 99 }, (/h /!/toelem/fromblob) /!/o/exec
# → ( ( /a : 1, /b : 2, : 99 ) )

Named results keep their names, anonymous ones stay anonymous, in order. The nearest thing in another language is Nix’s { … } or a Jsonnet object: a record constructor that can see the surrounding scope.

What a call does

Applying a function:

1. binds the arguments, captures and ambient names into a fragment, and prepends it to /_e — so they shadow what is already there
2. saves /_i, the stack below the call and /_c onto /_d as one element, a bundle whose header marks it as a frame and records which registers it holds; a register that was empty is left out — that is a frame
3. brackets /_e with the two () scope markers you saw under The registers
4. runs the body
5. on return, restores what the frame holds, and cuts /_e back to the caller’s part, which the markers delimit

The frame does not copy the environment. The caller’s bindings stay where they are, in /_e behind the markers, and the markers are the record of where the caller’s environment starts: on return, everything the call put in front of them goes, and the markers with it.

A frame is one element of /_d per call still in progress, and (m, k) /o/frame reads frame k of a machine m.

Why any of this is shaped this way

Because a computation can stop and move. The five registers are a machine; /continue/after snapshots it, hands it to the host, and the host puts it back later — possibly on a different machine. Everything above is arranged so that what is running is a value that can be written to a socket: no pointers in it, no state outside the bundle, nothing that only makes sense in this process.

It is also why the rule under Scope is worth reading twice. A function that reads its caller’s bindings means something different depending on who called it, and “who called it” may be on another machine.

More things that surprise people

1. There are two applies, at two layers. /!/funcall is ose’s; /!/o/exec is osen’s. Reaching for the wrong one does not fail: /!/funcall on a quotation hands back the unevaluated program rather than running it.
2. A { … } has to become an element before it can run, via /!/toelem/fromblob. Converting one that is already an element is refused.

3. A computed assignment inside a quotation appears in the result only if the name is NEW. Quotations, above, says a quotation’s bindings become elements of what it returns, and the finaliser does not care whether a name got there by syntax or by a verb – it collects what was written inside the scope markers. /o/assign/toreg PREPENDS when the name is new, which lands inside them, and OVERWRITES IN PLACE when the name already exists outside, which does not:

   { ("/_e", 42, "/x") /o/assign/toreg, /done : 1 }  exec
                                →  ( : [], /done : 1, /x : 42 )
   /x : 9,
   { ("/_e", 42, "/x") /o/assign/toreg, /done : 1 }  exec
                                →  ( : [], /done : 1 )
   

   The difference is invisible in the source: it depends on what was bound before the quotation was run.

4. /o/assign takes a BUNDLE, a value and an address, and it is a pure function. Not the two-argument verb its name suggests, and not a mutation at all: it answers a new bundle with the binding added.

    ( (), 42, "/x" ) /o/assign          →  ( /x : 42 )
    ( (/a : 1), 42, "/x" ) /o/assign    →  ( /a : 1, /x : 42 )
    ("/x", 42) /o/assign                →  wrong number of elements
   

   That is the difference from /o/assign/toreg, which names a register to write into – ("/_e", 42, "/x") /o/assign/toreg binds /x for real. One hands you a value, the other changes the environment, and the names do not say which.