HelpSource/Classes/Environment.schelp

   1 CLASS::Environment
   2 related::Classes/Event, Classes/IdentityDictionary
   3 categories::Collections>Unordered
   4 summary:: A dictionary which can serve as a 'name space' for functions
   5
   6 DESCRIPTION::
   7 An Environment is an IdentityDictionary with additional features that allow it to serve as a 'name space' within which functions can be defined and/or evaluated.
   8
   9 CLASSMETHODS::
  10 method::stack
  11 Maintains a stack of Environments accessed by link::#*push:: and link::#*pop::.
  12
  13 method::make
  14 Creates a new Environment and sends make message.
  15
  16 method::use
  17 Creates a new Environment and sends use message.
  18
  19 method::push
  20 Saves link::#.currentEnvironment:: on the stack.
  21
  22 method::pop
  23 Restores link::#.currentEnvironment:: from the stack.
  24
  25 INSTANCEMETHODS::
  26
  27 method::make
  28 Evaluates the function within the environment, returns the environment.
  29
  30 method::use
  31 Evaluates the function within the environment, returns the return value of the function.
  32
  33 method::push
  34 Saves the receiver on the stack.
  35
  36 method::pop
  37 Restores link::#.currentEnvironment:: from the stack.
  38
  39
  40 SECTION::PseudoVariables (global variables)
  41 These are not methods, but global variables.
  42 method:: currentEnvironment
  43 determines environment used by "~" syntax, link::#.valueEnvir::, and link::#.valueArrayEnvir::
  44
  45 method:: topEnvironment
  46 initial value of link::#.currentEnvironment::, can be used for 'global variables'
  47
  48 SECTION::Related Messages
  49
  50 method:: valueEnvir (arg1, arg2...)
  51 evaluates a function, looking up unspecified arguments in link::#.currentEnvironment::
  52
  53 method:: valueArrayEnvir (argArray)
  54 same as link::#.valueEnvir::, but with arguments in an array
  55
  56
  57 SECTION::Overview
  58
  59 subsection::topEnvironment, currentEnvironment, make and use
  60
  61 When SuperCollider starts, it creates an Environment that it stores in the pseudovariables link::#.topEnvironment:: and link::#.currentEnvironment::. The link::#.topEnvironment:: provides a universally accessible collection of named values similar to the link::Classes/Interpreter:: variables a, b, c, ....
  62
  63 The compiler provides a shortcut syntax where ~ is a placeholder for link::#.currentEnvironment::.
  64 This makes the expression code::~myvariable;:: equivalent to code::currentEnvironment.at(\myvariable);:: and the expression code::~myvariable = 888;:: equivalent to code::currentEnvironment.put(\myvariable, 888);::
  65
  66 The messages link::#*make::(function) and link::#*use::(function) replace link::#.currentEnvironment:: with the receiver. The message link::#*make:: is intended to be used when initializing an Environment, so it returns the Environment. The message link::#*use:: is for evaluating a functions within an Environment, so it returns the return value of the function.
  67
  68 For example
  69 code::
  70 (
  71 a = Environment.make({
  72         ~a = 100;
  73         ~b = 200;
  74         ~c = 300;
  75 });
  76 a.postln;
  77 )
  78 ::
  79 creates an environment, while
  80 code::
  81 a.use({
  82         ~a + ~b + ~c
  83 }).postln;
  84 ::
  85 evaluates the function within that environment.
  86
  87 subsection::valueEnvir and valueArrayEnvir
  88
  89 When Functions are evaluated with link::#.valueEnvir:: and link::#.valueArrayEnvir:: unspecified arguments are looked up in the current Environment.
  90 If the argument is not found in the Environment its default value is used.
  91 code::
  92 (
  93 var f;
  94
  95 // define a function
  96 f = { arg x, y, z; [x, y, z].postln; };
  97
  98 Environment.use({
  99         ~x = 7;
 100         ~y = 8;
 101         ~z = 9;
 102
 103         f.valueEnvir(1, 2, 3);  // all values supplied
 104         f.valueEnvir(1, 2);     // z is looked up in the current Environment
 105         f.valueEnvir(1);        // y and z are looked up in the current Environment
 106         f.valueEnvir;           // all arguments are looked up in the current Environment
 107         f.valueEnvir(z: 1);     // x and y are looked up in the current Environment
 108 });
 109 )
 110 ::
 111 Now here is how this can be used with an instrument function. Environments allow you to define instruments without having to worry about argument ordering conflicts. Even though the three functions below have the freq, amp and pan args declared in different orders it does not matter, because link::#.valueEnvir:: looks them up in the environment.
 112 code::
 113 s.boot;
 114
 115 (
 116 var orc;
 117 orc = Environment.make {
 118         ~a = { arg freq, amp, pan;
 119                 Pan2.ar(SinOsc.ar(freq), pan, amp);
 120         };
 121         ~b = { arg amp, pan, freq;
 122                 Pan2.ar(RLPF.ar(Saw.ar(freq), freq * 6, 0.1), pan, amp);
 123         };
 124         ~c = { arg pan, freq, amp;
 125                 Pan2.ar(Resonz.ar(GrayNoise.ar, freq * 2, 0.1), pan, amp * 2);
 126         };
 127         ~orc = [~a, ~b, ~c];
 128 };
 129 // 'reverb'
 130 { var in; in = In.ar(0, 2); CombN.ar(in, 0.2, 0.2, 3, 1, in); }.play(addAction: \addToTail);
 131
 132 { loop({
 133         orc.use({
 134                         // set values in the environment
 135                 ~freq = exprand(80, 600);
 136                 ~amp = 0.1;
 137                 ~pan = 1.0.rand2;
 138
 139                         // call a randomly chosen instrument function
 140                         // with values from the environment
 141
 142                  x = { ~orc.choose.valueEnvir; }.play(fadeTime: 0.2, addAction: \addToHead);
 143                  0.2.wait;
 144                  x.release(0.2);
 145         });
 146 }) }.fork;
 147
 148 )
 149 ::
 150
 151 subsection::Environments and asynchronous functions
 152
 153 Local variables declared in functions, and class and instance variables, use lexical scope. That is, the context in which they are understood depends on where the declaration is read during compilation. Asynchronous functions -- any function that will execute outside (later than) the current execution flow -- carry their lexically scoped variables with them.
 154 code::
 155 f = { var a = "got it"; { a.postln }.defer(0.5) };
 156 f.value;
 157 ::
 158 Asynchronous functions include any scheduled function, responder function associated with OSCFunc, MIDIFunc, HID or GUI action functions, or actions used in server messaging (such as Buffer.read, Buffer or Bus .get, and so on).
 159
 160 Environment variables have dynamic scope; they are read from whichever environment is current, whether or not it was the current environment when the function was declared. For instance, the following fails because e is no longer the current environment when the deferred function wakes up.
 161 code::
 162 e = (a: "got it", f: { { ~a.postln }.defer(0.5) });
 163 e.use { e.f };
 164 ::
 165 link::Classes/Function#inEnvir#Function's inEnvir:: method attaches a function to a specific environment. If no environment is given, the current environment at the time of executing inEnvir is the default.
 166 code::
 167 e = (a: "got it", f: { { ~a.postln }.inEnvir.defer(0.5) });
 168 e.use { e.f };
 169 ::
 170
 171 subsection::Using Environments as object prototypes
 172
 173 Environment's strong::know:: variable holds a link::Classes/Boolean:: value controlling whether the Environment may be used as an object prototype or not. If strong::know:: is true, any messages sent to the Environment that it does not already understand will be relayed into items in the Environment. (If false, not-understood messages will produce a standard "does not understand" error message.)
 174
 175 The default for know is false for Environment, and true for link::Classes/Event::.
 176 code::
 177 e = Environment[
 178         'someVariable' -> 5,
 179         'printMe' -> { |self, string| string.postln }
 180 ];
 181
 182 e.know = true;
 183 ::
 184 More typically, Events are used to define such prototypes because the syntax is simpler.
 185 code::
 186 e = (someVariable: 5, printMe: { |self, string| string.postln });
 187 ::
 188
 189
 190 An object prototype looks up the method selector in the Environment to decide what to do.
 191
 192 Most objects are simply returned -- the method call behaves like a getter for any other object.
 193 code::
 194 e.someVariable;
 195 // same as
 196 e.at('someVariable');
 197 e['someVariable'];
 198 ::
 199 If the selector is a setter, e.g. strong::someVariable_(value):: or strong::someVariable = value::, the new value is put into the Environment.
 200 code::
 201 e.someVariable = 10;
 202 // same as
 203 e.put('someVariable', 10);
 204 ::
 205 If the Environment item is a function, it is evaluated as if it were a method definition. The first argument passed into the function is the Environment that holds the function; arguments to the method call follow as the second, third etc. arguments passed into the function.
 206 code::
 207 e.printMe("Oh hai wrldz");
 208 // same as
 209 e['printMe'].value(e, "Oh hai wrldz");
 210 ::
 211 The function may access objects in the Environment using the first function argument.
 212 code::
 213 e.mul2 = { |z| z.someVariable * 2 };
 214 e.mul2;
 215 ::
 216 Environment variables inside a function will refer to the currently active environment -- not to the Environment being addressed. This is to allow the object prototype to interact with the link::#.currentEnvironment::.
 217 code::
 218 e.mul2 = { |z| ~someVariable * 2 };
 219 // this will throw an error because ~someVariable is nil in the currentEnvironment
 220 e.mul2;
 221 ::
 222 If you wish to access objects in the environment using environment variable syntax, 'use' the environment within the function.
 223 code::
 224 e.mul2 = { |z| z.use { ~someVariable * 2 } };
 225 e.mul2;
 226 ::
 227
 228 note::
 229 Be careful to avoid method names that are defined in any of the superclasses of environment (or event). Object prototyping works by trapping method selectors that are not already defined as class library methods. Using a generic method selector such as 'stop' or 'reset' will cause the corresponding class library method to respond, and the items in the environment will never be checked.
 230
 231 Assigning a value into an environment using a setter -- strong::name_():: or strong::.name = ...:: -- posts a warning message if the name is already defined in the class library.
 232 code::
 233 e.reset = { "My reset function".postln };
 234
 235 // prints:
 236 WARNING:
 237 'reset' exists a method name, so you can't use it as pseudo-method.
 238
 239 // this does NOT execute the reset function above
 240 // because Object:reset responds
 241 e.reset;
 242 ::
 243 ::