SPB Git

Repository Public

migration.md 5.4 KB 147 lines markdown

1# Migration Guides23A migration guide explains how to adapt scripts written for one version of the language to the next. ORIX Script 1.0 is the first version, so **there is no earlier version to migrate from, and no script needs to be converted.** This chapter exists so that future guides have a place, and to document the one difference between the released language and its original design sketch.45## From the design sketch to 1.0: variables must be declared67### The difference89The first sketch of the language, written before the compiler existed, showed a variable being created by a plain assignment:1011```orixdj-error12automation "Eight Bar Transition" {13    tempo = master.bpm1415    over 8 bars {16        deck.A.volume -> -60dB17        deck.B.volume -> 0dB18    }19}20```2122In ORIX Script 1.0 this is an error:2324```text25'tempo' is not declared. Declare it first: let tempo = …  (or 'var' if it changes). [E-UNDECLARED]26```2728A variable must be introduced with `let` (a value that never changes) or `var` (a value that can be assigned again):2930```orixdj31automation "Eight Bar Transition" {32    let tempo = master.bpm3334    over 8 bars {35        deck.A.volume -> -60dB36        deck.B.volume -> 0dB37    }38    print("started at", tempo, "BPM")39}40```4142### Why4344A script is meant to run in front of an audience, unattended. If an assignment could create a variable, a typing mistake in a name would never be reported: the script would quietly create a second variable and carry on with the wrong value.4546Consider a counter that decides when to stop:4748```orixdj-error49var turns = 050repeat 8 {51    turn = turns + 1          // typo: 'turn' instead of 'turns'52    wait 1 beat53}54```5556With implicit variables this would run without complaint, `turns` would stay at 0 for ever, and whatever depended on it would misbehave on stage. With explicit declarations the compiler refuses the script before it runs and says exactly what is wrong:5758```text59'turn' is not declared. Declare it first: let turn = …  (or 'var' if it changes). [E-UNDECLARED]60```6162Two more benefits follow from the same rule:6364- `let` documents and enforces that a value is fixed. Assigning to it is the error `E-CONST`.65- The type of a variable is fixed at its declaration, so later assignments can be checked (`E-TYPE`).6667### How to adapt a script6869For each name that is assigned without having been declared:70711. Find its first assignment.722. Put `let` in front of it if the name is never assigned again, `var` if it is.733. If the first assignment is inside a block (`if`, a loop) but the name is used outside, move the declaration before the block with an initial value.7475| Sketch | ORIX Script 1.0 |76| --- | --- |77| `tempo = master.bpm` | `let tempo = master.bpm` |78| `count = 0` … `count = count + 1` | `var count = 0` … `count = count + 1` |79| `level = deck.A.volume` (read once, used later) | `let level = deck.A.volume` |8081```orixdj82automation "Adapted" {83    var count = 084    let level = deck.A.volume85    repeat 4 {86        count = count + 187        wait 1 beat88    }89    print(count, level)90}91```9293The compiler lists every undeclared name with its line, so the adaptation is mechanical: fix the reported lines until the script compiles.9495### A related point in the same sketch: `at bar 8` after `over 8 bars`9697The sketch ended its transition like this:9899```orixdj100automation "Sketch Ending" {101    over 8 bars {102        deck.A.volume -> -60dB103    }104    at bar 8 {105        deck.A.pause()106    }107    deck.A.volume = 0dB108}109```110111This compiles in 1.0, and it is worth understanding what it does. Bar 8 begins 28 beats in; when the cursor reaches the `at` statement, after the 32 beats of the ramp, that position is already 4 beats in the past. The block therefore runs immediately, with a warning in the log. The result is what the author wanted, by accident. The clear way to write it is to put the statements after the ramp:112113```orixdj114automation "Clear Ending" {115    over 8 bars {116        deck.A.volume -> -60dB117    }118    deck.A.pause()119    deck.A.volume = 0dB120}121```122123This is not a change of the language, only a reminder that `at` positions count from the start of the automation and from 1. See [Beats and Bars](beats-and-bars.md).124125## Scripts from other applications126127ORIX Script is not compatible with the scripting or mapping formats of other DJ software, and there is no importer for them. A routine from elsewhere has to be rewritten. The concepts usually map directly: a control change becomes `path = value`, a timed move becomes `over`, a quantized action becomes `wait nextBar` followed by the action. Claude Studio can help with the rewrite; its output is compiled and simulated like any other script.128129## Future versions130131When a new version of the language is released, this chapter will gain one section per version, each with:132133- the list of changes that affect existing scripts;134- for each change, a before and after example and the diagnostic that the new compiler reports for the old form;135- what happens to scripts stored in projects saved with the previous version.136137Until then, the state of things is simple: every script that compiles with your copy of ORIX DJ is a 1.0 script. See [Version Compatibility](versions.md) for what is recorded in projects and exported files.138139## Related140141- [Version Compatibility](versions.md)142- [Variables](variables.md)143- [Beats and Bars](beats-and-bars.md)144- [Timing](timing.md)145- [Error Handling](errors.md)146- [First Automation](first-automation.md)147
Files main
Menu

Theme