HelpSource/Reference/Messages.schelp

   1 title:: Messages
   2 summary:: Method calls, sending messages to objects
   3 categories:: Language>OOP
   4 related:: Reference/Classes, Classes/Class, Classes/Object, Guides/Intro-to-Objects, Guides/Polymorphism
   5
   6 section:: Introduction
   7
   8 Sending messages is the way things get done in an object oriented language. A message consists of a message selector which names the type of operation, a receiver to which the message is sent and in some cases a list of arguments which give additional information pertaining to the operation.
   9 A message always returns a result. The kind of result depends on the kind of message. In the default case, the return value is the receiver itself.
  10
  11 Messages may be written using binary operators, functional notation or receiver notation.
  12
  13 section:: Binary operator messages
  14
  15 A binary operator selector is any string of characters from the list of legal binary operator characters:
  16 code::
  17 ! @ % & * - + = | < > ? /
  18 ::
  19
  20 An exception is that no operator may begin with code:://:: or code::/*:: which are comment delimiters.
  21
  22 A binary operator expression consists of two expressions with a binary operator between them.
  23 code::
  24 1 + 2           // sum of one and two
  25 a - b           // difference of a and b
  26 x < 0.0         // answer whether x is less than zero
  27 ::
  28
  29 A binary operator can also be an identifier followed by a colon.
  30 code::
  31 10 rrand: 100
  32 ::
  33
  34 section:: Operator Precedence
  35
  36 There is none. All binary operators have the same level of precedence and associate from left to right.
  37 For example, the expression:
  38 code::
  39 a * b + c * d
  40 ::
  41 is equivalent to:
  42 code::
  43 ((a * b) + c) * d
  44 ::
  45 and not:
  46 code::
  47 (a * b) + (c * d)
  48 ::
  49 Therefore it is usually better style to fully parenthesize your expressions.
  50
  51 section:: Functional notation messages
  52
  53 The message selector preceeds the parenthesized argument list. The first argument in the list is actually
  54 the receiver.
  55 code::
  56 sin(x)      // sine of x
  57 max(a, b)   // maximum of a and b
  58 ::
  59
  60 section:: Receiver notation messages
  61
  62 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.
  63 code::
  64 max(a, b)
  65
  66 // is equivalent to:
  67
  68 a.max(b)
  69
  70 // and
  71
  72 sin(x)
  73
  74 // is equivalent to:
  75
  76 x.sin
  77 ::
  78
  79 another example:
  80 code::
  81 g(f(a, b), c)
  82
  83 // is equivalent to:
  84
  85 g(a.f(b), c)
  86
  87 // is equivalent to:
  88
  89 f(a, b).g(c)
  90
  91 // is equivalent to:
  92
  93 a.f(b).g(c)
  94 ::
  95
  96 section:: Default Argument Values
  97
  98 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.
  99 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 link::Reference/Functions::).
 100 When calling a method or function with zero arguments you can omit the parentheses:
 101 code::
 102 // x is declared to take two arguments a and b which default to 1 and 2 respectively.
 103 // It returns their sum. This syntax will be explained in the section on Functions.
 104 x = { arg a=1, b=2; a + b };
 105
 106 z = x.value;            // z is set to 3. (a defaults to 1, b defaults to 2)
 107 z = x.value(10);        // z is set to 12. (a is 10, b defaults to 2)
 108 z = x.value(10, 5);     // z is set to 15. (a is 10, b is 5)
 109 z = x.value(10, 5, 9);  // z is set to 15. (a is 10, b is 5, 9 is ignored)
 110 ::
 111
 112 section:: Keyword Arguments
 113
 114 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.
 115 Any argument may be passed as a keyword argument except for the receiver code::this::.
 116 Keyword arguments must come after any normal (aka emphasis::positional::) arguments, and may be specified in any order.
 117 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:
 118 code::
 119 keywordWarnings(false)
 120 ::
 121 If a keyword argument and a positional argument specify the same argument, then the keyword argument value overrides the positional argument value.
 122
 123 For example the code::ar:: class method of the SinOsc class takes arguments named freq, phase, mul, and add in that order. All of the following are legal calls to that method.
 124 code::
 125 SinOsc.ar(800, pi, 0.2, 0); // all normal arguments: freq, phase, mul, add
 126
 127 // freq = 800, mul = 0.2, others get default values.
 128 SinOsc.ar(800, mul: 0.2);
 129
 130 // freq = 800, phase = pi, mul = 0.2, add gets its default value of zero.
 131 SinOsc.ar(phase: pi, mul: 0.2, freq: 800);
 132
 133 // keyword value of 1200 overrides the positional arg value of 800
 134 SinOsc.ar(800, freq: 1200);
 135 ::
 136 code::
 137 SinOsc.ar(zorg: 999); // invalid keyword prints warning
 138 ::
 139 The arguments to a Function may also be specified by keyword arguments when using the 'value' message.
 140 code::
 141 // function args may be specified by keyword.
 142 { arg a=1, b=2, c=3; [a, b, c].postln }.value(b: 7, c: 8);
 143 ::
 144 You may also use keyword arguments when using the 'perform' method.
 145 code::
 146 SinOsc.perform('ar', phase: pi, mul: 0.2, freq: 800);
 147 ::
 148 subsection:: Cost of using keyword arguments
 149
 150 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.
 151