home - plugins - tutorials - showcase - history - manual - design

dublang user manual

this reference manual describes the dublang features, ideas and concepts

• shebang
• services
• handlers
• filters
• triggers
• hooks
• plugins

shebang

shebang are lines starting by the two characters #! followed by the dublang plugin name

shebang defines regions in dublang language and can be added at any place, multiple times

for instance, the line #!supercollider defines a region to write SuperCollider code

#!supercollider

{ SinOsc.ar([220, 140]) }.play

#!tidalcycles

d1 $ sound "808bd(3,8)"
   # shape 0.2

services

services handles live coding servers and tools, it is built on top of systemd, the dublang command-line interface (cli) can be used to install (enable), remove (disable), start and stop services

handlers

handlers are executable files, usually lua scripts, that wraps an external tool, run it, and open a TCP server waiting for connection from dublang-nvim

handlers execution are managed by systemd

custom services and handlers

custom services and handlers can be added to the PROJECT-level folders services/ and handlers/

the dublang command-line interface (cli) is able to enable and start custom handlers by-project level

filters

filters are Lua functions executed each time a code block is evaluated by "CTRL + e"

for example if the SuperCollider code below is evaluated

~dirt.loadSoundFiles("${HOME}/samples/*")

then the envsubst filter will replace "${HOME}" for "/home/joenio" (in my case), before the code is sent to SuperCollider

filters are executed before the block itself and multiple functions can be combined in a pipeline of filters, each plugin defines a different pipeline but the envsubst is enabled by default in all plugins

filter: envsubst

the filter envsubst expands environment variables in the format ${NAME} before execution, it works like the unix command-line tool envsubst

example

#!dublang

return ${HOME}

this example will return “/home/joenio” for my user

the envsubst filter is enabled by default for all plugins

example using it to load samples with SuperDirt for Tidal Cycles

#!supercollider

~dirt.loadSoundFiles("${HOME}/samples/*")

filter: confsubst

the filter confsubst expands strings ${config.NAME1.NAME2} by Lua variables defined in the namespace config.NAME1.NAME2 before execution, it works like the filter envsubst but using values defined by Lua instead of using environment variables

example

#!dublang

return ${config.path.sounds}

this example will return the value for Lua global variable config.path.sounds

the confsubst filter is enabled by default for all plugins

example using it to set pth for MPV videos and images

#!dublang

config.path.mpv = "/home/joenio/videos"

#!mpv

video "dune:01.mp4"

triggers

triggers are methods to modify code block evaluation defined on shebang level, added below the shebang line in the format "|trigger [args]"

trigger: |repeat [n]

the trigger repeat schedule the last block execution to be re-executed in a infinite loop every [n] seconds

example

#!dublang
|repeat 5

return 'hello world'

after the code above be executed it be re-executed every 5 seconds

hooks

hooks are points of communication among plugins where events generated by one plugin can be captured by others plugins

one plugin can implement the function hook() to attract others plugins, any plugin implementing the function bite() will bite on the hook executing the function hook() for every connected plugin when code is evaluated by "CTRL + e", for example

• if plugins foo and bar are enabled
• and functions foo.hook() and bar.bite() are defined
• when plugin bar is executed by pressing "CTRL + e"
• then function bar.bite() runs the function foo.hook()

see below a diagram with the general overview of hooks and bites functions

plugins can customize the bite() function, but the default code looks like the code below (in Lua)

for i, p in pairs(plugins) do
  if p.hook and p.connected then
    local ok, err = pcall(p.hook, p, ...)
  end
end

plugins using hooks

• the gource plugin uses hooks to update the gource graph each time a block is executed by others plugins
• the git plugin saves and commits the dublang file .dub each time a block is evaluated by others plugins

plugins

reference manual for plugins

• dublang reference manual
• mpv reference manual
• nvimqt reference manual
• sonicpi reference manual
• supercollider reference manual

home - plugins - tutorials - showcase - history - manual - design