SPB Git

Repository Public

variables.md 6.5 KB 211 lines markdown

1# Variables23A variable is a name for a value: a fade length, a level to come back to, a counter. Naming a value lets you write it once and use it in several places, and lets a script remember something for later.45## Declaring: `let` and `var`67Every variable must be declared before it is used.89- `let` declares a name whose value never changes.10- `var` declares a name whose value can be changed later.1112```orixdj13let fade = 8 bars          // fixed14var hits = 0               // will change1516hits = hits + 117over fade { deck.A.volume -> -60dB }18deck.A.volume = 0dB19```2021A declaration always has an initial value. The value decides the type of the variable; it keeps that type for its whole life.2223Use `let` unless you really need to change the value. The compiler then protects you from changing it by mistake.2425## Remembering a setting2627The most common use of a variable in a DJ script is to remember where a control was, so that you can put it back.2829```orixdj30let before = deck.A.volume     // read the fader now3132over 2 bars { deck.A.volume -> -20dB }33wait 2 bars34over 1 bar { deck.A.volume -> before }35```3637`let before = deck.A.volume` reads the fader once, at that moment. If the fader moves later, `before` does not change. To get the current value again, read the path again.3839## Why declarations are required4041Writing `tempo = master.bpm` without `let` or `var` is an error:4243```orixdj-error44tempo = master.bpm45```4647```text48'tempo' is not declared. Declare it first: let tempo = …  (or 'var' if it changes). [E-UNDECLARED]49```5051This is deliberate. If an assignment could create a variable silently, a typing mistake would go unnoticed: you would mean to change `hits`, type `hist`, and the script would run with a new, useless variable instead of telling you. With explicit declarations, every misspelt name is caught before the script runs. See [Migration Guides](migration.md).5253## Changing a `let` is an error5455```orixdj-error56let level = -6dB57level = -12dB58```5960```text61'level' was declared with 'let' and cannot change. Declare it with 'var'. [E-CONST]62```6364## The type cannot change6566```orixdj-error67var level = -6dB68level = 0.569```7071```text72Cannot assign number to 'level' of type gain. [E-TYPE]73```7475## Optional type annotation7677You may state the type after the name. The compiler checks that the value has that type. It is never required, but it documents the intention.7879```orixdj80let cutoff: frequency = 800Hz81var open: bool = false82let pattern: [number] = [1, 0, 1, 1]83let target: deck = deck.B84print(cutoff, open, pattern, target)85```8687The type names are `number`, `duration`, `gain`, `frequency`, `bool`, `string`, `deck`, and `[type]` for an array.8889## Scope: where a name is visible9091A variable is visible from its declaration to the end of the block (the pair of braces) in which it is declared, including the blocks nested inside.9293```orixdj94let outer = 195if deck.A.playing {96    let inner = 297    print(outer + inner)     // both visible here98}99print(outer)                 // 'inner' no longer exists here100```101102Rules:103104- Two variables in the same block cannot have the same name (`E-REDECLARED`).105- A nested block may declare a name that already exists outside; inside that block the new variable hides the outer one.106- The variable of a `for` loop exists only inside the loop and cannot be assigned.107- Function parameters behave like `let`: they cannot be assigned.108- One automation or function can declare at most 512 variables.109110## Top-level constants111112A `let` written outside any automation is a constant shared by every automation and function of the file.113114```orixdj115let blend = 8 bars116let quiet = -18dB117118automation "In" quantize bar {119    deck.B.volume = quiet120    deck.B.play()121    over blend { deck.B.volume -> 0dB }122}123124automation "Out" quantize bar {125    over blend { deck.A.volume -> quiet }126}127```128129A top-level constant must be a constant expression: literals, arithmetic on them, and builtins such as `bars(8)`. It cannot read a live value, because no automation is running when the file is loaded.130131```orixdj-error132let tempo = master.bpm133134automation "X" {135    print(tempo)136}137```138139```text140A top-level 'let' must be a constant expression; read live values inside an automation. [E-CONST]141```142143Only `let` is allowed at the top level; `var` is not. If a variable inside an automation has the same name as a top-level constant, the compiler warns (`W-SHADOW`) because the constant is hidden there.144145## Variables and scheduled blocks146147Two statements run their block later: `at` and `on`. They treat variables differently, and the difference matters.148149**`at` takes a snapshot.** A block scheduled with `at` sees the variables as they were at the moment the `at` statement ran. Later changes are not seen by the block, and changes made inside the block are not seen outside.150151```orixdj152var level = -6dB153at bar 2 { deck.A.volume = level }     // will use -6 dB154level = -12dB                          // does not affect the scheduled block155wait 2 bars156deck.A.volume = 0dB157```158159This is what makes scheduling inside a loop work: each scheduled block keeps the value the loop variable had when it was scheduled.160161```orixdj162for step in 1...4 {163    at beat step * 4 { print("scheduled as number", step) }164}165```166167**`on` shares the variables.** An event handler works with the automation's own variables: it sees their current values and its changes are visible everywhere.168169```orixdj170var barCount = 0171on bar {172    barCount = barCount + 1173}174wait 8 bars175print("bars counted:", barCount)176stop177```178179## Arrays180181An array is an ordered list of values of the same type. Elements are numbered from 0.182183```orixdj184let cuts = [-3dB, -6dB, -12dB, -26dB]185deck.A.eq.high = cuts[0]186print(len(cuts))                // 4187for cut in cuts {188    deck.A.eq.low = cut189    wait 1 beat190}191deck.A.eq.low = 0dB192deck.A.eq.high = 0dB193```194195An array has at least one element and at most 256. Arrays cannot contain arrays. An index outside the array is an error (`E-RANGE`), found by the compiler when the index is a constant and at run time otherwise. There is no statement to change one element; build a new array instead.196197## Naming advice198199- Reserved words cannot be used for variables, `for` loop variables or function parameters: `bar`, `beat`, `deck`, `limit`, `curve`, `once`… The full list is in [Language Syntax](syntax.md). Use `barCount`, `maxTurns`, `shape`.200- Names are case-sensitive.201- Say what the value is for: `fadeLength`, `quietLevel`, `returnCutoff` are easier to read on stage than `x` and `t2`.202203## Related204205- [Types](types.md)206- [Units](units.md)207- [Language Syntax](syntax.md)208- [Functions](functions.md)209- [Events](events.md)210- [Migration Guides](migration.md)211
Files main
Menu

Theme