Help/Language/Method-Calls.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="824.42">
   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}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Monaco}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Monaco; color: #a71e12}
  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: 12.0px Monaco; color: #a71e12; min-height: 16.0px}
  17 span.s1 {font: 12.0px Helvetica}
  18 span.s2 {font: 12.0px Monaco}
  19 span.s3 {color: #000000}
  20 span.s4 {color: #0019b7}
  21 span.s5 {color: #316c17}
  22 span.Apple-tab-span {white-space:pre}
  23 </style>
  24 </head>
  25 <body>
  26 <p class="p1"><b>Messages</b><span class="s1"><span class="Apple-converted-space"> </span></span></p>
  27 <p class="p2"><br></p>
  28 <p class="p3">Sending messages is the way things get done in an object oriented language. A message consists of a message <b>selector</b> which names the type of operation, a <b>receiver</b> to which the message is sent and in some cases a list of <b>arguments</b> which give additional information pertaining to the operation. A message always</p>
  29 <p class="p3">returns a result. The kind of result depends on the kind of message. In the default case, the return value is the receiver itself.</p>
  30 <p class="p2"><br></p>
  31 <p class="p3">Messages may be written using binary operators, functional notation or receiver notation.<span class="Apple-converted-space"> </span></p>
  32 <p class="p2"><br></p>
  33 <p class="p3"><b>Binary operator messages</b></p>
  34 <p class="p2"><br></p>
  35 <p class="p3">A binary operator selector is any string of characters from the list of legal binary operator characters:</p>
  36 <p class="p2"><br></p>
  37 <p class="p4"><span class="s1"><span class="Apple-tab-span">    </span></span>! @ % &amp; * - + = | &lt; &gt; ? /</p>
  38 <p class="p2"><br></p>
  39 <p class="p3">An exception is that no operator may begin with <span class="s2">//</span> or <span class="s2">/*</span> which are comment delimiters.</p>
  40 <p class="p2"><br></p>
  41 <p class="p3">A binary operator expression consists of two expressions with a binary operator between them.<span class="Apple-converted-space"> </span></p>
  42 <p class="p2"><br></p>
  43 <p class="p5"><span class="s3"><span class="Apple-tab-span">    </span>1 + 2<span class="Apple-tab-span">       </span><span class="Apple-tab-span">    </span></span>// sum of one and two</p>
  44 <p class="p6"><br></p>
  45 <p class="p5"><span class="s3"><span class="Apple-tab-span">    </span>a - b<span class="Apple-tab-span">       </span><span class="Apple-tab-span">    </span></span>// difference of a and b</p>
  46 <p class="p6"><br></p>
  47 <p class="p5"><span class="s3"><span class="Apple-tab-span">    </span>x &lt; 0.0<span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></span>// answer whether x is less than zero</p>
  48 <p class="p7"><br></p>
  49 <p class="p3">A binary operator can also be an identifier followed by a colon.</p>
  50 <p class="p2"><br></p>
  51 <p class="p4"><span class="s1"><span class="Apple-tab-span">    </span></span>10 rrand: 100</p>
  52 <p class="p2"><span class="Apple-tab-span">     </span></p>
  53 <p class="p3"><b>Operator Precedence</b></p>
  54 <p class="p2"><br></p>
  55 <p class="p3">There is none. All binary operators have the same level of precedence and associate from left to right.<span class="Apple-converted-space"> </span></p>
  56 <p class="p3">For example, the expression:</p>
  57 <p class="p2"><br></p>
  58 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>a * b + c * d</p>
  59 <p class="p2"><br></p>
  60 <p class="p3"><span class="Apple-tab-span">     </span>is equivalent to:</p>
  61 <p class="p2"><br></p>
  62 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>((a * b) + c) * d</p>
  63 <p class="p2"><br></p>
  64 <p class="p3"><span class="Apple-tab-span">     </span>and not:</p>
  65 <p class="p2"><br></p>
  66 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>(a * b) + (c * d)</p>
  67 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  68 <p class="p3">Therefore it is usually better style to fully parenthesize your expressions.</p>
  69 <p class="p6"><br></p>
  70 <p class="p3"><b>Functional notation messages</b></p>
  71 <p class="p2"><br></p>
  72 <p class="p3">The message selector preceeds the parenthesized argument list. The first argument in the list is actually<span class="Apple-converted-space"> </span></p>
  73 <p class="p3">the receiver.</p>
  74 <p class="p2"><br></p>
  75 <p class="p5"><span class="s3"><span class="Apple-tab-span">    </span>sin(x)<span class="Apple-tab-span">      </span><span class="Apple-tab-span">    </span></span>// sine of x</p>
  76 <p class="p6"><span class="Apple-tab-span">     </span></p>
  77 <p class="p5"><span class="s3"><span class="Apple-tab-span">    </span>max(a, b)<span class="Apple-tab-span">   </span><span class="Apple-tab-span">    </span></span>// maximum of a and b</p>
  78 <p class="p6"><br></p>
  79 <p class="p6"><br></p>
  80 <p class="p3"><b>Receiver notation messages</b></p>
  81 <p class="p2"><br></p>
  82 <p class="p3">A method call in functional notation may be converted to receiver notation by putting the receiver before the method name followed by a dot as shown below.<span class="Apple-converted-space"> </span></p>
  83 <p class="p2"><br></p>
  84 <p class="p3"><span class="Apple-tab-span">     </span><span class="s2">max(a, b)</span><span class="Apple-converted-space">    </span>is equivalent to : <span class="Apple-converted-space">  </span><span class="s2">a.max(b)</span></p>
  85 <p class="p3"><span class="Apple-tab-span">     </span><span class="s2">sin(x)<span class="Apple-converted-space">  </span></span><span class="Apple-converted-space">  </span>is equivalent to : <span class="Apple-converted-space">  </span><span class="s2">x.sin</span></p>
  86 <p class="p2"><span class="Apple-tab-span">     </span></p>
  87 <p class="p3"><span class="Apple-tab-span">     </span>another example:</p>
  88 <p class="p2"><br></p>
  89 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>g(f(a, b), c)<span class="Apple-converted-space"> </span></p>
  90 <p class="p2"><br></p>
  91 <p class="p3"><span class="Apple-tab-span">     </span>is equivalent to :</p>
  92 <p class="p2"><br></p>
  93 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>g(a.f(b), c)</p>
  94 <p class="p2"><br></p>
  95 <p class="p3"><span class="Apple-tab-span">     </span>is equivalent to :</p>
  96 <p class="p2"><br></p>
  97 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>f(a, b).g(c)</p>
  98 <p class="p2"><br></p>
  99 <p class="p3"><span class="Apple-tab-span">     </span>is equivalent to :</p>
 100 <p class="p2"><br></p>
 101 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>a.f(b).g(c)</p>
 102 <p class="p2"><br></p>
 103 <p class="p2"><br></p>
 104 <p class="p3"><b>Default Argument Values</b></p>
 105 <p class="p2"><br></p>
 106 <p class="p3">You may call a function or method with more or fewer arguments than it was declared to accept. If fewer arguments are passed, those arguments not passed are set to a default value if one is given in the method or function definition, or otherwise to nil.<span class="Apple-converted-space">  </span>If too many arguments are passed, the excess arguments are either collected into an Array or ignored depending on whether or not the function or method has an ellipsis argument (explained in <b>Functions</b>). When calling a method or function with zero arguments you can omit the parentheses:</p>
 107 <p class="p2"><br></p>
 108 <p class="p5">// x is declared to take two arguments a and b which default to 1 and 2 respectively.</p>
 109 <p class="p5">// It returns their sum. This syntax will be explained in the section on Functions.</p>
 110 <p class="p4">x = { <span class="s4">arg</span> a=1, b=2; a + b };<span class="Apple-converted-space"> </span></p>
 111 <p class="p6"><br></p>
 112 <p class="p5"><span class="s3">z = x.value;<span class="Apple-converted-space">    <span class="Apple-tab-span">      </span><span class="Apple-tab-span">    </span></span></span>// z is set to 3. (a defaults to 1, b defaults to 2)</p>
 113 <p class="p6"><br></p>
 114 <p class="p5"><span class="s3">z = x.value(10);<span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span>// z is set to 12. (a is 10, b defaults to 2)</p>
 115 <p class="p6"><br></p>
 116 <p class="p5"><span class="s3">z = x.value(10, 5);<span class="Apple-tab-span"> </span></span>// z is set to 15. (a is 10, b is 5)</p>
 117 <p class="p6"><br></p>
 118 <p class="p5"><span class="s3">z = x.value(10, 5, 9);<span class="Apple-tab-span">      </span></span>// z is set to 15. (a is 10, b is 5, 9 is ignored)</p>
 119 <p class="p6"><br></p>
 120 <p class="p6"><br></p>
 121 <p class="p3"><b>Keyword Arguments</b></p>
 122 <p class="p2"><br></p>
 123 <p class="p3">Arguments to Methods may be specified by the name by which they are declared in a method's definition. Such arguments are called keyword arguments. Any argument may be passed as a keyword argument except for the receiver 'this'. Keyword arguments must come after any normal (aka 'positional') arguments, and may be specified in any order. If a keyword is specified and there is no matching argument then it is ignored and a warning will be printed. This warning may be turned off globally by making the following call:<span class="Apple-converted-space"> </span></p>
 124 <p class="p6"><br></p>
 125 <p class="p4">keywordWarnings(false)</p>
 126 <p class="p2"><br></p>
 127 <p class="p3">If a keyword argument and a positional argument specify the same argument, then the keyword argument value overrides the positional argument value.</p>
 128 <p class="p2"><br></p>
 129 <p class="p3">For example the 'ar' class method of the SinOsc class takes arguments named <b>freq</b>, <b>phase</b>, <b>mul</b>, and <b>add</b> in that order. All of the following are legal calls to that method.</p>
 130 <p class="p6"><br></p>
 131 <p class="p5"><span class="s4">SinOsc</span><span class="s3">.ar(800, pi, 0.2, 0); </span>// all normal arguments: freq, phase, mul, add</p>
 132 <p class="p6"><br></p>
 133 <p class="p5">// freq = 800, mul = 0.2, others get default values.</p>
 134 <p class="p4"><span class="s4">SinOsc</span>.ar(800, mul: 0.2);<span class="Apple-converted-space"> </span></p>
 135 <p class="p6"><br></p>
 136 <p class="p5">// freq = 800, phase = pi, mul = 0.2, add gets its default value of zero.</p>
 137 <p class="p4"><span class="s4">SinOsc</span>.ar(phase: pi, mul: 0.2, freq: 800);</p>
 138 <p class="p6"><br></p>
 139 <p class="p5">// keyword value of 1200 overrides the positional arg value of 800</p>
 140 <p class="p4"><span class="s4">SinOsc</span>.ar(800, freq: 1200);<span class="Apple-converted-space"> </span></p>
 141 <p class="p6"><br></p>
 142 <p class="p5"><span class="s4">SinOsc</span><span class="s3">.ar(zorg: 999); </span>// invalid keyword prints warning</p>
 143 <p class="p2"><br></p>
 144 <p class="p3">The arguments to a Function may also be specified by keyword arguments when using the 'value' message.<span class="Apple-converted-space"> </span></p>
 145 <p class="p2"><br></p>
 146 <p class="p5">// function args may be specified by keyword.</p>
 147 <p class="p4">{ <span class="s4">arg</span> a=1, b=2, c=3; [a, b, c].postln }.value(b: 7, c: 8);</p>
 148 <p class="p6"><br></p>
 149 <p class="p3">You may also use keyword arguments when using the 'perform' method.</p>
 150 <p class="p6"><br></p>
 151 <p class="p4"><span class="s4">SinOsc</span>.perform(<span class="s5">'ar'</span>, phase: pi, mul: 0.2, freq: 800);</p>
 152 <p class="p6"><br></p>
 153 <p class="p3"><b>Cost of using keyword arguments</b></p>
 154 <p class="p6"><br></p>
 155 <p class="p3">When using keyword arguments there is a runtime cost to do the matching that you should be aware of. The cost can be worth the convenience when speed is not critical.</p>
 156 </body>
 157 </html>