SPB Git

Repository Public

syntax.md 9.0 KB 242 lines markdown

1# Language Syntax23This chapter is the complete description of how ORIX Script text is written. The other chapters explain what each statement does; this one tells you exactly what the compiler accepts.45## A script file67A file contains, in any order:89- constants: `let name = constant`;10- functions: `fn name(parameters) { … }`;11- automations: `automation "Name" { … }`.1213Nothing else may appear at the top level. A file must define at least one automation.1415```orixdj16let fadeLength = 4 bars1718fn restore(d: deck) {19    d.volume = 0dB20    d.eq.low = 0dB21}2223automation "Fade And Restore" quantize bar {24    over fadeLength { deck.A.volume -> -60dB }25    deck.A.pause()26    restore(deck.A)27}28```2930```text31file        = { constant | function | automation }32constant    = "let" name [ ":" type ] "=" expression33function    = "fn" name "(" [ parameter { "," parameter } ] ")" [ "->" type ] block34parameter   = name ":" type35automation  = "automation" string [ "quantize" ( "bar" | "beat" | "none" ) ] block36block       = "{" { statement } "}"37```3839Two automations in one file cannot have the same name, and the name cannot be empty.4041## Lines, semicolons and braces4243- One statement per line. A semicolon separates statements written on the same line.44- An opening brace may be at the end of the header line or on the next line.45- `else` may follow the closing brace on the same line or on the next line.46- A list in parentheses or square brackets may be split over several lines: after the opening bracket, after a comma, and before the closing bracket. An expression is otherwise written on one line.47- Indentation is free. The editor's formatter re-indents by brace depth with four spaces, trims trailing spaces and collapses runs of blank lines.4849```orixdj50deck.A.eq.low = -6dB; deck.A.eq.mid = -3dB51if deck.B.playing52{53    deck.B.pause()54}55else56{57    deck.B.play()58}59```6061## Comments6263```orixdj64// A comment runs to the end of the line.65deck.A.volume = -3dB   // It can follow a statement.66/* A block comment67   can span several lines. */68deck.A.volume = 0dB69```7071A block comment that is never closed is an error (`E-LEX`).7273## Names7475A name starts with a letter or an underscore and continues with letters, digits and underscores. Names are case-sensitive: `deck.A` exists, `deck.a` does not.7677These words are reserved and cannot name a variable, a `for` loop variable or a function parameter:7879```text80automation  quantize  let  var  fn  return  if  else  repeat  for  in  while  limit81every  wait  until  at  over  curve  on  once  stop  break  continue  true  false82and  or  not  bar  beat  bars  beats  nextBeat  nextBar  deck  mixer  fx  master83trigger  none84```8586```orixdj-error87let beat = 488```8990```text91'beat' is a reserved word and cannot name a variable. [E-SYNTAX]92```9394A function cannot take the name of a builtin function or of a reserved word.9596## Literals9798| Kind | Examples | Notes |99| --- | --- | --- |100| Number | `4`, `0.35`, `.5`, `1_000` | Underscores between digits are ignored. There is no exponent notation. |101| Percentage | `50%` | The number divided by 100: `50%` is `0.5`. |102| Gain | `-12dB`, `0dB`, `3.5dB` | Decibels. |103| Frequency | `80Hz`, `12kHz` | Hertz. |104| Musical duration | `1beat`, `4 beats`, `8 bars`, `1/4beat`, `3/2bars` | Follows the tempo. |105| Absolute duration | `250ms`, `2s`, `2sec`, `1min` | Converted with the tempo when used. |106| Boolean | `true`, `false` | |107| String | `"smooth"`, `"Night Drive"` | Double quotes, on one line, at most 512 characters. |108| Array | `[1, 2, 3]`, `[1/4beat, 1/8beat]` | One or more elements of the same type; at most 256. |109| Deck | `deck.A`, `deck.B`, `deck.C`, `deck.D` | |110111Rules for units:112113- A unit is written directly after the number: `-12dB`, `20Hz`, `250ms`.114- The four musical words `beat`, `beats`, `bar`, `bars` may also follow the number after a space on the same line: `8 bars`.115- A fraction is written without spaces inside it and only with a musical word: `1/4beat`, `3/2bars`. One space may separate the fraction from the word: `1/4 beat`.116- `bpm` and `st` are accepted for readability and give a plain number: `128bpm` is `128`, `-2st` is `-2`.117- A negative literal is a minus sign applied to a positive one; `-12dB` and `- 12dB` are the same.118119String escapes: `\"` for a quote, `\\` for a backslash, `\n` for a new line, `\t` for a tab.120121See [Units](units.md) for the details (spaces in fractions, `%` as percentage or remainder).122123## Expressions124125Operators, from the lowest to the highest precedence. Operators on the same row are evaluated from left to right.126127| Level | Operators | Meaning |128| --- | --- | --- |129| 1 | `or`, `\|\|` | Logical or |130| 2 | `and`, `&&` | Logical and |131| 3 | `==`, `!=` | Equal, not equal |132| 4 | `<`, `<=`, `>`, `>=` | Comparison |133| 5 | `+`, `-` | Sum, difference |134| 6 | `*`, `/`, `%` | Product, quotient, remainder |135| 7 | `-x`, `+x`, `not x`, `!x` | Sign, logical not |136| 8 | `a[i]` | Array element (the first is `a[0]`) |137138Parentheses group. Which types each operator accepts is described in [Types](types.md).139140```orixdj141let a = 2 + 3 * 4            // 14142let b = (2 + 3) * 4          // 20143let ready = deck.B.loaded and not deck.B.playing144let steps = [1/4beat, 1/8beat, 1/16beat]145let shortest = steps[2]146let room = min(deck.A.volume, -3dB)147print(a, b, ready, shortest, room)148```149150Other forms of expression:151152- a variable or constant name;153- a parameter path, which reads the live value: `deck.A.bpm`, `mixer.crossfader`, `fx.delay.feedback`;154- a function call: `max(a, b)`, `half(8)`.155156An action such as `deck.A.play()` is not an expression: it has no value.157158## Paths159160A path is a chain of names separated by dots.161162| Path | Addresses |163| --- | --- |164| `deck.A.volume` | A parameter of deck A. |165| `deck.A.play()` | An action of deck A. |166| `deck.A.fx.echo.mix` | A parameter of the echo in the channel rack of deck A. |167| `mixer.crossfader` | A mixer parameter. |168| `mixer.channel.B.eq.low` | The same control as `deck.B.eq.low`. |169| `master.bpm` | A property of the master clock. |170| `fx.reverb.size` | A parameter of the reverb in the master rack. |171| `d.volume` | A parameter of the deck held in the variable `d`. |172173## Statements174175```text176statement =177    ( "let" | "var" ) name [ ":" type ] "=" expression178  | name "=" expression                        change a variable179  | path "=" expression                        set a parameter now180  | path "->" expression                       ramp a parameter (only inside "over")181  | path "(" [ arguments ] ")"                 call an action or a function182  | "wait" expression183  | "wait" ( "nextBeat" | "nextBar" )184  | "wait" "until" position185  | "at" position block186  | "over" expression [ "curve" name ] block187  | "every" expression "for" expression block188  | "repeat" expression block189  | "for" name "in" expression ( "..." | "..<" ) expression block190  | "for" name "in" expression block191  | "while" expression "limit" expression block192  | "if" expression block [ "else" ( if-statement | block ) ]193  | "on" event [ "once" ] block194  | "return" [ expression ]195  | "stop" | "break" | "continue"196197position  = "bar" expression | "beat" expression | expression | "nextBeat" | "nextBar"198event     = "beat" | "bar" | "trigger" "(" expression ")" | deck "." event-name199type      = "number" | "duration" | "gain" | "frequency" | "bool" | "string" | "deck" | "[" type "]"200```201202Where each statement is explained:203204| Statement | Chapter |205| --- | --- |206| `let`, `var`, assignment to a variable | [Variables](variables.md) |207| `path = value`, `path()` | [Deck Commands](deck-api.md), [Mixer Commands](mixer-api.md), [Effects Commands](effects-api.md) |208| `wait`, `over`, `->`, `at` | [Timing](timing.md), [Beats and Bars](beats-and-bars.md), [Automation Scheduling](scheduling.md) |209| `every`, `repeat`, `for`, `while`, `break`, `continue` | [Loops](loops.md) |210| `if`, `else` | [Conditions](conditions.md) |211| `on` | [Events](events.md) |212| `fn`, `return` | [Functions](functions.md) |213| `stop` | [Automation Scheduling](scheduling.md) |214215## Where statements are allowed216217| Statement | In an automation | In a function without return type | In a function with return type | Inside `over` |218| --- | --- | --- | --- | --- |219| `let`, `var`, variable assignment | yes | yes | yes | yes |220| `path = value`, action call | yes | yes | no (`E-PURE`) | yes |221| `path -> value` | no (`E-RAMP`) | no | no | yes |222| `wait`, `at`, `over`, `every` | yes | yes | no (`E-PURE`) | no (`E-OVER`) |223| `repeat`, `for`, `while`, `if` | yes | yes | yes | no (`E-OVER`) |224| `on` | yes, outside loops | no (`E-EVENT`) | no | no |225| `return` | no (`E-RETURN`) | yes, without a value | yes, with a value | no |226| `stop` | yes | yes | no (`E-PURE`) | no |227| `print(…)` | yes | yes | no (`E-PURE`) | yes |228229## Nesting limits230231Blocks can be nested 20 levels deep, and so can expressions. A script can be 256 KB long and contain 20000 statements. See [Performance Guidelines](performance.md) for all the limits.232233## Related234235- [Variables](variables.md)236- [Types](types.md)237- [Units](units.md)238- [Timing](timing.md)239- [Functions](functions.md)240- [Error Handling](errors.md)241- [Complete API Reference](api-reference.md)242
Files main
Menu

Theme