HelpSource/Reference/Functions.schelp

   1 title:: Functions
   2 summary:: lambda expressions
   3 categories:: Language
   4 related:: Classes/Function, Classes/AbstractFunction, Classes/FunctionDef
   5
   6 section:: Introduction
   7
   8 A link::Classes/Function:: is an expression which defines operations to be performed when it is sent the code::value:: message. In functional languages, a function would be known as a lambda expression.
   9 Function definitions are enclosed in curly brackets code::{}::. Argument declarations, if any, follow the open bracket. Variable declarations follow argument declarations. An expression follows the declarations.
  10 code::
  11 { arg a, b, c;  var d;   d = a * b; c + d }
  12 ::
  13
  14 Functions are not evaluated immediately when they occur in code, but are passed as values just like integers or strings.
  15
  16 A function may be evaluated by passing it the code::value:: message and a list of arguments.
  17
  18 When evaluated, the function returns the value of its expression.
  19 code::
  20 f = { arg a, b; a + b };
  21 f.value(4, 5).postln;
  22 f.value(10, 200).postln;
  23 ::
  24
  25 An empty function returns the value nil when evaluated.
  26 code::
  27 {}.value.postln;
  28 ::
  29
  30 A function can be thought as a machine able to perform a task on demand, e.g. a calculator. The calculator can receive input (args) and can output a value, the result of the performed operations. The function definition can then be thought as the building of the calculator: once built, the calculator does nothing until it is requested to work (by passing the value method to a function).
  31 The following figure depicts an empty function, input without output, output without input, and the general case with input and output.
  32
  33 image::functions.png#Functions::
  34
  35 section:: Arguments
  36
  37 An argument list immediately follows the open curly bracket of a function definition. An argument list either begins with the reserved word code::arg::, or is contained between two vertical bars. If a function takes no arguments, then the argument list may be omitted.
  38
  39 Names of arguments in the list may be initialized to a default value using the following syntax forms. Arguments which are not explicitly initialized will be set to nil if no value is passed for them.
  40
  41 "arg" style, default value is a literal:
  42 code::{ arg x = 1; .... } :: link::#[1]::
  43
  44 "arg" style, default value is an expression:
  45 code::{ arg x = 10.rand; ... } :: link::#[2]::
  46
  47 "arg" style, default value is a literal but you want to treat it like an expression:
  48 code::{ arg x = (2); ... } :: link::#[2]::
  49
  50 Pipe style, default value is a literal:
  51 code::{ |x = 1| ... } :: link::#[1]::
  52
  53 Pipe style, default value is an expression:
  54 code::{ |x = (10.rand)| ... } :: link::#[2]::
  55
  56 If the last argument in the list is preceeded by three dots (an ellipsis), then all the remaining arguments that were passed will be assigned to that variable as an link::Classes/Array::. Arguments must be separated by commas.
  57
  58 examples:
  59 code::
  60 { arg a, b, c=3; } // is equivalent to:
  61
  62 { |a, b, c=3| }
  63
  64 { arg x='stop', y, z=0; } // these args are initialised
  65
  66 { arg a, b, c ... d; } // any arguments after the first 3 will be assigned to d as an Array
  67 ::
  68
  69 If you want all the arguments put in an Array
  70 code::
  71 arg ... z;
  72 ::
  73
  74 In general arguments may be initialized to literals or expressions, but in the case of Function:play or SynthDef:play, they may only be initialized to literals.
  75 code::
  76 // this is okay:
  77
  78 { arg a = Array.geom(4, 100, 3); a * 4 }.value;
  79
  80 // this is not:
  81
  82 { arg freq = Array.geom(4, 100, 3); Mix(SinOsc.ar(freq, 0, 0.1)) }.play; // silence
  83
  84 // but this is:
  85 { arg freq =  #[ 100, 300, 900, 2700 ]; Mix(SinOsc.ar(freq, 0, 0.1)) }.play; // silence
  86 ::
  87
  88 See link::Reference/Literals:: for more information.
  89
  90 anchor::[1]::
  91 subsection:: [1] Literal argument defaults
  92
  93 Argument defaults that are literals are stored as part of the link::Classes/FunctionDef::. Arguments passed at runtime -- including nil -- always override the defaults:
  94
  95 code::
  96 f = { arg x = 1; x };
  97 f.value(2);  // prints 2
  98
  99 f.value;   // prints 1
 100
 101 f.value(nil);  // prints nil
 102 ::
 103
 104 anchor::[2]::
 105 subsection:: [2] Expression argument defaults
 106
 107 Since expressions are evaluated when the function is called, they cannot be stored in the link::Classes/FunctionDef::. They are executed only if the passed-in value is nil.
 108
 109 code::
 110 f = { arg x = 10.rand; x };
 111 f.value(100);  // prints 100
 112
 113 f.value;   // prints a number 0-9
 114
 115 f.value(nil);   // prints a number 0-9!
 116 ::
 117
 118 This means you can use expression-style to define a default that cannot be overridden by nil.
 119
 120 code::
 121 f = { arg x = (3); x };
 122 f.value(nil);   // prints 3
 123 ::
 124
 125 Note: Parentheses are required when initializing an argument to an expression, if the argument list is written inside code::||:: pipes.
 126
 127 code::
 128 (
 129 var abc = 2;
 130 { arg x = abc+1; x }   // OK
 131 )
 132
 133 (
 134 var abc = 2;
 135 { |x = abc+1| x }
 136 )
 137 ERROR: Parse error
 138    in file 'selected text'
 139    line 1 char 10:
 140   { |x = abc•+1| x }
 141 -----------------------------------
 142 ERROR: Command line parse failed
 143
 144 (
 145 var abc = 2;
 146 { |x = (abc+1)| x }   // OK
 147 )
 148
 149 (
 150 var abc = 2;
 151 { |x (abc+1)| x }   // In ||, the = may be omitted if () are there
 152 )
 153 ::
 154
 155 This is because the pipe character also serves as a binary operator. Without parentheses, expressions such as the following are ambiguous:
 156
 157 code::
 158 { |a, b, c = a | b | c }
 159 ::
 160
 161 The following produce identical function definitions. Expression-style defaults are simply a shortcut syntax for the latter.
 162
 163 code::
 164 { arg x = 10.rand; x };
 165
 166 {       arg x;
 167         x ?? { x = 10.rand };
 168         x
 169 };
 170 ::
 171
 172 section:: Variables
 173
 174 Following the argument declarations are the variable declarations. These may be declared in any order. Variable lists are preceeded by the reserved word code::var::. There can be multiple var declaration lists if necessary. Variables may be initialized to default values in the same way as arguments. Variable declarations lists may not contain an ellipsis.
 175
 176 code::
 177 var level=0, slope=1, curve=1;
 178 ::
 179