Language Syntax
This 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.
A script file
A file contains, in any order:
- constants:
let name = constant; - functions:
fn name(parameters) { … }; - automations:
automation "Name" { … }.
Nothing else may appear at the top level. A file must define at least one automation.
let fadeLength = 4 bars
fn restore(d: deck) {
d.volume = 0dB
d.eq.low = 0dB
}
automation "Fade And Restore" quantize bar {
over fadeLength { deck.A.volume -> -60dB }
deck.A.pause()
restore(deck.A)
}file = { constant | function | automation }
constant = "let" name [ ":" type ] "=" expression
function = "fn" name "(" [ parameter { "," parameter } ] ")" [ "->" type ] block
parameter = name ":" type
automation = "automation" string [ "quantize" ( "bar" | "beat" | "none" ) ] block
block = "{" { statement } "}"Two automations in one file cannot have the same name, and the name cannot be empty.
Lines, semicolons and braces
- One statement per line. A semicolon separates statements written on the same line.
- An opening brace may be at the end of the header line or on the next line.
elsemay follow the closing brace on the same line or on the next line.- 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.
- Indentation is free. The editor's formatter re-indents by brace depth with four spaces, trims trailing spaces and collapses runs of blank lines.
deck.A.eq.low = -6dB; deck.A.eq.mid = -3dB
if deck.B.playing
{
deck.B.pause()
}
else
{
deck.B.play()
}Comments
// A comment runs to the end of the line.
deck.A.volume = -3dB // It can follow a statement.
/* A block comment
can span several lines. */
deck.A.volume = 0dBA block comment that is never closed is an error (E-LEX).
Names
A 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.
These words are reserved and cannot name a variable, a for loop variable or a function parameter:
automation quantize let var fn return if else repeat for in while limit
every wait until at over curve on once stop break continue true false
and or not bar beat bars beats nextBeat nextBar deck mixer fx master
trigger nonelet beat = 4'beat' is a reserved word and cannot name a variable. [E-SYNTAX]A function cannot take the name of a builtin function or of a reserved word.
Literals
| Kind | Examples | Notes |
|---|---|---|
| Number | 4, 0.35, .5, 1_000 |
Underscores between digits are ignored. There is no exponent notation. |
| Percentage | 50% |
The number divided by 100: 50% is 0.5. |
| Gain | -12dB, 0dB, 3.5dB |
Decibels. |
| Frequency | 80Hz, 12kHz |
Hertz. |
| Musical duration | 1beat, 4 beats, 8 bars, 1/4beat, 3/2bars |
Follows the tempo. |
| Absolute duration | 250ms, 2s, 2sec, 1min |
Converted with the tempo when used. |
| Boolean | true, false |
|
| String | "smooth", "Night Drive" |
Double quotes, on one line, at most 512 characters. |
| Array | [1, 2, 3], [1/4beat, 1/8beat] |
One or more elements of the same type; at most 256. |
| Deck | deck.A, deck.B, deck.C, deck.D |
Rules for units:
- A unit is written directly after the number:
-12dB,20Hz,250ms. - The four musical words
beat,beats,bar,barsmay also follow the number after a space on the same line:8 bars. - 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. bpmandstare accepted for readability and give a plain number:128bpmis128,-2stis-2.- A negative literal is a minus sign applied to a positive one;
-12dBand- 12dBare the same.
String escapes: \" for a quote, \\ for a backslash, \n for a new line, \t for a tab.
See Units for the details (spaces in fractions, % as percentage or remainder).
Expressions
Operators, from the lowest to the highest precedence. Operators on the same row are evaluated from left to right.
| Level | Operators | Meaning |
|---|---|---|
| 1 | or, || |
Logical or |
| 2 | and, && |
Logical and |
| 3 | ==, != |
Equal, not equal |
| 4 | <, <=, >, >= |
Comparison |
| 5 | +, - |
Sum, difference |
| 6 | *, /, % |
Product, quotient, remainder |
| 7 | -x, +x, not x, !x |
Sign, logical not |
| 8 | a[i] |
Array element (the first is a[0]) |
Parentheses group. Which types each operator accepts is described in Types.
let a = 2 + 3 * 4 // 14
let b = (2 + 3) * 4 // 20
let ready = deck.B.loaded and not deck.B.playing
let steps = [1/4beat, 1/8beat, 1/16beat]
let shortest = steps[2]
let room = min(deck.A.volume, -3dB)
print(a, b, ready, shortest, room)Other forms of expression:
- a variable or constant name;
- a parameter path, which reads the live value:
deck.A.bpm,mixer.crossfader,fx.delay.feedback; - a function call:
max(a, b),half(8).
An action such as deck.A.play() is not an expression: it has no value.
Paths
A path is a chain of names separated by dots.
| Path | Addresses |
|---|---|
deck.A.volume |
A parameter of deck A. |
deck.A.play() |
An action of deck A. |
deck.A.fx.echo.mix |
A parameter of the echo in the channel rack of deck A. |
mixer.crossfader |
A mixer parameter. |
mixer.channel.B.eq.low |
The same control as deck.B.eq.low. |
master.bpm |
A property of the master clock. |
fx.reverb.size |
A parameter of the reverb in the master rack. |
d.volume |
A parameter of the deck held in the variable d. |
Statements
statement =
( "let" | "var" ) name [ ":" type ] "=" expression
| name "=" expression change a variable
| path "=" expression set a parameter now
| path "->" expression ramp a parameter (only inside "over")
| path "(" [ arguments ] ")" call an action or a function
| "wait" expression
| "wait" ( "nextBeat" | "nextBar" )
| "wait" "until" position
| "at" position block
| "over" expression [ "curve" name ] block
| "every" expression "for" expression block
| "repeat" expression block
| "for" name "in" expression ( "..." | "..<" ) expression block
| "for" name "in" expression block
| "while" expression "limit" expression block
| "if" expression block [ "else" ( if-statement | block ) ]
| "on" event [ "once" ] block
| "return" [ expression ]
| "stop" | "break" | "continue"
position = "bar" expression | "beat" expression | expression | "nextBeat" | "nextBar"
event = "beat" | "bar" | "trigger" "(" expression ")" | deck "." event-name
type = "number" | "duration" | "gain" | "frequency" | "bool" | "string" | "deck" | "[" type "]"Where each statement is explained:
| Statement | Chapter |
|---|---|
let, var, assignment to a variable |
Variables |
path = value, path() |
Deck Commands, Mixer Commands, Effects Commands |
wait, over, ->, at |
Timing, Beats and Bars, Automation Scheduling |
every, repeat, for, while, break, continue |
Loops |
if, else |
Conditions |
on |
Events |
fn, return |
Functions |
stop |
Automation Scheduling |
Where statements are allowed
| Statement | In an automation | In a function without return type | In a function with return type | Inside over |
|---|---|---|---|---|
let, var, variable assignment |
yes | yes | yes | yes |
path = value, action call |
yes | yes | no (E-PURE) |
yes |
path -> value |
no (E-RAMP) |
no | no | yes |
wait, at, over, every |
yes | yes | no (E-PURE) |
no (E-OVER) |
repeat, for, while, if |
yes | yes | yes | no (E-OVER) |
on |
yes, outside loops | no (E-EVENT) |
no | no |
return |
no (E-RETURN) |
yes, without a value | yes, with a value | no |
stop |
yes | yes | no (E-PURE) |
no |
print(…) |
yes | yes | no (E-PURE) |
yes |
Nesting limits
Blocks can be nested 20 levels deep, and so can expressions. A script can be 256 KB long and contain 20000 statements. See Performance Guidelines for all the limits.