Introduction

The design goal of the plugin bundle was to create a tool to easily add realtime programmable logic glue in LV2 plugin graphs.

To have plugins which do a specific task efficiently is great, especially for audio plugins. LV2 stands apart from other audio plugin specifications with its extentable event system based on Atoms. As events can be much more varied in nature and represent pretty much anything (NOT ONLY MIDI), it would be useful to have a tool to create arbitrary event filters for a given setup on-the-fly.

For a given setup, one may need a special event filter only once and it seems to be overkill to write a native LV2 event filter in C/C++ just for that. It would also be nice to have a tool for fast prototyping of new event filters.

A scripting language seems to be ideal for these cases, where the user can write an event filter on a higher level of abstraction on-the-fly. The scripting language needs to be realtime safe, though, which restricts the choices dramatically.

One such scripting language is Lua. It is small, fast, easily embeddable and realtime-safe if coupled to a realtime-safe memory allocator like TLSF.

The Moony plugins can handle LV2 control and atom event ports, only. They do not handle LV2 audio ports. Control port values are internally handled as simple floating point numbers, whereas the atom event ports build on top of the LV2 atom and atom forge C headers.

Plugin Variants

The Moony plugin bundle ships with multiple plugin variants, whereas all of them share the same API but with different configurations of input and output ports. Depending on the users's usage scenario, one or the other variant may be preferable.

Plugin variants only differ in number of control and atom event input and output ports. Apart from this difference, they can often be used interchangeably.

C1 x C1

This plugin variant features a single control port input and a single control port output.

-- C1 x C1 prototype 'run' function

function run(n, control, notify, c)
  return c
end

C2 x C2

This plugin variant features two control port inputs and two control port outputs.

-- C2 x C2 prototype 'run' function

function run(n, control, notify, c1, c2)
  return c1, c2
end

C4 x C4

This plugin variant features four control port inputs and four control port outputs.

-- C4 x C4 prototype 'run' function

function run(n, control, notify, c1, c2, c3, c4)
  return c1, c2, c3, c4
end

A1 x A1

This plugin variant features a single atom port input and a single atom port output.

-- A1 x A1 prototype 'run' function

function run(n, control, notify, seq, forge)
end

A2 x A2

This plugin variant features two atom port inputs and two atom port outputs.

-- A2 x A2 prototype 'run' function

function run(n, control, notify, seq1, forge1, seq2, forge2)
end

A4 x A4

This plugin variant features four atom port inputs and four atom port outputs.

-- A4 x A4 prototype 'run' function

function run(n, control, notify, seq1, forge1, seq2, forge2, seq3, forge3, seq4, forge4)
end

C1+A1 x C1+A1

This plugin variant features a single control port input and a single control port output with a single atom port input and a single atom port output.

-- C1+A1 x C1+A1 prototype 'run' function

function run(n, control, notify, seq, forge, c)
  return c
end

C2+A1 x C2+A1

This plugin variant features two control port inputs and two control port outputs with a single atom port input and a single atom port output.

-- C2+A1 x C2+A1 prototype 'run' function

function run(n, control, notify, seq, forge, c1, c2)
  return c1, c2
end

C4+A1 x C4+A1

This plugin variant features four control port inputs and four control port outputs with a single atom port input and a single atom port output.

-- C4+A1 x C4+A1 prototype 'run' function

function run(n, control, notify, seq, forge, c1, c2, c3, c4)
  return c1, c2, c3, c4
end

Lua libraries

Moony runs its Lua interpreter in sandboxed mode, e.g. because of its real-time requirements, Moony cannot provide any access to blocking functions like file I/O and pipes. Only the following standard Lua libraries are enabled:

• base
• coroutine
• table
• string
• math
• utf8
• debug

The following standard Lua libraries are disabled:

• io
• package
• os

The following base functions are disabled:

• loadfile
• dofile

The following math functions are disabled (use the dedicated random utility library instead):

• math.random
• math.randomseed

Additionally to the standard libraries, Moony ships the following commonly used utility libraries:

• lpeg
• base64
• ascii85
• mathx
• complex
• random

Log & Debug

Whenever you want to log or debug something while developing your scripts, you can easily dump any value via Lua's print function. The print's output will be shown on the UI and also be sent to the host's log backend, e.g. to a log window or console.

-- sends 'hello world' to the UI and the host's log backend

print('hello world')

Callbacks

Moony can run user defined callbacks at different positions in its processing graph. If the user provides an implementation for a specific callback, Moony will run the latter. If the plugin does not need a specific callback, the latter can simply be omitted. The implementations of all callbacks are thus optional.

run

The run callback function is the main callback function and thus the most important one. It is called once per period by the plugin host. The period size, e.g. the number of audio samples the function is called for may be chosen arbitrary by the host. Do not expect it to be constant.

Depending on the plugin variant, the run function takes variable amount of arguments. All variants have the first and last two arguments in common, though.

If a plugin has input event ports, sequence objects (Lua userdata) will be given to the run function whose events can be iterated over.

If a plugin has output event ports, forge objects (Lua userdata) will be given to the run function which can be filled with arbitrary atom event structures.

If a plugin has input control ports, those values will be given to the run function as native Lua numbers.

If a plugin has output control ports, the run function is expected to return native Lua numbers, missing return values will be set to 0.0.

function run(n, control, notify, seq1, forge1, ..., c1, ...)

n (integer)

number of audio samples of current period

{control, notify} (userdata, userdata)

pair of atom sequence and atom forge object for communication with UI

{seq, forge} [x] (userdata, userdata)

pairs of atom sequence and atom forge objects, with x=[0, 1, 2, 4]

c [x] (number)

control port inputs, with x=[0, 1, 2, 4]

(number)

control port outputs, with x=[0, 1, 2, 4]

-- 'run' callback prototype for moony#a1xa1

function run(n, control, notify, seq, forge)
  -- here we will process events
end

once

The once function exists for pure convenience only. It has exactly the same form as the run function, but is called only once after the whole script code is loaded or updated.

The once function will run directly before the run function, it therefore is no replacement for the latter in a given update period, but and extension to it.

Put logic here that needs to run once after script code update, e.g. registering a new StateResponder.

function once(n, control, notify, seq1, forge1, ..., c1, ...)

n (integer)

number of audio samples of current period

{control, notify} (userdata, userdata)

pair of atom sequence and atom forge object for communication with UI

{seq, forge} [x] (userdata, userdata)

pairs of atom sequence and atom forge objects, with x=[0, 1, 2, 4]

c [x] (number)

control port inputs, with x=[0, 1, 2, 4]

-- 'once' callback prototype for moony#a1xa1

function once(n, control, notify, seq, forge)
  -- here we will run logic once right after a code update

  -- send all-notes-off MIDI message on all channels
  for channel = 0x0, 0xf do
    forge:time(0):midi(MIDI.Controller | channel, MIDI.AllNotesOff)
  end
end

stash

