Repository Public
1# Functions23A function is a named piece of script that you write once and use many times. A fade that works for deck A can work for any deck if the deck becomes a parameter. A calculation used in three places can have a name.45ORIX Script has two kinds of function, and the difference is important:67| Kind | Header | May do | Used as |8| --- | --- | --- | --- |9| **Procedure** | `fn name(…) { … }` | Everything an automation does: set controls, call actions, wait, ramp | A statement: `name(…)` |10| **Value function** | `fn name(…) -> type { … }` | Only compute | An expression: `let x = name(…)` |1112Functions are declared at the top level of the file, outside any automation, in any order.1314## Procedures1516```orixdj17fn fadeOut(d: deck, length: duration) {18 over length { d.volume -> -60dB }19 d.pause()20 d.volume = 0dB21}2223automation "Fade Out A" quantize bar {24 fadeOut(deck.A, 4 bars)25}26```2728- Every parameter has a name and a type: `d: deck`, `length: duration`.29- Inside the function, a parameter of type `deck` is used exactly like `deck.A`: `d.volume`, `d.play()`, `d.fx.echo.enable()`.30- The call must give one argument per parameter, of the right type.3132### A procedure runs in the caller's time3334Calling a procedure is like pasting its body at the place of the call. Its waits and ramps move the caller's cursor: the statement after the call runs when the procedure has finished.3536```orixdj37fn dip(d: deck) {38 over 2 beats { d.volume -> -12dB }39 over 2 beats { d.volume -> 0dB }40}4142automation "Two Dips" quantize bar {43 dip(deck.A) // takes one bar44 wait 1 bar45 dip(deck.A) // starts two bars in46}47```4849To run a procedure without waiting for it, call it from an `at` block. The block has its own cursor, so the main sequence carries on.5051```orixdj52fn fade(d: deck, level: gain, length: duration) {53 over length { d.volume -> level }54}5556automation "Crossing Fades" quantize bar {57 deck.B.volume = -60dB58 deck.B.sync(true)59 deck.B.play()60 at bar 1 { fade(deck.A, -60dB, 8 bars) } // both start now and run together61 at bar 1 { fade(deck.B, 0dB, 4 bars) }62 wait 8 bars63 deck.A.pause()64 deck.A.volume = 0dB65}66```6768### Leaving early6970`return` without a value leaves the procedure.7172```orixdj73fn startIfReady(d: deck) {74 if not d.loaded {75 print("nothing loaded")76 return77 }78 d.play()79}8081automation "Start C" {82 startIfReady(deck.C)83}84```8586`stop` inside a procedure stops the whole automation, not just the procedure.8788### What a procedure cannot contain8990- `on` handlers: they belong in an automation (`E-EVENT`).91- A procedure cannot be called inside an `over` block (`E-OVER`).9293`at bar N` inside a function counts from the start of the automation, not from the call; the compiler reminds you with the warning `W-AT`. Inside a function, prefer `wait` to position yourself.9495## Value functions9697A function with `-> type` computes a value and gives it back with `return`.9899```orixdj100fn barsToBeats(count: number) -> number {101 return count * 4102}103104fn quieter(level: gain, steps: number) -> gain {105 return max(level - 3dB * steps, -60dB)106}107108automation "Compute" {109 let total = barsToBeats(8)110 deck.A.volume = quieter(0dB, 2) // -6 dB111 print(total)112 wait 1 bar113 deck.A.volume = 0dB114}115```116117A value function is **pure**: its result depends only on its arguments. It may declare variables, use `if` and loops, and call builtins and other value functions. It may not:118119- wait, ramp or schedule (`wait`, `over`, `at`, `every`, `on`);120- set a control or call an action;121- read a live value such as `deck.A.bpm`: pass it as an argument instead;122- call `print`, `random()` or a procedure, or use `stop`.123124Each of these is the error `E-PURE`.125126```orixdj-error127fn halfTempo() -> number {128 return deck.A.bpm / 2129}130131automation "X" {132 print(halfTempo())133}134```135136```text137A function that returns a value cannot read live values such as 'deck.A.bpm'; pass them as arguments. [E-PURE]138```139140(For this script the compiler also reports `E-RETURN` on the function, because the rejected `return` statement no longer counts as one. Fixing the first problem removes both messages.)141142The corrected version reads the tempo in the automation and passes it in:143144```orixdj145fn half(x: number) -> number {146 return x / 2147}148149automation "Half Tempo" {150 print(half(deck.A.bpm))151}152```153154### Every path must return155156The compiler checks that a value function returns a value whatever happens. The last statement must be a `return`, or an `if`/`else` whose two branches both end with one.157158```orixdj-error159fn pick(x: number) -> number {160 if x > 1 {161 return x162 }163}164165automation "X" {166 print(pick(2))167}168```169170```text171Function 'pick' must return a number on every path. [E-RETURN]172```173174```orixdj175fn pick(x: number) -> number {176 if x > 1 {177 return x178 }179 return 1180}181182automation "Pick" {183 print(pick(2), pick(0))184}185```186187The returned value must have the declared type.188189## Parameters and arguments190191- Parameter types: `number`, `duration`, `gain`, `frequency`, `bool`, `string`, `deck`, or an array type such as `[gain]`.192- Arguments are checked strictly. The "plain number as a linear fader level" convenience applies only when assigning to a gain control, not to function arguments: pass `-6dB`, not `0.5`, to a `gain` parameter.193- A parameter cannot have the name of a reserved word (`E-SYNTAX`): write `d: deck`, not `deck: deck`.194- Parameters cannot be assigned inside the function. Copy one into a `var` if you need to change it.195- A function has its own variables. It cannot see the variables of the automation that calls it; it can see the file's top-level constants.196197```orixdj198let floorLevel = -60dB199200fn playPattern(d: deck, levels: [gain], stepLength: duration) {201 for level in levels {202 d.volume = max(level, floorLevel)203 wait stepLength204 }205 d.volume = 0dB206}207208automation "Pattern" quantize bar {209 playPattern(deck.A, [0dB, -60dB, -6dB, -60dB], 1/2beat)210}211```212213Wrong number or type of arguments:214215```orixdj-error216fn fadeOut(d: deck, length: duration) {217 over length { d.volume -> -60dB }218}219220automation "X" {221 fadeOut(deck.A)222}223```224225```text226'fadeOut' takes 2 arguments, not 1. [E-ARGS]227```228229## No recursion230231A function cannot call itself, directly or through other functions (`E-RECURSION`). This is one of the rules that guarantee an automation always ends. Use a loop instead.232233```orixdj-error234fn countdown(n: number) -> number {235 if n <= 0 { return 0 }236 return countdown(n - 1)237}238239automation "X" {240 print(countdown(3))241}242```243244```text245Function 'countdown' calls itself, directly or through other functions. Recursion is not allowed: automations must be bounded. [E-RECURSION]246```247248Calls can be nested at most 16 deep.249250## Names251252A function cannot have the name of another function, of a builtin (`min`, `max`, `clamp`, `abs`, `round`, `floor`, `ceil`, `lerp`, `random`, `len`, `db`, `hz`, `beats`, `bars`, `seconds`, `toBeats`, `toSeconds`, `toNumber`, `print`) or of a reserved word (`E-REDECLARED`).253254Calling a value function, or a builtin other than `print`, as a statement throws its result away; the compiler warns with `W-UNUSED`.255256## A small library257258Functions make a file of transitions readable. This one defines three building blocks and two automations that combine them.259260```orixdj261let silent = -60dB262263fn bringIn(d: deck, length: duration) {264 d.sync(true)265 d.volume = silent266 d.eq.low = -26dB267 d.play()268 over length { d.volume -> 0dB }269}270271fn swapBass(from: deck, to: deck) {272 from.eq.low = -26dB273 to.eq.low = 0dB274}275276fn takeOut(d: deck, length: duration) {277 over length { d.volume -> silent }278 d.pause()279 d.eq.low = 0dB280 d.volume = 0dB281}282283automation "A to B" quantize bar {284 bringIn(deck.B, 4 bars)285 swapBass(deck.A, deck.B)286 takeOut(deck.A, 4 bars)287}288289automation "A to C quick" quantize bar {290 bringIn(deck.C, 1 bar)291 swapBass(deck.A, deck.C)292 takeOut(deck.A, 1 bar)293}294```295296When the length of a procedure depends on an argument, as here, the total length of the automation is not known before it runs. That only affects what the scheduler display can show.297298## Related299300- [Variables](variables.md)301- [Types](types.md)302- [Timing](timing.md)303- [Loops](loops.md)304- [Presets](presets.md)305- [Error Handling](errors.md)306