SPB Git

Repository Public

Reference.swift 9.9 KB 185 lines swift

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
Files main
Menu

Theme