OM# Documentation

Patch Box

Patch boxes are the principal way of manipulating abstractions in OM#.

See also: Patching in OM#

Patches can be created with the File/New/ menu or the Ctrl/⌘ + N shortcut.
They are saved as .opat files which can be used as global abstractions.

Internal patch abstractions can be created from the Box/Add Box… menu or typing patch, or p in the same text field you would use to type a function or class name (displayed with double-click or using the N keyboard shortcut).

Ins and Outs

In functional programming languages, it is common to define abstraction as turning one or several terms of a function into variables.
For instance, let’s consider the Lisp expression (+ 5 1). If 5 is turned into a variable x, then this expression becomes the function f(x) = x + 1 ; or in the Lisp syntax, the lambda expression (lambda (x) (+ x 1)), which adds 1 to its input (or “argument”).
When the functions called (or applied) in a given context, each variable (argument) is bound to a value coming from this context.

In OM#, abstraction are internally compiled into Lisp functions. Turning a patch into an abstraction requires including in this patch at least one “output” box, determining the result or return value(s) of the abstraction, and a number (0 or more) “input” boxes, determining the inputs or arguments (or in other words, the variables of the abstraction).

In order to include an input or output in a patch, you can use one of the following options:

  1. Type in or `out in the same text field you would use to type a function or class name (displayed with double-click or using the N keyboard shortcut).

  2. Use the menus “Boxes/Add Box/Input” / “Boxes/Add Box/Output”, then click somewhere in the container patch to create the new input or output box.

→ Connect the input and output boxes respectively to the parameters and results of the abstraction

In / Out boxes correspond to the inlets / outlets of the abstraction boxes referring to the patch you are editing.

Renaming inputs and output

In and Out boxes can be renamed by double-clicking on the name label.

Giving consistent/meaningful names to the inputs and outputs is recommended for better readability and easier use of a patch inside container patches, but the names have no influence on the patch execution (much like a variable name in standard text programming).

Input default value

Input boxes have themselves optional inlets. These inlets can be used to connect default values, which will be used for internal evaluations of the patch boxes.

The default values (that is, anything connected above input boxes) are not taken into account in the compilation of the patch, nor “outside” in the evaluation of the abstraction boxes referring to the patch.

The Lisp-equivalent “lambda” expression of the edited patch can be displayed on the patch side panel as long as at least one output box is present, and will be computed (just like during the patch compilation) from this or these output box(es). Input boxes are considered as the arguments of the expression.

Encapsulation

Encapsulation creates an internal abstraction from selected boxes in a patch.
Every connection excluded from the encapsulation becomes input or an output of the abstraction.
To encapsulate selected boxes, use the corresponding “Boxes / Encapsulate selection” menu or the shift + E shortcut.

The inverse mechanism (“un-encapsulation”) can be used to remove an abstraction and include its contents in the containing patch.
To un-encapsulate an abstraction, use the “Boxes / Unencapsulate selection” menu or the shift + U shortcut.

Display

Abstraction boxes offer three visualization modes, which can be switched from the View item of the inspector panel, or using the M keyboard shortcut :