Help/Language/Functions.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <title></title>
   7 <meta name="Generator" content="Cocoa HTML Writer">
   8 <meta name="CocoaVersion" content="949.43">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; color: #0000bf}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Monaco; min-height: 16.0px}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000}
  18 p.p9 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
  19 p.p10 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; color: #0000bf; min-height: 14.0px}
  20 span.s1 {color: #000000}
  21 span.s2 {text-decoration: underline}
  22 span.s3 {color: #0000bf}
  23 span.s4 {color: #0000bf}
  24 span.s5 {color: #007300}
  25 span.s6 {color: #bf0000}
  26 span.Apple-tab-span {white-space:pre}
  27 </style>
  28 </head>
  29 <body>
  30 <p class="p1"><b>Functions</b></p>
  31 <p class="p2"><br></p>
  32 <p class="p3"><span class="s1"><b>See also: </b><a href="../Core/Kernel/Function.html"><span class="s2">Function</span></a>, <a href="../Core/Kernel/AbstractFunction.html"><span class="s2">AbstractFunction</span></a>, <a href="../Core/Kernel/FunctionDef.html"><span class="s2">FunctionDef</span></a></span></p>
  33 <p class="p2"><br></p>
  34 <p class="p4">A <a href="../Core/Kernel/Function.html"><span class="s3">Function</span></a> is an expression which defines operations to be performed when it is sent the 'value' message. In functional languages, a function would be known as a lambda expression. Function definitions are enclosed in curly brackets {}. Argument declarations, if any, follow the open bracket. Variable declarations follow argument declarations. An expression follows the declarations.<span class="Apple-converted-space"> </span></p>
  35 <p class="p2"><br></p>
  36 <p class="p5">{ <span class="s4">arg</span> a, b, c;<span class="Apple-converted-space">  </span><span class="s4">var</span> d; <span class="Apple-converted-space">  </span>d = a * b; c + d }</p>
  37 <p class="p2"><br></p>
  38 <p class="p4">Functions are not evaluated immediately when they occur in code, but are passed as values just like integers or strings.</p>
  39 <p class="p2"><br></p>
  40 <p class="p4">A function may be evaluated by passing it the value message and a list of arguments.</p>
  41 <p class="p2"><br></p>
  42 <p class="p4">When evaluated, the function returns the value of its expression.</p>
  43 <p class="p2"><br></p>
  44 <p class="p5">f = { <span class="s4">arg</span> a, b; a + b };</p>
  45 <p class="p5">f.value(4, 5).postln;</p>
  46 <p class="p5">f.value(10, 200).postln;</p>
  47 <p class="p6"><br></p>
  48 <p class="p4">An empty function returns the value nil when evaluated.</p>
  49 <p class="p6"><br></p>
  50 <p class="p5">{}.value.postln;</p>
  51 <p class="p6"><br></p>
  52 <p class="p4">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).</p>
  53 <p class="p4">The following figure depicts an empty function, input without output, output without input, and the general case with input and output.<span class="Apple-converted-space"> </span></p>
  54 <p class="p2"><span class="Apple-converted-space"> </span></p>
  55 <p class="p4"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b><img src="attachments/Functions/functions.png" alt="attachments/Functions/functions.png"></p>
  56 <p class="p4"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>Functions</b></p>
  57 <p class="p6"><br></p>
  58 <p class="p7"><b>Arguments</b></p>
  59 <p class="p2"><br></p>
  60 <p class="p4">An argument list immediately follows the open curly bracket of a function definition. An argument list either begins with the reserved word <b>arg</b>, or is contained between two vertical bars. If a function takes no arguments, then the argument list may be omitted.<span class="Apple-converted-space"> </span></p>
  61 <p class="p2"><br></p>
  62 <p class="p4">Names of arguments in the list may be initialized to a default value by using an equals sign. Arguments which are not explicitly initialized will be set to nil if no value is passed for them.</p>
  63 <p class="p2"><br></p>
  64 <p class="p4">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 Array. Arguments must be separated by commas.</p>
  65 <p class="p2"><br></p>
  66 <p class="p4">examples:</p>
  67 <p class="p2"><br></p>
  68 <p class="p8"><span class="s4">arg</span><span class="s1"> a, b, c=3; </span>// is equivalent to:</p>
  69 <p class="p9"><br></p>
  70 <p class="p5">|a, b, c=3|</p>
  71 <p class="p9"><br></p>
  72 <p class="p8"><span class="s4">arg</span><span class="s1"> x=</span><span class="s5">'stop'</span><span class="s1">, y, z=0; </span>// these args are initialised</p>
  73 <p class="p9"><br></p>
  74 <p class="p8"><span class="s4">arg</span><span class="s1"> a, b, c ... d; </span>// any arguments after the first 3 will be assigned to d as an Array</p>
  75 <p class="p2"><br></p>
  76 <p class="p2"><br></p>
  77 <p class="p4">If you want all the arguments put in an Array</p>
  78 <p class="p2"><br></p>
  79 <p class="p5"><span class="s4">arg</span> ... z;</p>
  80 <p class="p6"><br></p>
  81 <p class="p4">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.</p>
  82 <p class="p2"><br></p>
  83 <p class="p8">// this is okay:</p>
  84 <p class="p9"><br></p>
  85 <p class="p5">{ <span class="s4">arg</span> a = <span class="s4">Array</span>.geom(4, 100, 3); a * 4 }.value;</p>
  86 <p class="p9"><br></p>
  87 <p class="p8">// this is not:</p>
  88 <p class="p9"><br></p>
  89 <p class="p5">{ <span class="s4">arg</span> freq = <span class="s4">Array</span>.geom(4, 100, 3); <span class="s4">Mix</span>(<span class="s4">SinOsc</span>.ar(freq, 0, 0.1)) }.play; <span class="s6">// silence</span></p>
  90 <p class="p9"><br></p>
  91 <p class="p8">// but this is:</p>
  92 <p class="p5">{ <span class="s4">arg</span> freq =<span class="Apple-converted-space">  </span>#[ 100, 300, 900, 2700 ]; <span class="s4">Mix</span>(<span class="s4">SinOsc</span>.ar(freq, 0, 0.1)) }.play; <span class="s6">// silence</span></p>
  93 <p class="p2"><br></p>
  94 <p class="p4">See <a href="Literals.html"><span class="s3">Literals</span></a> for more information.</p>
  95 <p class="p2"><br></p>
  96 <p class="p7"><b>Variables</b></p>
  97 <p class="p2"><br></p>
  98 <p class="p4">Following the argument declarations are the variable declarations. These may be declared in any order. Variable lists are preceeded by the reserved word <b>var</b>. 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.</p>
  99 <p class="p2"><br></p>
 100 <p class="p4">examples:</p>
 101 <p class="p2"><br></p>
 102 <p class="p5"><span class="s4">var</span> level=0, slope=1, curve=1;</p>
 103 <p class="p2"><br></p>
 104 <p class="p2"><br></p>
 105 <p class="p10"><br></p>
 106 </body>
 107 </html>