When script code is reloaded, plugin state inside Lua virtual machine potentially is lost. In order to preserve state across a script code reload, arbitrary state can be serialized and parked in temporary memory. Such a temporary serialized state can later be deserialized via apply.

The stash function is directly called before switching to the new script code.

function stash(forge)

forge (userdata)

atom forge object to serialize to

-- 'stash' callback prototype

-- a simple flag
local myflag = true

function stash(forge)
  -- serialize single boolean flag
  forge:bool(myflag)
end

function apply(atom)
  assert(atom.type == Atom.Bool)

  -- deserialize single boolean flag
  myflag = atom.body
  assert(myflag == true)
end

apply

When script code is reloaded, plugin state inside Lua virtual machine potentially is lost. In order to preserve state across a script code reload, arbitrary state previously serialized by stash can be deserialized from temporary memory.

The apply function is directly called after switching to the new script code.

function apply(atom)

atom (userdata)

atom object to deserialize from

-- 'apply' callback prototype

-- table that holds active notes
local active_notes = {
  60, 64, 67, 72
}

function stash(forge)
  local tup = forge:tuple()

  -- serialize active notes to atom tuple
  for i, v in ipairs(active_notes) do
    tup:int(v)
  end

  tup:pop()
end

function apply(atom)
  assert(atom.type == Atom.Tuple)

  -- clear active notes table
  active_notes = {}

  -- deserialize active notes from atom tuple
  for i, v in atom:foreach() do
    assert(v.type == Atom.Int)

    active_notes[i] = v.body
  end

  assert(#active_notes == 4)
end

save

The save function works analogously to stash, but instead of serializing to temporary memory before a script code reload, save serializes to disk upon a state save request issued by the host.

State serialized to disk by save is preserved across plugin instantiations and truly is the same as a preset.

function save(forge)

forge (userdata)

atom forge object to serialize to

-- 'save' callback prototype

local urn = Mapper('urn:uuid:6f7e2445-ae5f-4e2e-ae11-9a5cfb1b5d1e#')

-- state
local state = {
  [urn.foo] = {
    [RDFS.range] = Atom.Int,
    [RDF.value] = 12
  },
  [urn.bar] = {
    [RDFS.range] = Atom.Chunk,
    [RDF.value] = string.char(0x0, 0x1, 0x2)
  }
}

function save(forge)
  local obj = forge:object()

  -- serialize state to atom object
  for k, v in pairs(state) do
    obj:key(k):typed(v[RDFS.range], v[RDF.value])
  end

  obj:pop()
end

function restore(atom)
  assert(atom.type == Atom.Object)

  -- deserialize state from atom object
  for k, v in pairs(state) do
    local itm = atom[k]

    if itm then
      assert(itm.type == v[RDFS.range])
      assert(itm.body == v[RDF.value])

      v[RDF.value] = itm.body
    end
  end
end

restore

The restore function works analogously to apply, but instead of deserializing from temporary memory after a script code reload, restore deserializes from disk upon a state reload request issued by the host.

If defined, the function is called upon each code reload with the most recently saved state directly after apply and before once or run.

function restore(atom)

atom (userdata)

atom object to deserialize from

-- 'restore' callback prototype

local urn = Mapper('urn:uuid:8fdd61cd-9c12-4366-b208-8306b37cb981#')

-- 3D positional state
local state = {
  [urn.position] = { 0.2, 0.3, 0.9 },
  [urn.rotation] = { -math.pi, 0.0, math.pi/2 }
}

function save(forge)
  local obj = forge:object()

  -- serialize state to atom object
  for k, v in pairs(state) do
    for vec in obj:key(k):vector(Atom.Float):autopop() do
      for i, w in ipairs(v) do
        vec:float(w)
      end
    end
  end

  obj:pop()
end

function restore(atom)
  assert(atom.type == Atom.Object)

  -- deserialize state from atom object
  for k, v in pairs(state) do
    local itm = atom[k]

    if itm then
      assert(itm.type == Atom.Vector)
      assert(itm.childType == Atom.Float)

      state[k] = { itm:unpack() }
      assert(#state[k] == 3)
    end
  end
end

Map & Unmap

LV2 references objects and their properties by URIs, usually rather long, unique string identifiers. When comparing URIs, whole strings need to be compared, which is inefficient. In LV2, an URI thus can be mapped to a simple integer URID, greatly increasing efficiency of comparisons. Unmapping from URID to original URI is supported, too.

Moony directly mirrors mapping and unmapping of the underlying low-level implementation, but additionally caches every newly queried URI or URID for faster lookup inside script code. Cached URIs and URIDs are not preserved across script code updates, though.

Map

Map an URI to its corresponding URID. Map is a first-class Lua table acting as a cache for all queried URIDs and can also be called as function.

Map:__call(URI) | Map(URI) | Map:__index(URI) | Map[URI]

URI (string)

URI to be mapped

(integer)

mapped URID

-- Map can be indexed or called as function

local prefix = 'http://example.com#'

local foo_urid = Map(prefix .. 'foo')
local bar_urid = Map[prefix .. 'bar']

Unmap

Unmap an URID to its original URI. Unmap is a first-class Lua table acting as a cache for all queried URIs and can also be called as function.

Unmap:__call(URID) | Unmap(URID) | Unmap:__index(URID) | Unmap[URID]

URID (integer)

URID to be unmapped

(string)

unmapped URI

-- Unmap can be indexed or called as function

local prefix = 'http://example.com#'

local foo_urid= Map(prefix .. 'foo')
local bar_urid = Map[prefix .. 'bar']

local foo_uri = Unmap(foo_urid)
local bar_uri = Unmap[bar_urid]

assert(prefix .. 'foo' == foo_uri)
assert(prefix .. 'bar' == bar_uri)

Mapper

A convenience wrapper and syntactic sugar around Map. Simplifies creating multiple mappings which share a common URI prefix.

Returns a table which can be queried by indexing with the URI postfix. The query is equivalent to a mapping of concatenated URI prefix and postfix.

This is especially useful when dealing with custom properties and the StateResponder.

Mapper(prefix)

prefix (string)

prefix string to be appended to

(table)

Mapper table

-- Mapper is a convenience wrapper over Map

local prefix = 'urn:uuid:d178f397-3179-4c38-9d25-31d60ffc5788#'
local mapper = Mapper(prefix)

local bar_urid = Map[prefix .. 'bar']

assert(mapper.bar == bar_urid)

Blank

Returns a unique, non-colliding integer ID to be used in event messaging. Especially useful for Patch messages or custom event systems where there is a need to track event properties over space and time.

Blank()

(integer)

unique integer ID

-- Blank returns unique integer IDs

local cache = {}

for i = 1, 100 do
  local id = Blank()

  assert(not cache[id])
  cache[id] = true
end

Forge

A forge object is used to serialize arbitrary complex atoms, both simple primitives and nested containers.

Primitive

Atom types that contain single data as part of their body are referred to as primitives.

Bool

Forge a boolean atom, e.g. of type Atom.Bool.

forge:bool(value)

value (boolean)

boolean value to forge

(userdata)

self forge object

-- Forge Bool

function stash_tuple(forge)
  forge:bool(true)
  forge:bool(false)
end

Int

Forge an integer atom, e.g. of type Atom.Int.

forge:int(value)

value (integer)

integer value to forge

(userdata)

self forge object

-- Forge Int

function stash(forge)
  forge:int(12)
end

Long

Forge long integer atom, e.g. of type Atom.Long.

forge:long(value)

value (integer)

integer value to forge

(userdata)

self forge object

-- Forge Long

function stash(forge)
  forge:long(12)
end

Float

Forge single-precision float atom, e.g. of type Atom.Float.

forge:float(value)

value (number)

number value to forge

(userdata)

self forge object

-- Forge Float

function stash(forge)
  forge:float(12.5)
end

Double

Forge double-precision float atom, e.g. of type Atom.Double.

forge:double(value)

value (number)

number value to forge

(userdata)

self forge object

-- Forge Double

function stash(forge)
  forge:double(12.5)
end

URID

Forge URID atom, e.g. of type Atom.URID.

forge:urid(value)

value (integer)

URID value to forge

(userdata)

self forge object

-- Forge URID

local uri = 'urn:uuid:887c5b2e-89f9-4f1d-aa7c-0ac240ea11b5#foo'
local urid = Map[uri]

function stash(forge)
  forge:urid(urid)
end

URI

Forge URI atom, e.g. of type Atom.URI.

forge:uri(value)

value (string)

URI value to forge

(userdata)

self forge object

-- Forge URI

local uri = 'urn:uuid:1f2eb75a-29dc-446b-a8eb-c22d20144a85#foo'

function stash(forge)
  forge:uri(uri)
end

String

Forge string atom, e.g. of type Atom.String.

forge:string(value)

value (string)

string value to forge

(userdata)

self forge object

-- Forge String

function stash(forge)
  forge:string('hello world')
end

Path

Forge path atom, e.g. of type Atom.Path.

forge:path(value)

value (string)

string value to forge

(userdata)

self forge object

-- Forge Path

function stash(forge)
  forge:path('/tmp/xyz')
end

Literal

Forge literal atom, e.g. of type Atom.Literal.

forge:literal(value, datatype=nil, language=nil)

value (string)

string value to forge

datatype (integer)

datatype of literal as integer URID, defaults to 0

language (integer)

language of literal as integer URID, defaults to 0

(userdata)

self forge object

-- Forge Literal

local rus = Map['http://lexvo.org/id/iso639-3/rus'] -- Russian language

function stash_tuple(forge)
  forge:literal('902A7F', MIDI.MidiEvent) -- MIDI encoded as hexidecimal text
  forge:literal('Приве́т!', nil, rus) -- 'hello!'
end

Chunk

Forge chunk atom, e.g. of type Atom.Chunk.

forge:chunk(value)

value (string)

byte string value to forge

(userdata)

self forge object

forge:chunk(value)

value (table)

table with individual values to forge

(userdata)

self forge object

forge:chunk(...)

... (integer)

individual values to forge

(userdata)

self forge object

-- Forge Chunk

function stash_tuple(forge)
  forge:chunk(string.char(0x1, 0x2, 0x3))
  forge:chunk({0x1, 0x2, 0x3})
  forge:chunk(0x1, 0x2, 0x3)
end

MIDI

Forge MIDI atom, e.g. of type MIDI.MidiEvent.

forge:midi(value)

value (string)

byte string value to forge

(userdata)

self forge object

forge:midi(value)

value (table)

table with individual values to forge

(userdata)

self forge object

forge:midi(...)

... (integer)

individual values to forge

(userdata)

self forge object

-- Forge MIDI

function stash_tuple(forge)
  forge:midi(string.char(MIDI.NoteOn, 69, 0x7f))
  forge:midi({MIDI.NoteOn, 69, 0x7f})
  forge:midi(MIDI.NoteOn, 69, 0x7f)
end

Raw

Forge a custom atom of arbitrary type.

forge:raw(type, value)

type (integer)

type of atom as integer URID

value (string)

byte string value to forge

(userdata)

self forge object

forge:raw(type, value)

type (integer)

type of atom as integer URID

value (table)

table with individual values to forge

(userdata)

self forge object

forge:raw(type, ...)

type (integer)

type of atom as integer URID

... (integer)

individual values to forge

(userdata)

self forge object

-- Forge Raw

local byt = { -- stores individual bytes of zero-terminated string 'LV2'
  string.byte('L'),
  string.byte('V'),
  string.byte('2'),
  string.byte('\0')
}

function stash_tuple(forge)
  forge:raw(Atom.String, string.char(table.unpack(byt)))
  forge:raw(Atom.String, byt)
  forge:raw(Atom.String, table.unpack(byt))
end

Typed

Forge an atom of arbitrary type.

forge:typed(type, ...)

type (integer)

type of atom as integer URID

... (boolean | integer | number | string | table)

value(s) to forge, see native forge functions documentation

(userdata)

self forge object

-- Forge Typed

function stash_tuple(forge)
  forge:typed(Atom.Int, 12) -- equivalent to forge:int(...)
  forge:typed(Atom.Float, 12.5) -- equivalent to forge:float(...)
  forge:typed(Atom.String, 'LV2 rocks!') -- equivalent to forge:string(...)
end

Atom

Forge an unchanged atom. Useful for cloning whole atoms.

forge:atom(value)

value (userdata)

atom to forge

(userdata)

self forge object

-- Forge Atom

-- forge integer atom
function stash_tuple(forge)
  forge:int(12)
end

-- forge prepared integer atom in whole
function apply_tuple(tup, forge)
  assert(tup[1].body == 12)

  forge:atom(tup[1])
end

-- check if integer atom has been forged in whole
function check(tup)
  assert(tup[1].body == 12)
end

Container

Atom types that contain nested atoms as part of their body are referred to as containers.

Sequence

Forge a sequence atom, e.g. an atom of type Atom.Sequence.

forge:sequence(unit=0)

unit (integer)

event time unit as integer URID, defaults to 0, can either be Atom.frameTime or Atom.beatTime

(userdata)

derived container forge object, needs to be finalized with Pop

-- Forge Sequence

function stash_tuple(forge)
  local seq = forge:sequence() -- create derived container forge object
    seq:time(0):int(12)
    seq:frameTime(1):int(13)
  seq:pop() -- finalize container

  seq = forge:sequence(Atom.frameTime) -- create derived container forge object
    seq:time(0):int(12)
    seq:frameTime(1):int(13)
  seq:pop() -- finalize container

  for seq in forge:sequence(Atom.beatTime):autopop() do -- create iterator for derived container forge object
    seq:time(0.0):int(12)
    seq:beatTime(1.0):int(13)
  end -- finalize container
end

Frame Time

Forge frame time of event. Use this on sequences with unit 0 or Atom.frameTime.

forge:frameTime(frames)

frames (integer)

frame time of event

(userdata)

self forge object

Beat Time

Forge beat time of event. Use this on sequences with unit Atom.beatTime.

forge:beatTime(beats)

beats (number)

beat time of event

(userdata)

self forge object

Time

Forge frame or beat time of event. Can be used as syntactic sugar instead of Frame Time or Beat Time.

forge:time(timestamp)

timestamp (integer | number)

frame time (integer) or beat time (number) of event

(userdata)

self forge object

Object

Forge an object atom, e.g. an atom of type Atom.Object.

forge:object(otype=0, id=0)

otype (integer)

object type as integer URID, defaults to 0

id (integer)

object ID as integer URID, defaults to 0

(userdata)

derived container forge object, needs to be finalized with Pop

-- Forge Object

local urn = Mapper('urn:uuid:efc85bf7-0246-486f-948b-0cfbcae4e1053#')

function stash_tuple(forge)
  local obj = forge:object(urn.FooBar) -- create derived container forge object
    obj:key(urn.foo):int(12) -- without context
    obj:key(urn.bar, urn.ctx):long(13) -- with context
  obj:pop() -- finalize container

  for obj in forge:object(urn.FooBar):autopop() do -- create iterator for derived container forge object
    obj:key(urn.foo):int(12) -- without context
    obj:key(urn.bar, urn.ctx):long(13) -- with context
  end -- finalize container
end

Key

Forge key of object property.

forge:key(value, context=0)

value (integer)

key of property as integer URID

context (integer)

context of property as integer URID, defaults to 0

(userdata)

self forge object

Tuple

Forge a tuple atom, e.g. an atom of type Atom.Tuple.

forge:tuple()

(userdata)

derived container forge object, needs to be finalized with Pop

-- Forge Tuple

function stash_tuple(forge)
  local tup = forge:tuple() -- create derived container forge object
    tup:int(12)
    tup:long(13)
    tup:float(13.5)
    tup:double(14.5)
    tup:string('this is an element of an atom tuple')
    tup:bool(true)
  tup:pop() -- finalize container

  for tup in forge:tuple():autopop() do -- create iterator for derived container forge object
    tup:int(12)
    tup:long(13)
    tup:float(13.5)
    tup:double(14.5)
    tup:string('this is an element of an atom tuple')
    tup:bool(true)
  end -- finalize container
end

Vector

Forge a vector atom, e.g. an atom of type Atom.Vector.

forge:vector(type)

type (integer)

child type as integer URID, valid are: Atom.Bool, Atom.Int, Atom.Float, Atom.Long, Atom.Double, Atom.URID

(userdata)

derived container forge object, needs to be finalized with Pop

forge:vector(type, tab)

type (integer)

child type as integer URID, valid are: Atom.Bool, Atom.Int, Atom.Float, Atom.Long, Atom.Double, Atom.URID

tab (table)

table with values of matching vector child type

(userdata)

self forge object

forge:vector(type, ...)

type (integer)

child type as integer URID, valid are: Atom.Bool, Atom.Int, Atom.Float, Atom.Long, Atom.Double, Atom.URID

... (integer | number)

argument list with values of matching vector child type

(userdata)

self forge object

-- Forge Vector

local vBool = {
  true, false, true
}

function stash_tuple(forge)
  forge:vector(Atom.Int):int(1):int(2):int(3):int(4):int(5):pop()
  forge:vector(Atom.Int, {1, 2, 3, 4, 5})
  forge:vector(Atom.Int, 1, 2, 3, 4, 5)

  for vec in forge:vector(Atom.Bool):autopop() do
    for i, v in ipairs(vBool) do
      vec:bool(v)
    end
  end
  forge:vector(Atom.Bool, vBool)
  forge:vector(Atom.Bool, table.unpack(vBool))
end

Pop

Finalize any derived container forge object.

forge:pop()

(userdata)

parent container forge object

-- Pop

function stash(forge)
  local tup = forge:tuple()
  tup:int(1)
  tup:int(2)
  tup:pop()
end

function apply(atom)
  assert(#atom == 2)
end

Autopop

Finalize any derived container forge object automatically via a for-iterator-construction.

forge:autopop()

(function, userdata)

iterator function, parent container forge object

-- Autopop

function stash(forge)
  for tup in forge:tuple():autopop() do
    tup:int(1)
    tup:int(2)
  end
end

function apply(atom)
  assert(#atom == 2)
end

OSC

Atom types that contain Open Sound Control bundles or messages as part of their body.

Bundle

Forge a OSC bundle atom, e.g. an atom object of type OSC.Bundle.

forge:bundle(timestamp=1)

timestamp (integer | number)

absolute timestamp in frames (integer) or relative timestamp (number) in seconds, defaults to 1 aka immediate

(userdata)

derived container forge object, needs to be finalized with Pop

-- Forge Bundle

function stash_tuple(forge)
  -- schedule bundle for immediate dispatch
  local bndl = forge:bundle() -- create derived container forge object
    bndl:message('/hello', 's', 'world')
  bndl:pop() -- finalize container

  -- schedule bundle for dispatch @ Sep 19, 2016 02.09.16.015811000 UTC
  bndl = forge:bundle(0xdb89c74c040c3199)
    bndl:message('/hello', 's', 'world')
  bndl:pop()

  -- schedule bundle for dispatch in 0.1s
  bndl = forge:bundle(0.1)
    bndl:message('/hello', 's', 'world')
  bndl:pop()
end

Message

Forge a OSC message atom, e.g. an atom object of type OSC.Message. Supported OSC argument types are: 'i', 'f', 's', 'b', 'h', 'd', 't', 'm', 'S', 'c', 'r', 'T', 'F', 'N', 'I'

forge:message(path, format, ...)

path (string)

OSC path as string

format (string)

OSC format as string

... (integer | number | string)

variable arguments according to format

(userdata)

self forge object

-- Forge Message

function stash(forge)
  -- schedule bundle for immediate dispatch
  local bndl = forge:bundle() -- create derived container forge object
    bndl:message('/hello', 'ifs', 2016, 12.5, 'hello')
    bndl:message('/hello', 'b', string.char(0x1, 0x2, 0x3))
    bndl:message('/hello', 'hdS', 2017, 13.5, Param.sampleRate)
    bndl:message('/hello', 't', 0xdb89c74c040c3199)
    bndl:message('/hello', 'TFNI')
    bndl:message('/hello', 'm', string.char(MIDI.NoteOn, 69, 0x7f))
    bndl:message('/hello', 'cr', string.byte('s'), 0xff00ff00)
  bndl:pop() -- finalize container)
end

Impulse

Forge Impulse argument of OSC message.

forge:impulse()

(userdata)

self forge object

Char

Forge Char argument of OSC message.

forge:char(ch)

ch (integer)

character as integer

(userdata)

self forge object

RGBA

Forge RGBA color argument of OSC message.

forge:rgba(col)

col (integer)

color as 32-bit unsigned integer

(userdata)

self forge object

Timetag

Forge Timetag argument of OSC message.

forge:timetag(timestamp)

timestamp (integer | number)

absolute timestamp in frames (integer) or relative timestamp (number) in seconds, defaults to 1 aka immediate

(userdata)

self forge object

-- Forge custom OSC arguments

function stash(forge)
  for obj in forge:object(OSC.Message):autopop() do
    obj:key(OSC.messagePath):string('/custom')
    for tup in obj:key(OSC.messageArguments):tuple():autopop() do
      -- forge 'i', 'f', 's', 'b' OSC arguments
      tup:int(12) -- 'i'nteger
      tup:float(1.5) -- 'f'loat
      tup:string('foo') -- 's'tring
      tup:chunk(string.char(0x1, 0x2)) -- 'b'lob

      -- forge 'h', 'd', 't' OSC arguments
      tup:long(13) -- 'h'
      tup:double(1.6) -- 'd'ouble
      tup:timetag(0.1) -- 't', 100ms from now

      -- forge 'N', 'I', 'T', 'F' OSC arguments
      tup:raw(0) -- empty atom, 'N'il
      tup:impulse() -- 'I'mpulse
      tup:bool(true) -- 'T'rue
      tup:bool(false) -- 'F'alse

      -- forge 'c', 'r', 'm', 'S' OSC arguments
      tup:char(string.byte('c')) -- 'c'char
      tup:rgba(0xbb0000ff) -- reddish, 'r'gba
      tup:midi(MIDI.NoteOn, Note['C-0'], 64) -- 'm'idi
      tup:urid(Param.sampleRate) -- 'S'ymbol
    end
  end
end

Patch

Atom types that contain Patch messages as part of their body.

Patch

Forge a patch patch atom, e.g. an atom object of type Patch.Patch.

forge:patch(subject=0, sequenceNumber=0)

subject (integer)

patch subject as integer URID, defaults to 0

sequenceNumber (integer)

patch sequence number as integer, defaults to 0

(userdata)

derived container forge object, needs to be finalized with Pop

-- Forge Patch

local urn = Mapper('urn:uuid:29f87e4f-fa45-4f91-aa88-767053006a0d#')

function stash(forge)
  local patch= forge:patch(urn.subj, 1002) -- with subject and sequence number

    local rem = patch:remove() -- equivalent to patch:object(Patch.remove)
      rem:key(urn.foo):urid(Patch.wildcard)
      rem:key(urn.bar):urid(Patch.wildcard)
    rem:pop()

    local add = patch:add() -- equivalent to patch:object(Patch.add)
      add:key(urn.foo):int(12)
      add:key(urn.bar):float(12.5)
    add:pop()

  patch:pop()
end

Add

Forge add property of patch property.

forge:add()

(userdata)

derived container forge object, needs to be finalized with Pop

Remove

Forge remove property of patch property.

forge:remove()

(userdata)

derived container forge object, needs to be finalized with Pop

Get

Forge a patch get atom, e.g. an atom object of type Patch.Get.

forge:get(property, subject=0, sequenceNumber=0)

property (integer)

patch property as integer URID

subject (integer)

patch subject as integer URID, defaults to 0

sequenceNumber (integer)

patch sequence number as integer, defaults to 0

(userdata)

self container object

-- Forge Get

local urn = Mapper('urn:uuid:5b172c1f-9152-4d4e-ad68-84965792b931#')

function stash_tuple(forge)
  forge:get(urn.prop) -- without subject and sequence number
  forge:get(urn.prop, nil, 1001) -- without subject
  forge:get(urn.prop, urn.subj, 1002) -- with subject and sequence number
end

Set

Forge a patch set atom, e.g. an atom object of type Patch.Set.

forge:set(property, subject=0, sequenceNumber=0)

property (integer)

patch property as integer URID

subject (integer)

patch subject as integer URID, defaults to 0

sequenceNumber (integer)

patch sequence number as integer, defaults to 0

(userdata)

derived container forge object, needs to be finalized with Pop

-- Forge Set

local urn = Mapper('urn:uuid:29c714c1-0c7b-4434-81d6-82ee8a4d64b8#')

function stash_tuple(forge)
  local set = forge:set(urn.prop) -- without subject and sequence number
    set:int(12)
  set:pop()

  set = forge:set(urn.prop, urn.subj, 1002) -- with subject and sequence number
    set:float(12)
  set:pop()
end

Put

Forge a patch put atom, e.g. an atom object of type Patch.Put.

forge:put(subject=0, sequenceNumber=0)

subject (integer)

patch subject as integer URID, defaults to 0

sequenceNumber (integer)

patch sequence number as integer, defaults to 0

(userdata)

derived container forge object, needs to be finalized with Pop

-- Forge Put

local urn = Mapper('urn:uuid:dabe2235-2405-46e6-a26c-90dbe34d9bf3#')

function stash_tuple(forge)
  local put = forge:put() -- without subject and sequence number
    put:key(urn.foo):int(12)
    put:key(urn.bar):float(12.5)
  put:pop()

  put= forge:put(urn.subj, 1002) -- with subject and sequence number
    put:key(urn.foo):int(12)
    put:key(urn.bar):float(12.5)
  put:pop()
end

Ack

Forge an ack patch atom, e.g. an atom object of type Patch.Ack.

forge:ack(subject=0, sequenceNumber=0)

subject (integer)

patch subject as integer URID, defaults to 0

sequenceNumber (integer)

patch sequence number as integer, defaults to 0

(userdata)

self forge object

-- Forge Ack

local urn = Mapper('urn:uuid:f35c0f85-5b7f-4434-912d-8bf982711b30#')

function stash(forge)
  forge:ack(urn.subj, 1002) -- with subject and sequence number
end

Error

Forge an error patch atom, e.g. an atom object of type Patch.Error.

forge:error(subject=0, sequenceNumber=0)

subject (integer)

patch subject as integer URID, defaults to 0

sequenceNumber (integer)

patch sequence number as integer, defaults to 0

(userdata)

self forge object

-- Forge Error

local urn = Mapper('urn:uuid:93ea103c-75ff-47e2-b89b-fc79173bedee#')

function stash(forge)
  forge:error(urn.subj, 1002) -- with subject and sequence number
end

Delete

Forge a delete patch atom, e.g. an atom object of type Patch.Delete.

forge:delete(subject, sequenceNumber=0)

subject (integer)

patch subject as integer URID

sequenceNumber (integer)

patch sequence number as integer, defaults to 0

(userdata)

self forge object

-- Forge Delete

local urn = Mapper('urn:uuid:cea077fc-b822-4143-b5c5-34c0f7d9f016#')

function stash(forge)
  forge:delete(urn.subj, 1002) -- with sequence number
end

Copy

Forge a copy patch atom, e.g. an atom object of type Patch.Copy.

forge:copy(subject, destination, sequenceNumber=0)

subject (integer)

patch subject as integer URID

destination (integer)

patch destination as integer URID

sequenceNumber (integer)

patch sequence number as integer, defaults to 0

(userdata)

self forge object

-- Forge Copy

local urn = Mapper('urn:uuid:3d4de1a6-a5fa-463d-a59c-c7778a6b18e9#')

function stash(forge)
  forge:copy(urn.subj, urn.dest, 1002) -- with sequence number
end

Move

Forge a move patch atom, e.g. an atom object of type Patch.Move.

forge:move(subject, destination, sequenceNumber=0)

subject (integer)

patch subject as integer URID

destination (integer)

patch destination as integer URID

sequenceNumber (integer)

patch sequence number as integer, defaults to 0

(userdata)

self forge object

-- Forge Move

local urn = Mapper('urn:uuid:6370dea9-a41a-4347-80f0-75d9fcccc28a#')

function stash(forge)
  forge:move(urn.subj, urn.dest, 1002) -- with sequence number
end

Insert

Forge a patch insert atom, e.g. an atom object of type Patch.Insert.

forge:insert(subject=0, sequenceNumber=0)

subject (integer)

patch subject as integer URID, defaults to 0

sequenceNumber (integer)

patch sequence number as integer, defaults to 0

(userdata)

derived container forge object, needs to be finalized with Pop

-- Forge Insert

local urn = Mapper('urn:uuid:16e7ed0d-20ee-45ef-8268-ed931a998a4f#')

function stash_tuple(forge)
  local insert = forge:insert() -- without subject and sequence number
    insert:key(urn.foo):int(12)
    insert:key(urn.bar):float(12.5)
  insert:pop()

  insert= forge:insert(urn.subj, 1002) -- with subject and sequence number
    insert:key(urn.foo):int(12)
    insert:key(urn.bar):float(12.5)
  insert:pop()
end

Canvas

Atom types that contain Canvas messages as part of their body. Modeled after the HTML5 Canvas API. But the vector drawing instructions into an atom:Tuple and store it as property Canvas:graph.

BeginPath

Forge an atom object of type Canvas.BeginPath. Manually begin a new path. Not needed for instructions that inherently begin a new path by themeselves: Canvas.MoveTo, Canvas.Arc, Canvas.Rectangle.

forge:beginPath()

(userdata)

self forge object

-- Forge BeginPath

function stash(ctx)
  ctx:beginPath()
end

ClosePath

Forge an atom object of type Canvas.ClosePath. Close a previously begun path.

forge:closePath()

(userdata)

self forge object

-- Forge ClosePath

function stash(ctx)
  ctx:closePath()
end

Arc

Forge an atom object of type Canvas.Arc. Create an Arc structure.

forge:arc(x, y, r, a=0, b=2*Pi)

x (number)

x coordinate of center

y (number)

y coordinate of center

r (number)

radius

a (number)

starting angle in radians, defaults to 0

b (number)

ending angle in radians, defaults to 2*Pi

(userdata)

self forge object

-- Forge Arc

function stash(ctx)
  ctx:arc(0.5, 0.5, 0.1):stroke()
  ctx:arc(0.5, 0.5, 0.1, math.pi/4, math.pi/2):stroke()
end

CurveTo

Forge an atom object of type Canvas.CurveTo. Append a spline curve segment to path.

forge:curveTo(x1, y1, x2, y2, x3, y3)

x1 (number)

x coordinate of spline point 1

y1 (number)

y1 coordinate of spline point 1

x2 (number)

x coordinate of spline point 2

y2 (number)

y2 coordinate of spline point 2

x3 (number)

x coordinate of spline point 3

y3 (number)

y3 coordinate of spline point 3

(userdata)

self forge object

-- Forge CurveTo

function stash(ctx)
  ctx:beginPath():moveTo(0.0, 0.0):curveTo(0.1, 0.1, 0.2, 0.4, 0.3, 0.9):closePath():stroke()
end

LineTo

Forge an atom object of type Canvas.LineTo. Append line segment to path.

forge:lineTo(x, y)

x (number)

x coordinate of line point

y (number)

y coordinate of line point

(userdata)

self forge object

-- Forge LineTo 

function stash(ctx)
  ctx:beginPath():moveTo(0.0, 0.0):lineTo(1.0, 1.0):closePath():stroke()
end

MoveTo

Forge an atom object of type Canvas.MoveTo. Move to given point and begin new path.

forge:moveTo(x, y)

x (number)

x coordinate of point

y (number)

y coordinate of point

(userdata)

self forge object

-- Forge MoveTo

function stash(ctx)
  ctx:moveTo(0.0, 0.0)
end

Rectangle

Forge an atom object of type Canvas.Rectangle. Create rectangle.

forge:rectangle(x, y, w, h)

x (number)

x coordinate of top left point

y (number)

y coordinate of top left point

w (number)

width of rectangle

h (number)

height of rectangle

(userdata)

self forge object

-- Forge Rectangle

function stash(ctx)
  ctx:rectangle(0.1, 0.1, 0.8, 0.8):fill()
end

PolyLine

Forge an atom object of type Canvas.PolyLine. Create polyline.

forge:polyLine(x1, y1, ...)

x1 (number)

x coordinate of first point

y1 (number)

y coordinate of first poine

(userdata)

self forge object

-- Forge PolyLine

function stash(ctx)
  ctx:beginPath():polyLine(0.1, 0.1, 0.9, 0.1, 0.5, 0.9):closePath():fill()
end

Style

Forge an atom object of type Canvas.Style. Set current stroke and fill color.

forge:style(color)

color (integer)

color in ARGB format

(userdata)

self forge object

-- Forge Style

function stash(ctx)
  ctx:rectangle(0.1, 0.1, 0.2, 0.2):style(0xffffffff):fill() -- opaque white
  ctx:rectangle(0.2, 0.2, 0.2, 0.2):style(0xff0000ff):fill() -- opaque red
  ctx:rectangle(0.3, 0.3, 0.2, 0.2):style(0x00ff0080):fill() -- half-transparent green
end

LineWidth

Forge an atom object of type Canvas.LineWidth. Set current line width.

forge:lineWidth(width)

width (number)

line width

(userdata)

self forge object

-- Forge LineWidth

function stash(ctx)
  ctx:rectangle(0.1, 0.1, 0.2, 0.2):lineWidth(0.01):stroke()
  ctx:rectangle(0.2, 0.2, 0.2, 0.2):lineWidth(0.04):stroke()
end

LineDash

Forge an atom object of type Canvas.LineDash. Set current line dash style.

forge:lineDash(dashLen, spaceLen)

dashLen (number)

length of dash lines

spaceLen (number)

length of space between dash lines

(userdata)

self forge object

-- Forge LineDash

function stash(ctx)
  ctx:rectangle(0.1, 0.1, 0.2, 0.2):lineDash(0.01, 0.01):stroke()
  ctx:rectangle(0.2, 0.2, 0.2, 0.2):lineDash(0.01, 0.04):stroke()
end

LineCap

Forge an atom object of type Canvas.LineCap. Set current line cap style.

forge:lineCap(cap)

cap (integer)

line cap type URID: Canvas.lineCapButt, Canvas.lineCapRound, Canvas.lineCapSquare

(userdata)

self forge object

-- Forge LineCap

local function tri(ctx, x, y, s, cap)
  ctx:moveTo(x, y):lineTo(x + s, y):lineTo(x + s, y + s/2):lineCap(cap):stroke()
end

function stash(ctx)
  ctx:lineWidth(0.05)
  tri(ctx, 0.3, 0.1, 0.4, Canvas.lineCapButt)
  tri(ctx, 0.2, 0.2, 0.4, Canvas.lineCapRound)
  tri(ctx, 0.1, 0.3, 0.4, Canvas.lineCapSquare)
end

LineJoin

Forge an atom object of type Canvas.LineJoin. Set current line join style.

forge:lineJoin(join)

join (integer)

line join type URID: Canvas.lineJoinMiter, Canvas.lineJoinRound, Canvas.lineJoinBevel

(userdata)

self forge object

-- Forge LineJoin

local function tri(ctx, x, y, s, join)
  ctx:moveTo(x, y):lineTo(x + s, y):lineTo(x + s, y + s/2):lineJoin(join):stroke()
end

function stash(ctx)
  ctx:lineWidth(0.05)
  tri(ctx, 0.3, 0.1, 0.4, Canvas.lineJoinMiter)
  tri(ctx, 0.2, 0.2, 0.4, Canvas.lineJoinRound)
  tri(ctx, 0.1, 0.3, 0.4, Canvas.lineJoinBevel)
end

MiterLimit

Forge an atom object of type Canvas.MiterLimit. Set current line join miter limit.

forge:miterLimit(limit)

limit (number)

miter limit

(userdata)

self forge object

-- Forge MiterLimit

local function tri(ctx, x, y, s, limit)
  ctx:moveTo(x, y):lineTo(x + s, y):lineTo(x + s, y + s/2):lineJoin(Canvas.lineJoinMiter):miterLimit(limit):stroke()
end

function stash(ctx)
  ctx:lineWidth(0.05)
  tri(ctx, 0.3, 0.1, 0.4, 1.0)
  tri(ctx, 0.2, 0.2, 0.4, 2.0)
end

Stroke

Forge an atom object of type Canvas.Stroke. Stroke current path.

forge:stroke()

(userdata)

self forge object

-- Forge Stroke

function stash(ctx)
  ctx:rectangle(0.0, 0.0, 1.0, 1.0):stroke()
end

Fill

Forge an atom object of type Canvas.Fill. Fill current path.

forge:fill()

(userdata)

self forge object

-- Forge Fill

function stash(ctx)
  ctx:rectangle(0.0, 0.0, 1.0, 1.0):fill()
end

Clip

Forge an atom object of type Canvas.Clip. Set current path as clip mask.

forge:clip()

(userdata)

self forge object

-- Forge Clip

function stash(ctx)
  ctx:save()
  ctx:arc(0.25, 0.25, 0.25):clip()
  ctx:rectangle(0.25, 0.25, 0.5, 0.5):fill()
  ctx:restore()
end

Save

Forge an atom object of type Canvas.Save. Push/save current state.

forge:save()

(userdata)

self forge object

-- Forge Save

function stash(ctx)
  ctx:save():translate(0.5, 0.5):rotate(math.pi/4)
  ctx:rectangle(-0.1, -0.1, 0.2, 0.2):stroke()
  ctx:restore()

  ctx:rectangle(0.4, 0.4, 0.2, 0.2):stroke()
end

Restore

Forge an atom object of type Canvas.Restore. Pop/restore previously saved state.

forge:restore()

(userdata)

self forge object

-- Forge Restore

function stash(ctx)
  ctx:save():translate(0.5, 0.5):rotate(math.pi/4)
  ctx:rectangle(-0.1, -0.1, 0.2, 0.2):stroke()
  ctx:restore()

  ctx:rectangle(0.4, 0.4, 0.2, 0.2):stroke()
end

Translate

Forge an atom object of type Canvas.Translate. Translate current render matrix.

forge:translate(tx, ty)

tx (number)

x coordinate offset of translocation

ty (number)

y coordinate offset of translocation

(userdata)

self forge object

-- Forge Translate

function stash(ctx)
  ctx:save():translate(0.4, 0.4)
  ctx:rectangle(0.0, 0.0, 0.2, 0.2):fill()
  ctx:restore()
end

Scale

Forge an atom object of type Canvas.Scale. Scale current render matrix.

forge:scale(sx, sy)

sx (number)

x coordinate scaling factor

sy (number)

y coordinate scaling factor

(userdata)

self forge object

-- Forge Scale

function stash(ctx)
  ctx:save():scale(2.0, 2.0)
  ctx:rectangle(0.0, 0.0, 0.5, 0.5):fill()
  ctx:restore()
end

Rotate

Forge an atom object of type Canvas.Rotate. Rotate current render matrix.

forge:rotate(a)

a (number)

angle of rotation in radians

(userdata)

self forge object

-- Forge Rotate

function stash(ctx)
  ctx:save():translate(0.4, 0.4):rotate(math.pi/4) -- rotate by 45 degrees
  ctx:rectangle(-0.1, -0.1, 0.2, 0.2):fill()
  ctx:restore()
end

Transform

Forge an atom object of type Canvas.Transform. Set current render matrix.

forge:transform(a)

xx (number)

multiplier for x in: x' = xx*x + xy*y + x0

xy (number)

multiplier for y in: x' = xx*x + xy*y + x0

x0 (number)

constant in: x' = xx*x + xy*y + x0

yx (number)

multiplier for y in: y' = yy*y + yx*x + y0

yx (number)

multiplier for x in: y' = yy*y + yx*x + y0

y0 (number)

constant in: y' = yy*y + yx*x + y0

(userdata)

self forge object

-- Forge Transform

function stash(ctx)
  ctx:save():transform(-1.0, 0.0, 1.0, 1.0, 0.0, 0.0) -- mirror on x-asix
  ctx:rectangle(-0.1, -0.1, 0.2, 0.2):fill()
  ctx:restore()
end

Reset

Forge an atom object of type Canvas.Reset. Reset current render matrix to identity configuration.

forge:reset()

(userdata)

self forge object

-- Forge Reset

function stash(ctx)
  ctx:translate(0.4, 0.4)
  ctx:rectangle(0.0, 0.0, 0.2, 0.2):fill()

  ctx:reset()

  ctx:rectangle(0.0, 0.0, 0.2, 0.2):fill()
end

FontSize

Forge an atom object of type Canvas.FontSize. Set font size.

forge:fontSize(size)

size (number)

size of font

(userdata)

self forge object

-- Forge FontSize

function stash(ctx)
  ctx:moveTo(0.5, 0.5):fontSize(0.1):fillText('Hello')
end

FillText

Forge an atom object of type Canvas.FillText. Fill/draw text at current position.

forge:fillText(text)

text (string)

text to fill/draw

(userdata)

self forge object

-- Forge FillText

function stash(ctx)
  ctx:moveTo(0.5, 0.5):fontSize(0.1):style(0xff0000ff):fillText('Hello')
end

Atom

Instead of deserializing all LV2 event data to corresponding Lua types, Moony instead presents a proxy object to the user in form of a Lua userdata. This is needed because there are more LV2 atom types than native Lua types. It turns out to be more efficient, too, as the user usually wants to filter events before looking at their payload.

All atom types have some common attributes they can be queried for:

atom.__len | #atom

(integer)

size of atom body

atom.type

(integer)

URID of atom type

atom.raw

(string)

raw byte string of atom body

atom.__tostring | tostring(atom)

(string)

string representation of atom

Primitive

Atom types that contain single data as part of their body are referred to as primitives.

Nil

An empty atom, e.g. of type and size 0.

nil.__len | #nil

(integer)

size of atom body

nil.type

(integer)

URID of atom type

nil.body

(nil)

atom body as Lua nil

nil.__tostring | tostring(nil)

(string)

string representation of atom

-- Atom Nil

-- serialize
function stash(forge)
end

function apply(atom)
  -- attributes
  assert(#atom == 0) -- query size of atom body
  print(tostring(atom)) -- convert to string
  assert(atom.type == 0) -- query type of atom
  assert(atom.body == nil) -- get atom body
end

Bool

A boolean atom, e.g. of type Atom.Bool and size 4.

bool.__len | #bool

(integer)

size of atom body

bool.type

(integer)

URID of atom type

bool.body

(boolean)

atom body as Lua boolean

bool.__tostring | tostring(bool)

(string)

string representation of atom

-- Atom Bool

-- serialize
function stash(forge)
  forge:bool(true)
end

function apply(atom)
  -- attributes
  assert(#atom == 4) -- query size of atom body
  print(tostring(atom)) -- convert to string
  assert(atom.type == Atom.Bool) -- query type of atom
  assert(atom.body == true) -- get atom body
end

Int

An integer atom, e.g. of type Atom.Int and size 4.

int.__len | #int

(integer)

size of atom body

int.type

(integer)

URID of atom type

int.body

(integer)

atom body as Lua integer

int.__tostring | tostring(int)

(string)

string representation of atom

-- Atom Int

-- serialize
function stash(forge)
  forge:int(12)
end

function apply(atom)
  -- attributes
  assert(#atom == 4) -- query size of atom body
  print(tostring(atom)) -- convert to string
  assert(atom.type == Atom.Int) -- query type of atom
  assert(atom.body == 12) -- get atom body
end

Long

A long integer atom, e.g. of type Atom.Long and size 8.

long.__len | #long

(integer)

size of atom body

long.type

(integer)

URID of atom type

long.body

(integer)

atom body as Lua integer

long.__tostring | tostring(long)

(string)

string representation of atom

-- Atom Long

-- serialize
function stash(forge)
  forge:long(13)
end

function apply(atom)
  -- attributes
  assert(#atom == 8) -- query size of atom body
  print(tostring(atom)) -- convert to string
  assert(atom.type == Atom.Long) -- query type of atom
  assert(atom.body == 13) -- get atom body
end

Float

A single-precision float atom, e.g. of type Atom.Float and size 4.

float.__len | #float

(integer)

size of atom body

float.type

(integer)

URID of atom type

float.body

(number)

atom body as Lua number

float.__tostring | tostring(float)

(string)

string representation of atom

-- Atom Float

-- serialize
function stash(forge)
  forge:float(1.5)
end

function apply(atom)
  -- attributes
  assert(#atom == 4) -- query size of atom body
  print(tostring(atom)) -- convert to string
  assert(atom.type == Atom.Float) -- query type of atom
  assert(atom.body == 1.5) -- get atom body
end

Double

A double-precision float atom, e.g. of type Atom.Double and size 8.

double.__len | #double

(integer)

size of atom body

double.type

(integer)

URID of atom type

double.body

(number)

atom body as Lua number

double.__tostring | tostring(double)

(string)

string representation of atom

-- Atom Double

-- serialize
function stash(forge)
  forge:double(1.6)
end

function apply(atom)
  -- attributes
  assert(#atom == 8) -- query size of atom body
  print(tostring(atom)) -- convert to string
  assert(atom.type == Atom.Double) -- query type of atom
  assert(atom.body == 1.6) -- get atom body
end

URID

An URID atom, e.g. of type Atom.URID and size 4.

urid.__len | #urid

(integer)

size of atom body

urid.type

(integer)

URID of atom type

urid.body

(integer)

atom body as Lua integer

urid.__tostring | tostring(urid)

(string)

string representation of atom

-- Atom URID

local urid = Map['urn:uuid:6d82e244-ee66-403f-aea1-26b3d9823820#foo']

-- serialize
function stash(forge)
  forge:urid(urid)
end

function apply(atom)
  -- attributes
  assert(#atom == 4) -- query size of atom body
  print(tostring(atom)) -- convert to string
  assert(atom.type == Atom.URID) -- query type of atom
  assert(atom.body == urid) -- get atom body
end

URI

An URI atom, e.g. of type Atom.URI and variable size. Atom size denotes to string size plus zero byte terminator.

uri.__len | #uri

(integer)

size of atom body

uri.type

(integer)

URID of atom type

uri.body

(string)

atom body as Lua string

uri.__tostring | tostring(uri)

(string)

string representation of atom

-- Atom URI

local uri = 'urn:uuid:022ec18a-0a02-4a19-ad7a-a10403a0c4c3#foo'

-- serialize
function stash(forge)
  forge:uri(uri)
end

function apply(atom)
  -- attributes
  assert(#atom == #uri + 1) -- query size of atom body
  print(tostring(atom)) -- convert to string
  assert(atom.type == Atom.URI) -- query type of atom
  assert(atom.body == uri) -- get atom body
end

String

A string atom, e.g. of type Atom.String and variable size. Atom size denotes to string size plus zero byte terminator.

string.__len | #string

(integer)

size of atom body

string.type

(integer)

URID of atom type

string.body

(string)

atom body as Lua string

string.__tostring | tostring(string)

(string)

string representation of atom

-- Atom String

local str = 'hello world'

-- serialize
function stash(forge)
  forge:string(str)
end

function apply(atom)
  -- attributes
  assert(#atom == #str + 1) -- query size of atom body
  print(tostring(atom)) -- convert to string
  assert(atom.type == Atom.String) -- query type of atom
  assert(atom.body == str) -- get atom body
end