HelpSource/Reference/Literals.schelp

   1 title:: Literals
   2 summary:: values with a direct syntactic representation
   3 related:: Classes/Number, Classes/Integer, Classes/Float, Classes/SimpleNumber, Classes/String, Classes/Array, Classes/Symbol
   4 categories:: Language
   5
   6 Literals are values which have a direct syntactic representation.
   7 The following sections describe the types of literals that can be represented.
   8
   9 section::Numbers
  10
  11 subsection::Integers
  12 An integer is any series of digits optionally preceded by a minus sign:
  13 code::
  14 -13
  15 666
  16 2112
  17 96
  18 ::
  19
  20 subsection::Floats
  21 A float is one or more decimal digits followed by a decimal point followed by one or more decimal digits.
  22 You must have digits on both sides of the decimal point.  This distinguishes floating point numbers from
  23 integer expressions like code::8.rand::.
  24
  25 Examples of floats:
  26 code::
  27 0.39
  28 98.6
  29 1.0
  30 -0.5
  31 ::
  32
  33 Exponential notation is also supported:
  34 code::
  35 1.2e4
  36 1e-4
  37 ::
  38
  39 The constant pi can be appended to a number to create a floating point constant:
  40 code::
  41 pi
  42 2pi
  43 0.5pi
  44 -0.25pi
  45 ::
  46
  47 subsection::Radix
  48 Numbers can also be written in radices other than base 10 up to base 36.
  49 The radix is specified in base 10 followed by the letter 'r' followed by the value written in
  50 that radix using characters 0-9,A-Z, or a-z, for digit values from 0 to 35.
  51 For example you can write hexidecimal numbers as follows:
  52 code::
  53 16rF0
  54 16rA9FF
  55 ::
  56 Binary numbers can be written as follows:
  57 code::
  58 2r01101011
  59 ::
  60
  61 Floating point values may also be specified in any base:
  62 code::
  63 12r4A.A
  64 ::
  65
  66 section::Characters
  67
  68 Characters are preceded by a dollar sign:
  69 code::
  70 $A
  71 $B
  72 $C
  73 ::
  74
  75 Tab, linefeed, carriage return, and backslash are preceded by a backslash:
  76 code::
  77 $\t
  78 $\n
  79 $\r
  80 $\\
  81 ::
  82
  83 section::Symbols
  84
  85 A symbol is written as a string enclosed in single quotes.
  86 examples of symbols:
  87 code::
  88 'x'
  89 'aiff'
  90 'BigSwiftyAndAssoc'
  91 'nowhere here'
  92 'somewhere there'
  93 '.+o*o+.'
  94 ::
  95
  96 A symbol consisting of a single word can be written with a preceeding backslash.
  97 code::
  98 \x
  99 \aiff
 100 \BigSwiftyAndAssoc
 101 ::
 102
 103 section::Strings
 104
 105 Strings are written in double quotes:
 106 code::
 107 "This is a string."
 108 ::
 109
 110 If two or more strings are lexically adjacent, then they combine into a larger string:
 111 code::
 112 "This" " is " "also a " "string."
 113 ::
 114
 115 Strings may span more than one line. If so, then the new line characters become part of the string:
 116 code::
 117 "This
 118 is
 119 also a
 120 string.
 121 "
 122 ::
 123
 124 section::Identifiers
 125
 126 Names of methods and variables begin with a lower case alphabetic character, followed by zero or more
 127 alphanumeric characters:
 128 code::
 129 var abc, z123, func;
 130 ::
 131
 132 section::Class Names
 133
 134 Class names always begin with a capital letter followed by zero or more alphanumeric characters.
 135 code::
 136 Object
 137 Point
 138 Synth
 139 SinOsc
 140 Pan2
 141 ::
 142
 143 section::Special Values
 144
 145 The singular instances of the classes True, False and Nil are written as the
 146 words true, false, nil and inf.
 147 code::
 148 x = true;
 149 y = false;
 150 z = nil;
 151 ::
 152
 153 section::Arrays
 154
 155 link::Classes/Array::s of literals are created at compile time and are written with a # preceeding the array as follows:
 156 code::
 157 #[1, 2, 'abc', "def", 4]
 158 ::
 159 Literal Arrays must be used as is and may not be altered at run time.
 160
 161 In literal Arrays names are interpreted as symbols. This is not the case in regular Arrays, where they are interpreted as variable names:
 162 code::
 163 #[foo, bar]     // this is legal; an Array of Symbols
 164 [foo, bar]      // this is only legal if foo and bar have been declared as variables
 165 ::
 166 Arrays and other collections may also be created dynamically which is explained in link::Classes/Collection::.
 167 Using a literal Array is faster than building an array dynamically every time you need it.
 168
 169 When nesting literal arrays, only the outermost literal array needs the '#' character.
 170 code::
 171 #[[1, 2, 3], [4, 5, 6]]
 172 ::
 173
 174 Literal Arrays can be useful for things such as tables of constants, for example note names:
 175 code::
 176 (
 177 // build a table of note names
 178 var table = ();
 179 value {
 180     var semitones = [0, 2, 4, 5, 7, 9, 11];
 181     var naturalNoteNames = ["c", "d", "e", "f", "g", "a", "b"];
 182
 183     (0..9).do {|o|
 184         naturalNoteNames.do {|c, i|
 185             var n = (o + 1) * 12 + semitones[i];
 186             table[(c ++ o).asSymbol] = n;
 187             table[(c ++ "s"  ++ o).asSymbol] = n + 1;
 188             table[(c ++ "ss" ++ o).asSymbol] = n + 2;
 189             table[(c ++ "b"  ++ o).asSymbol] = n - 1;
 190             table[(c ++ "bb" ++ o).asSymbol] = n - 2;
 191         };
 192     };
 193 };
 194
 195 // translate note names to midi keys
 196 table.atAll(#[c4, e4, gs4, c5, e5, gs5, c6])
 197 )
 198 ::
 199
 200 section:: Compiler limits
 201
 202 There is no theoretical limit on the number of literals in a single function, if those literals are used as freestanding objects. (Of course, there remains the practical limits of system memory and the processor time required to keep track of all the objects.)
 203
 204 The following are a special category of literal, called emphasis::selectors::.
 205
 206 list::
 207 ## Class names
 208 ## Method names
 209 ## Function definitions (enclosed in curly braces code::{  }::)
 210 ::
 211
 212 Here, there are four selectors: code::SinOsc::, code::ar::, code::play:: and the entire function containing SinOsc.
 213
 214 code::{ SinOsc.ar(440, 0, 0.1) }.play;::
 215
 216 A single function may contain no more than 256 selectors. If this limit is exceeded, a compiler error is printed:
 217
 218 teletype::ERROR: Selector table too big: too many classes, method selectors or function definitions in this function. Simplify the function.::
 219
 220 note::
 221 Code submitted for interactive execution is first compiled into a function. A very large block of code, spanning several thousand lines, may run into this limitation if it doesn't break down the tasks into smaller functions. In general, code is easier to maintain if it is reasonably emphasis::modular::, with small functions handling clearly-defined parts of the problem. This error message is a signal that the code has become too complex for a loose or "flat" code structure.
 222 ::
 223
 224 subsection:: What counts as "inside the function"?
 225
 226 Selectors are counted only toward the function definition currently being compiled.
 227
 228 code::
 229 { x.foo };
 230
 231 { x.bar };
 232 ::
 233
 234 Both functions contain exactly one selector. They are separate functions. The use of "foo" in one function doesn't affect the number of selectors in another function.
 235
 236 code::
 237 {
 238         var f = { |n|
 239                 if(n > 1) { n * f.value(n-1) } { 1 }
 240         };
 241
 242         f.value(10);
 243 }.value;
 244 ::
 245
 246 The outer function includes only the selector code::value::. The other selectors -- code::>::, code::*::, code::-:: -- belong to the inner function definition and don't affect the outer function's number of selectors.
 247
 248 So, one possible easy way to work around the limitation is to break up a large block of code into several functions that are value'd successively:
 249
 250 code::
 251 {
 252         ... a bunch of code ...
 253 }.value;
 254
 255 {
 256         ... a bunch of code ...
 257 }.value;
 258
 259 {
 260         ... a bunch of code ...
 261 }.value;
 262 ::