How osen evaluates

Implementation — for embedders and module authors

Implementation

A program is a bundle, and that is not a metaphor

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, /_e, /_s and /_c onto /_d — that is a frame
3. brackets /_e with the two () scope markers you saw in section 2
4. runs the body
5. on return, restores the four from the frame; the markers tell the finaliser which part of the environment was the caller’s

The markers and the saved copy are two halves of one mechanism: the copy is the record of where the caller’s environment started, and replacing /_e with it on return is also the only thing that removes the markers.

A frame is four elements of /_d, one set per call still in progress.

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 scope rule in section 8 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. Doing it twice trips an assertion in ose_getNthPayloadItem() and takes the prompt down.

3. A computed assignment inside a quotation appears in the result only if the name is NEW. Section 5 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.