cue_dsl 1.0.0

data/README.md

@@ -0,0 +1,153 @@
+# cue_dsl
+
+[![pipeline status](https://gitlab.com/nicb/cue_dsl/badges/%{default_branch}/pipeline.svg)](https://gitlab.com/nicb/cue_dsl/-/commits/%{default_branch})
+[![coverage](https://gitlab.com/nicb/cue_dsl/badges/%{default_branch}/coverage.svg)](https://gitlab.com/nicb/cue_dsl/-/commits/%{default_branch})
+
+A small Ruby DSL for generating Pure Data `[text sequence]` cue lists for
+live-electronics performances, plus a cheatsheet of every device parameter.
+
+The cue sheet is written to **STDOUT**; the cheatsheet to a file.
+
+## Install
+
+```sh
+gem build cue_dsl.gemspec
+gem install cue_dsl-*.gem
+```
+
+Requires Ruby >= 3.0. Runtime deps: none (stdlib `yaml` only).
+
+## Files needed next to your DSL
+
+- `receivers.txt` — one Pd receiver name per line, e.g. `FILTER_cutoff_recv`.
+  Lines starting with a lowercase letter that don't match `reset_<name>_recv`
+  or one of the known `system_*` receivers are ignored. Lines containing
+  `$1` / `$2` templates are skipped.
+- `devices.yml` — static routing for each device:
+
+```yaml
+matrix:
+  rows: 9
+  cols: 8
+
+devices:
+  DRY:
+    label: "Dry"
+    inputs: [0]
+    outputs: [0]
+  FILTER:
+    label: "Filter"
+    inputs: [1]
+    outputs: [1]
+    filters: 12            # enables filter.fc(0..11).cutoff / .Q
+  CE:
+    label: "Echo Chamber"
+    inputs: [2]
+    outputs: [2, 3]        # two outputs
+  OUT:
+    label: "Output"
+    inputs: [6, 7]         # two inputs
+    outputs: []
+```
+
+## Writing cues
+
+```ruby
+# cues.rb
+cue "Intro" do
+  comment "Opening — filter sweep in", kind: :gui
+  connect DRY >> FILTER >> CE >> OUT
+  filter.cutoff 800
+  filter.mod_onoff :off
+  filter.fc(0).cutoff 400
+  rm.mod_freq 2.5
+  mtx.at(0, 1) 1
+  system.cue_step "go"
+end
+
+cue "Climax" do
+  connect DRY >> FILTER >> CE >> OUT
+  filter.cutoff 3000
+  reset :CE
+  system.cue_step "pause"
+end
+```
+
+### DSL verbs
+
+- `cue "name" do … end` — one cue. Name is required and non-empty.
+- `connect A >> B >> C …` — installs matrix cells from the static routing.
+  Supports 1→1, 1→2 (fan-out), 2→1 (output 1 only), 2→2 (pairwise).
+  Any other geometry raises `ConnectionError`.
+- `device.param value` — emits `<receiver> <value>` in the cue sheet.
+- `device.fc(i).param value` — filter-bank parameter (`i` in `0..11`).
+- `mtx.at(r, c) value` — explicit matrix cell write, in source order.
+- `reset :CE` / `:PS` / `:RM` / `:SA` / `:matrix` — emits `reset_<name>_recv bang`.
+- `system.cue_step "go"` — emits `cue_step_recv go`.
+  `system.header_message` is **forbidden** — see below.
+- `comment "text"` (or `kind: :gui` for `##`) — passthrough comment.
+
+### Matrix semantics
+
+Rows are inputs, columns are outputs. A receiver MTX_<row>_<col>_recv addresses input <row> and output <col>.
+In devices.yml, inputs: lists rows and outputs: lists columns. A link A >> B enables MTX[B_input_row][A_output_col].
+
+### Header & pause
+
+Every rendered cue starts with:
+
+```
+reset_matrix_recv bang                 # if CueDSL.reset_matrix is on
+header_message_recv N\ -\ <cue name>   # N is 0-based
+```
+
+Spaces, commas and semicolons in the header are escaped (`\ `, `\,`, `\;`).
+
+Every rendered cue ends with a literal `pause` line.
+
+`system.header_message` raises an error; the cue name is the source of truth.
+
+## Running
+
+```ruby
+require "cue_dsl"
+
+CueDSL.configure do |c|
+  c.reset_matrix    = true                       # default true
+  c.cheatsheet_path = "cheatsheet.txt"           # default nil (no file)
+  c.cue_numbers_path = "cue_list_numbers.txt"    # default nil (no file)
+end
+
+CueDSL.run("cues.rb")                            # writes cue sheet to $stdout
+```
+
+`CueDSL.cue_numbers_path = "cue_list_numbers.txt"` (default `nil`) writes an index of `<line> <escaped cue name>`,
+one entry per cue, where `<line>` is the 0-based line in the cue sheet where
+the cue starts (the `reset_system_recv` bang line). Only cues rendered with `reset_system: true` appear;
+the file is intended for building a goto mechanism against `[text sequence]`.
+
+## Tests
+
+```sh
+rake test
+```
+
+## Layout
+
+```
+lib/cue_dsl.rb                    # Context, DSL verbs, run()
+lib/cue_dsl/device.rb
+lib/cue_dsl/filter_bank.rb
+lib/cue_dsl/matrix.rb
+lib/cue_dsl/connect.rb
+lib/cue_dsl/cue.rb
+lib/cue_dsl/parameter.rb
+lib/cue_dsl/receivers_loader.rb
+lib/cue_dsl/devices_config.rb
+lib/cue_dsl/cheatsheet.rb
+test/**                           # minitest
+```
+
+## License
+
+![GNU GPL3](./doc/gplv3.png){width=66} [GNU GPL 3 License](./LICENSE)

data/bin/run.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run the cue DSL for a performance directory.
+#
+# Usage:
+#   ruby -I path/to/cue_dsl/lib path/to/cue_dsl/bin/run.rb [cue_list.rb] > cue_list.txt
+#
+# Run from the performance directory (the one containing cue_list.rb,
+# receivers.txt and devices.yml). All relative paths below are resolved
+# against the current working directory, not against this script.
+#
+# With no argument, defaults to "cue_list.rb".
+
+require "cue_dsl"
+
+dsl_path = ARGV[0] || "cue_list.rb"
+
+unless File.exist?(dsl_path)
+  warn "run.rb: DSL file not found: #{dsl_path}"
+  warn "run.rb: usage: ruby -I <lib> bin/run.rb [cue_list.rb] > cue_list.txt"
+  exit 1
+end
+
+CueDSL.configure do |c|
+  c.reset_system     = false                     # default false
+  c.cheatsheet_path  = "cheatsheet.txt"          # default nil (no file)
+  c.cue_numbers_path = "cue_list_numbers.txt"    # default nil (no file)
+end
+
+CueDSL.run(dsl_path)                             # writes cue sheet to $stdout

data/lib/cue_dsl/chain.rb

@@ -0,0 +1,16 @@
+# lib/cue_dsl/chain.rb
+module CueDSL
+  # Built up by Device#> and Chain#>. Passed to Context#connect.
+  class Chain
+    attr_reader :devices
+
+    def initialize(devices)
+      @devices = devices.freeze
+    end
+
+    def >>(other)
+      raise ConnectionError, "cannot append #{other.inspect} to chain" unless other.is_a?(Device)
+      Chain.new(@devices + [other])
+    end
+  end
+end

data/lib/cue_dsl/cheatsheet.rb

@@ -0,0 +1,59 @@
+# lib/cue_dsl/cheatsheet.rb
+module CueDSL
+  class Cheatsheet
+    AUTO_EMITTED = {
+      header_message: "auto-emitted from cue name; do not call",
+      preview_cue:    "auto-emitted from next cue name; do not call"
+    }.freeze
+
+    def self.render(devices:, matrix:, system_params:, reset_verbs:)
+      out = []
+      devices.each do |dev|
+        out << "=== #{dev.name} (#{dev.label}) ==="
+        dev.parameters.sort_by { |k, _| k.to_s }.each do |short, param|
+          next unless param.kind == :normal
+          out << format("  %-24s %-36s %s", short, param.pd_name, "#{dev.name.downcase}.#{short}(value)")
+        end
+        if dev.filter_count.positive?
+          dev.filter_count.times do |i|
+            params = dev.filter_fc_params_for(i)
+            params.sort_by { |k, _| k.to_s }.each do |name, param|
+              out << format("  %-24s %-36s %s",
+                            "fc(#{i}).#{name}", param.pd_name,
+                            "#{dev.name.downcase}.fc(#{i}).#{name}(value)")
+            end
+          end
+        end
+        out << ""
+      end
+
+      out << "=== MTX (Matrix #{matrix.rows}x#{matrix.cols} — rows=inputs, cols=outputs) ==="
+      matrix.rows.times do |r|
+        matrix.cols.times do |c|
+          out << format("  %-24s %-36s %s",
+                        "at(#{r},#{c})", "MTX_#{r}_#{c}_recv",
+                        "mtx.at(#{r}, #{c}, value)")
+        end
+      end
+      out << ""
+
+      out << "=== system ==="
+      system_params.each do |sym, param|
+        if AUTO_EMITTED.key?(sym)
+          out << format("  %-24s %-36s (%s)", sym, param.pd_name, AUTO_EMITTED[sym])
+        else
+          out << format("  %-24s %-36s %s", sym, param.pd_name, "system.#{sym}(value)")
+        end
+      end
+      out << ""
+
+      out << "=== resets ==="
+      reset_verbs.each do |sym|
+        out << format("  %-24s %-36s %s", sym, "reset_#{sym}_recv", "reset :#{sym}")
+      end
+      out << ""
+
+      out.join("\n")
+    end
+  end
+end

data/lib/cue_dsl/connect.rb

@@ -0,0 +1,28 @@
+# lib/cue_dsl/connect.rb
+module CueDSL
+  module Connect
+    # Matrix semantics: rows = inputs, cols = outputs.
+    # A >> B sets MTX[B_input_row][A_output_col] = 1.
+    # Returns [[row, col], ...] of matrix cells to set to 1.
+    def self.cells_for(a, b)
+      a_out = a.outputs
+      b_in  = b.inputs
+      raise ConnectionError, "#{a.name} has no outputs" if a_out.empty?
+      raise ConnectionError, "#{b.name} has no inputs"  if b_in.empty?
+
+      if a_out.length == 1 && b_in.length == 1
+        [[b_in[0], a_out[0]]]
+      elsif a_out.length == 1 && b_in.length == 2
+        [[b_in[0], a_out[0]], [b_in[1], a_out[0]]]
+      elsif a_out.length == 2 && b_in.length == 1
+        [[b_in[0], a_out[0]]]
+      elsif a_out.length == 2 && b_in.length == 2
+        [[b_in[0], a_out[0]], [b_in[1], a_out[1]]]
+      else
+        raise ConnectionError,
+              "cannot connect #{a.name}(#{a_out.length} out) >> " \
+              "#{b.name}(#{b_in.length} in); unsupported port geometry"
+      end
+    end
+  end
+end

data/lib/cue_dsl/cue.rb

@@ -0,0 +1,65 @@
+# lib/cue_dsl/cue.rb
+module CueDSL
+  class Cue
+    Action = Struct.new(:kind, :payload, keyword_init: true)
+    # kind: :param, :matrix, :reset, :system, :comment, :chain
+
+    attr_reader :name, :line, :devices, :actions, :resets
+
+    def initialize(name, line, reset_system: nil)
+      raise ConfigurationError, "cue name cannot be empty" if name.nil? || name.to_s.strip.empty?
+      @name         = name.to_s
+      @line         = line
+      @devices      = []
+      @actions      = []
+      @resets       = []
+      @reset_system = reset_system     # nil means "use the global default"
+    end
+
+    def add_device(dev)
+      @devices << dev unless @devices.include?(dev)
+    end
+
+    def record_param(line);   @actions << Action.new(kind: :param,   payload: line); end
+    def record_matrix(line);  @actions << Action.new(kind: :matrix,  payload: line); end
+    def record_system(line);  @actions << Action.new(kind: :system,  payload: line); end
+    def record_comment(text); @actions << Action.new(kind: :comment, payload: text); end
+    def record_reset(line);   @actions << Action.new(kind: :reset,   payload: line); end
+    def record_chain_marker(chain_devices)
+      @actions << Action.new(kind: :chain, payload: chain_devices)
+    end
+
+    # preview: nil (no preview line), or a string already formatted as "<n> - <name>".
+    def render(index:, matrix:, reset_system: true, header: nil, preview: nil)
+      header ||= "#{index} - #{name}"
+      out = []
+      out << "reset_system_recv bang" if reset_system
+      out << "header_message_recv #{escape(header)}"
+      out << "preview_cue_recv #{escape(preview)}" unless preview.nil?
+
+      @actions.each do |a|
+        case a.kind
+        when :chain
+          a.payload.each_cons(2) do |x, y|
+            Connect.cells_for(x, y).each { |(r, c)| out << "MTX_#{r}_#{c}_recv 1" }
+          end
+        else
+          out << a.payload
+        end
+      end
+
+      out << "pause"
+      out
+    end
+
+    def reset_system?
+      @reset_system
+    end
+
+    private
+
+    def escape(str)
+      str.gsub(/[ ,;]/) { |m| "\\#{m}" }
+    end
+  end
+end

data/lib/cue_dsl/device.rb

@@ -0,0 +1,61 @@
+# lib/cue_dsl/device.rb
+module CueDSL
+  class Device
+    attr_reader :name, :label, :inputs, :outputs, :parameters, :filter_count
+
+    def initialize(name:, label:, inputs:, outputs:, parameters:, filter_count: 0)
+      @name         = name
+      @label        = label
+      @inputs       = inputs
+      @outputs      = outputs
+      @parameters   = parameters
+      @filter_count = filter_count
+      @filter_bank  = {}
+      @cue          = nil
+      @filter_fc_params_by_index = Hash.new { |h, k| h[k] = {} }
+
+      parameters.each do |short, param|
+        next unless param.kind == :normal
+        next unless short.is_a?(Symbol) || short.is_a?(String)
+        define_singleton_method(short) do |value, ms = nil|
+          record_param(param.emit(value, ms))
+        end
+      end
+
+      if filter_count.positive?
+        define_singleton_method(:fc) do |i|
+          unless (0...filter_count).cover?(i)
+            raise ArgumentError, "FC index out of range 0..#{filter_count - 1}"
+          end
+          @filter_bank[i] ||= FilterBank.new(self, i)
+        end
+      end
+    end
+
+    def >>(other)
+      Chain.new([self, other])
+    end
+
+    def filter_fc_params_for(index)
+      @filter_fc_params_by_index[index] || {}
+    end
+
+    def register_filter_fc(param)
+      name = param.short_name.to_s.sub(/\Afc_#{param.index}_/, "").to_sym
+      @filter_fc_params_by_index[param.index][name] = param
+    end
+
+    def bind(cue); @cue = cue; end
+    def unbind;    @cue = nil; end
+
+    def record_param(line)
+      raise Error, "device #{name} used outside a cue" if @cue.nil?
+      @cue.record_param(line)
+    end
+
+    def record_matrix(line)
+      raise Error, "matrix used outside a cue" if @cue.nil?
+      @cue.record_matrix(line)
+    end
+  end
+end

data/lib/cue_dsl/devices_config.rb

@@ -0,0 +1,52 @@
+# lib/cue_dsl/devices_config.rb
+require "yaml"
+
+module CueDSL
+  class DevicesConfig
+    Entry = Struct.new(:name, :label, :inputs, :outputs, :filter_count, keyword_init: true)
+
+    attr_reader :matrix_rows, :matrix_cols, :entries
+
+    def self.load(path)
+      new(YAML.safe_load(File.read(path), permitted_classes: [Symbol]) || {})
+    end
+
+    def initialize(hash)
+      @matrix_rows = hash.dig("matrix", "rows") or
+        raise ConfigurationError, "devices.yml: missing matrix.rows"
+      @matrix_cols = hash.dig("matrix", "cols") or
+        raise ConfigurationError, "devices.yml: missing matrix.cols"
+      @entries = {}
+      (hash["devices"] || {}).each do |name, spec|
+        @entries[name] = Entry.new(
+          name: name,
+          label: spec["label"] || name,
+          inputs:  Array(spec["inputs"]),
+          outputs: Array(spec["outputs"]),
+          filter_count: spec["filters"].to_i
+        )
+      end
+    end
+
+    def resolve(token)
+      key = normalize(token)
+      return @entries[key] if @entries.key?(key)
+      found = @entries.values.find { |e| normalize(e.label) == key }
+      return found if found
+      raise UnknownDeviceError,
+            "unknown device #{token.inspect} (try one of #{@entries.keys.join(', ')})"
+    end
+
+    private
+
+    def normalize(str)
+      str.to_s
+         .unicode_normalize(:nfkd)
+         .encode("ASCII", invalid: :replace, undef: :replace, replace: "")
+         .upcase
+         .gsub(/[^\p{Alnum}]+/, "_")
+         .sub(/\A_+/, "")
+         .sub(/_+\z/, "")
+    end
+  end
+end

data/lib/cue_dsl/errors.rb

@@ -0,0 +1,7 @@
+# lib/cue_dsl/errors.rb
+module CueDSL
+  class Error < StandardError; end
+  class ConnectionError < Error; end
+  class UnknownDeviceError < Error; end
+  class ConfigurationError < Error; end
+end

data/lib/cue_dsl/filter_bank.rb

@@ -0,0 +1,17 @@
+# lib/cue_dsl/filter_bank.rb
+module CueDSL
+  class FilterBank
+    attr_reader :index
+
+    def initialize(owner, index)
+      @owner = owner
+      @index = index
+      params = owner.filter_fc_params_for(index)
+      params.each do |short, param|
+        define_singleton_method(short) do |value, ms = nil|
+          @owner.record_param(param.emit(value, ms))
+        end
+      end
+    end
+  end
+end

data/lib/cue_dsl/matrix.rb

@@ -0,0 +1,41 @@
+# lib/cue_dsl/matrix.rb
+module CueDSL
+  class Matrix < Device
+    UNSET = Object.new.freeze
+    attr_reader :rows, :cols
+
+    def initialize(rows:, cols:, parameters:)
+      super(name: "MTX", label: "Matrix", inputs: [], outputs: [], parameters: parameters)
+      @rows = rows
+      @cols = cols
+    end
+
+    # mtx.at(r, c, v)  -> records the message immediately
+    # mtx.at(r, c).(v) -> defers via CellSetter#call
+    def at(row, col, value = UNSET)
+      raise ArgumentError, "row #{row} out of range 0..#{rows - 1}" unless (0...rows).cover?(row)
+      raise ArgumentError, "col #{col} out of range 0..#{cols - 1}" unless (0...cols).cover?(col)
+      return CellSetter.new(self, row, col) if value.equal?(UNSET)
+      record_matrix("MTX_#{row}_#{col}_recv #{self.class.format_value(value)}")
+    end
+
+    def self.format_value(v)
+      case v
+      when Symbol then v.to_s
+      when Float  then v == v.to_i ? v.to_i.to_s : v.to_s
+      else v.to_s
+      end
+    end
+
+    class CellSetter
+      def initialize(matrix, row, col)
+        @matrix, @row, @col = matrix, row, col
+      end
+
+      def set(v)
+        @matrix.record_matrix("MTX_#{@row}_#{@col}_recv #{Matrix.format_value(v)}")
+      end
+      alias_method :call, :set
+    end
+  end
+end

data/lib/cue_dsl/parameter.rb

@@ -0,0 +1,33 @@
+# lib/cue_dsl/parameter.rb
+module CueDSL
+  class Parameter
+    attr_reader :pd_name, :device_prefix, :short_name, :kind, :index
+
+    def initialize(pd_name:, device_prefix:, short_name:, kind: :normal, index: nil)
+      @pd_name       = pd_name
+      @device_prefix = device_prefix
+      @short_name    = short_name
+      @kind          = kind
+      @index         = index
+    end
+
+    def emit(value, ms = nil)
+      if ms.nil?
+        "#{pd_name} #{format_value(value)}"
+      else
+        "#{pd_name} #{format_value(value)} #{format_value(ms)}"
+      end
+    end
+
+    def format_value(value)
+      case value
+      when Symbol then value.to_s
+      when Float
+        return value.to_i.to_s if value == value.to_i
+        value.to_s
+      else
+        value.to_s
+      end
+    end
+  end
+end

data/lib/cue_dsl/receivers_loader.rb

@@ -0,0 +1,74 @@
+# lib/cue_dsl/receivers_loader.rb
+module CueDSL
+  class ReceiversLoader
+    RESET_RE     = /\Areset_(\w+)_recv\z/
+    TEMPLATE_RE  = /\$[0-9]/
+    SYSTEM_RE    = /\A(cue_step|git_describe|header_message|preview_cue|system_init)_recv\z/
+    FILTER_FC_RE = /\AFILTER_fc_(\d+)_(\w+)_recv\z/
+
+    Result = Struct.new(:devices, :matrix_params, :system_params, :reset_verbs, keyword_init: true)
+
+    def self.load(path)
+      new(File.readlines(path, chomp: true)).load
+    end
+
+    def initialize(lines)
+      @lines = lines.map(&:strip).reject(&:empty?)
+    end
+
+    def load
+      devices       = Hash.new { |h, k| h[k] = {} }
+      matrix_params = {}
+      system_params = {}
+      reset_verbs   = []
+
+      @lines.each do |line|
+        next if line.match?(TEMPLATE_RE)
+
+        if (m = RESET_RE.match(line))
+          reset_verbs << m[1].to_sym
+          next
+        end
+
+        if (m = SYSTEM_RE.match(line))
+          system_params[m[1].to_sym] = Parameter.new(
+            pd_name: line, device_prefix: "system", short_name: m[1], kind: :system
+          )
+          next
+        end
+
+        if (m = /\AMTX_(\d+)_(\d+)_recv\z/.match(line))
+          r, c = m[1].to_i, m[2].to_i
+          matrix_params[[r, c]] = Parameter.new(
+            pd_name: line, device_prefix: "MTX", short_name: "#{r}_#{c}"
+          )
+          next
+        end
+
+        next unless line =~ /\A[A-Z]/
+
+        if (m = FILTER_FC_RE.match(line))
+          idx  = m[1].to_i
+          name = m[2]
+          devices["FILTER"][:"fc_#{idx}_#{name}"] = Parameter.new(
+            pd_name: line, device_prefix: "FILTER",
+            short_name: "fc_#{idx}_#{name}", kind: :filter_fc, index: idx
+          )
+          next
+        end
+
+        prefix, *rest = line.sub(/_recv\z/, "").split("_")
+        short = rest.join("_")
+        next if short.empty?
+        devices[prefix][short] = Parameter.new(
+          pd_name: line, device_prefix: prefix, short_name: short
+        )
+      end
+
+      Result.new(
+        devices: devices, matrix_params: matrix_params,
+        system_params: system_params, reset_verbs: reset_verbs
+      )
+    end
+  end
+end

data/lib/cue_dsl/version.rb

@@ -0,0 +1,4 @@
+# lib/cue_dsl/errors.rb
+module CueDSL
+  VERSION = "1.0.0"
+end