Repository Public
1// ORIX DJ2// File: Packages/ORIXDJCore/Sources/ORIXScript/Reference.swift3// Description: Reference documentation generated from the language schema: the API chapters of the Docs tab, the4// files under docs/orix-script, and the language description given to Claude all come from here.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation9import ORIXDSP1011public enum ReferenceGenerator {12 private static func row(_ cells: [String]) -> String { "| " + cells.joined(separator: " | ") + " |" }1314 private static func paramTable(_ prefix: String, _ params: [ParamDef]) -> String {15 var lines = [row(["Path", "Type", "Range", "Default", "Access", "Description"]), row(["---", "---", "---", "---", "---", "---"])]16 for p in params {17 lines.append(row(["`\(prefix)\(p.key)`", "\(p.type)", (p.rangeText.isEmpty || (!p.writable && p.min == p.max)) ? "–" : p.rangeText, p.writable ? "`\(p.defaultValue)`" : "–", p.writable ? (p.rampable ? "read, write, ramp" : "read, write") : "read", p.doc]))18 }19 return lines.joined(separator: "\n")20 }2122 private static func actionTable(_ prefix: String, _ actions: [ActionDef]) -> String {23 var lines = [row(["Action", "Arguments", "Description"]), row(["---", "---", "---"])]24 for a in actions {25 let args = a.params.isEmpty ? "–" : a.params.map { "`\($0.name)`: \($0.type)\($0.optional ? " (optional)" : ""). \($0.doc)" }.joined(separator: " ")26 lines.append(row(["`\(prefix)\(a.signature)`", args, a.doc]))27 }28 return lines.joined(separator: "\n")29 }3031 public static var deckAPI: String {32 """33 ## Deck parameters and properties3435 Decks are `deck.A`, `deck.B`, `deck.C` and `deck.D`. A variable of type `deck` can be used in place of `deck.X`.3637 \(paramTable("deck.X.", ScriptSchema.deckParams))3839 ## Deck actions4041 \(actionTable("deck.X.", ScriptSchema.deckActions))4243 ## Deck events4445 \(([row(["Event", "Fires when"]), row(["---", "---"])] + ScriptSchema.deckEvents.map { row(["`on deck.X.\($0.name) { … }`", $0.doc]) }).joined(separator: "\n"))46 """47 }4849 public static var mixerAPI: String {50 """51 ## Mixer parameters5253 \(paramTable("mixer.", ScriptSchema.mixerParams))5455 ## Channel aliases5657 `mixer.channel.X.<name>` addresses the same parameter as the deck path.5859 \(([row(["Alias", "Same as"]), row(["---", "---"])] + ScriptSchema.mixerChannelAliases.sorted { $0.key < $1.key }.map { row(["`mixer.channel.X.\($0.key)`", "`deck.X.\($0.value)`"]) }).joined(separator: "\n"))6061 ## Master clock6263 \(paramTable("master.", ScriptSchema.masterParams))6465 ## Global events6667 \(([row(["Event", "Fires when"]), row(["---", "---"])] + ScriptSchema.globalEvents.map { row(["`on \($0.name) { … }`", $0.doc]) }).joined(separator: "\n"))68 """69 }7071 public static var effectsAPI: String {72 var out = """73 ## Racks7475 `fx.<effect>` addresses the master rack. `deck.X.fx.<effect>` addresses the rack of a channel. A rack holds at most one unit of each effect and eight units in total. Writing a parameter of an effect that is not in the rack adds it, switched off.7677 ## Actions7879 \(actionTable("fx.<effect>.", ScriptSchema.fxActions))8081 """82 for kind in EffectKind.allCases {83 let d = EffectCatalog.descriptor(kind)84 out += "\n## \(d.displayName) — `fx.\(kind.rawValue)`\n\n\(d.summary)\n\n\(paramTable("fx.\(kind.rawValue).", ScriptSchema.fxParams(kind)))\n"85 }86 return out87 }8889 public static var builtins: String {90 ([row(["Function", "Description"]), row(["---", "---"])] + ScriptSchema.builtins.map { row(["`\($0.signature)`", $0.doc]) }).joined(separator: "\n")91 }9293 public static var limits: String {94 let r = RuntimeLimits()95 return ([row(["Limit", "Value"]), row(["---", "---"])] + [96 row(["Script size", "\(CompileLimits.maxSourceBytes / 1024) KB"]),97 row(["Statements per script", "\(CompileLimits.maxStatements)"]),98 row(["Iterations of one loop", "\(CompileLimits.maxLoopIterations)"]),99 row(["Array length", "\(CompileLimits.maxArrayLength)"]),100 row(["Shortest `every` period", "1/64 beat"]),101 row(["Event handlers per automation", "\(CompileLimits.maxHandlers)"]),102 row(["Operations without a wait", "\(r.maxOperationsPerStep)"]),103 row(["Operations over the life of an automation", "\(r.maxTotalOperations)"]),104 row(["Scheduled blocks at once", "\(r.maxTasks)"]),105 row(["Ramps at once", "\(r.maxRamps)"]),106 row(["Commands per beat (ramps excluded)", "\(r.maxCommandsPerBeat)"]),107 row(["Longest wait or ramp", "\(Int(r.maxSpanBeats)) beats"]),108 row(["Function call depth", "\(r.maxCallDepth)"]),109 ]).joined(separator: "\n")110 }111112 static let generatedNote = "> This chapter is generated from the language schema (`swift run orix-dj-bench docs`). Do not edit it by hand."113114 /// File name and content of the chapters generated from the schema.115 public static var generatedChapters: [(file: String, content: String)] {116 [117 ("deck-api.md", "# Deck commands\n\n\(generatedNote)\n\n\(deckAPI)\n"),118 ("mixer-api.md", "# Mixer commands\n\n\(generatedNote)\n\n\(mixerAPI)\n"),119 ("effects-api.md", "# Effects commands\n\n\(generatedNote)\n\n\(effectsAPI)\n"),120 ("api-reference.md", generatedNote + "\n\n" + completeReference),121 ]122 }123124 /// The whole API reference as one Markdown document.125 public static var completeReference: String {126 "# Complete API reference\n\nGenerated from the language schema of ORIX Script \(ORIXScriptLanguage.version). Every path listed here is accepted by the compiler; nothing else is.\n\n# Decks\n\n\(deckAPI)\n\n# Mixer and master clock\n\n\(mixerAPI)\n\n# Effects\n\n\(effectsAPI)\n\n# Builtin functions\n\n\(builtins)\n\n# Limits\n\n\(limits)\n"127 }128129 /// Compact language description for a model that has to write ORIX Script. Stable text: it is sent as a cached system prompt.130 public static var languageBrief: String {131 func compact(_ prefix: String, _ params: [ParamDef]) -> String {132 params.map { "\(prefix)\($0.key): \($0.type)\($0.writable ? "" : " (read-only)")\($0.rangeText.isEmpty ? "" : " [\($0.rangeText)]")" }.joined(separator: "\n")133 }134 var fx = ""135 for kind in EffectKind.allCases {136 fx += "fx.\(kind.rawValue): " + ScriptSchema.fxParams(kind).filter { $0.key != "enabled" }.map { "\($0.key) \($0.type) [\($0.rangeText)]" }.joined(separator: "; ") + "\n"137 }138 return """139 ORIX Script \(ORIXScriptLanguage.version) is the automation language of ORIX DJ. A script is validated by a compiler before it can run; anything not listed below is a compile error.140141 STRUCTURE142 automation "Name" [quantize bar|beat|none] { statements }143 Optional top level: `let NAME = constant`, `fn name(p: type, …) { … }` (timed procedure) or `fn name(p: type) -> type { … return x }` (pure function, no timing, no live values).144 One statement per line. Comments: // and /* */.145146 TYPES AND LITERALS147 number (1, 0.5, 50% = 0.5, 128bpm, 2st), duration (4beats, 8 bars, 1/4beat, 2s, 250ms), gain (-6dB; -60dB is silence), frequency (800Hz, 12kHz), bool (true/false), string ("text"), deck (deck.A), arrays ([1, 2, 3], same type, max \(CompileLimits.maxArrayLength)).148 Types never mix: gain parameters take dB, frequency parameters take Hz/kHz, durations take a unit. A plain number given to a gain parameter is a linear level 0…1.149150 STATEMENTS151 let x = expr / var x = expr / x = expr (only var)152 path = value set a parameter now153 path(args) call an action154 wait 4beats / wait nextBeat / wait nextBar / wait until bar 9155 at bar N { … } / at beat N { … } / at 16beats { … } / at nextBar { … } schedule a block; bars and beats count from 1 at the start of the automation; `at` does not delay the statements after it156 over 8 bars [curve linear|easeIn|easeOut|smooth|exp] { path -> target } ramp parameters; blocks until done; inside only `->` ramps, `=` and actions are allowed157 every 1beat for 8beats { … } repeat on a grid158 repeat N { … } / for i in 1...8 { … } / for x in [a, b] { … } / while cond limit 64 { … }159 if cond { … } else if cond { … } else { … }160 on deck.A.trackEnd [once] { … } / on beat { … } / on bar { … } / on trigger(1) { … } an automation with handlers runs until `stop`161 stop, break, continue, return, print(values…)162 Operators: + - * / %, == != < <= > >=, and or not.163 `->` is only valid inside `over`. Durations in seconds are converted with the current tempo. 4 beats per bar.164165 DECK PATHS (X = A, B, C, D)166 \(compact("deck.X.", ScriptSchema.deckParams))167 Actions: \(ScriptSchema.deckActions.map { "deck.X.\($0.signature)" }.joined(separator: ", "))168 Events: \(ScriptSchema.deckEvents.map { "deck.X.\($0.name)" }.joined(separator: ", ")), beat, bar, trigger(1…\(ScriptSchema.triggerCount))169170 MIXER AND CLOCK171 \(compact("mixer.", ScriptSchema.mixerParams))172 mixer.channel.X.{volume, gain, eq.low, eq.mid, eq.high, filter, cue} are aliases of the deck paths.173 \(compact("master.", ScriptSchema.masterParams))174175 EFFECTS (master rack: fx.NAME…, channel rack: deck.X.fx.NAME…; actions enable(), disable(), toggle(); every effect also has `mix` 0…1)176 \(fx)177 BUILTINS178 \(ScriptSchema.builtins.map(\.signature).joined(separator: "; "))179180 LIMITS181 Loops need a bound (max \(CompileLimits.maxLoopIterations) iterations). No recursion. No file, network, shell or system access exists in the language.182 """183 }184}185