SPB Git

Repository Public

syntax.md 9.0 KB

# 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.

orixdj
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)
}
text
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.
  • else may 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.
orixdj
deck.A.eq.low = -6dB; deck.A.eq.mid = -3dB
if deck.B.playing
{
    deck.B.pause()
}
else
{
    deck.B.play()
}

# Comments

orixdj
// 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 = 0dB

A 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:

text
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  none
orixdj-error
let beat = 4
text
'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, bars may 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.
  • bpm and st are accepted for readability and give a plain number: 128bpm is 128, -2st is -2.
  • A negative literal is a minus sign applied to a positive one; -12dB and - 12dB are 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.

orixdj
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

text
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.

Files main
Menu

Theme