HelpSource/Classes/FunctionList.schelp

   1 class::FunctionList
   2 summary:: A function that composes multiple functions into one
   3 categories::Core>Kernel
   4
   5 description::
   6
   7 A FunctionList is a function that composes multiple functions into one. This allows allow to deal transparently with several functions as if they were one and to append new functions at a later point. The functions are evaluated in the order they have in the FunctionList's array, which is by default the order in which they have been added to it.
   8
   9 See the link::Reference/Functions:: help file for a basic introduction.
  10
  11 classMethods::
  12
  13 method::new
  14
  15 create a new instance.
  16 argument:: functions
  17 An array of functions or objects
  18
  19 instanceMethods::
  20
  21 method::array
  22
  23 Set/get the FunctionList's array. New functions can be added to the array directly, e.g.
  24 code::
  25 x = FunctionList(...some functions);
  26 x.array = x.array.insert(2, aFunction);
  27 ::
  28
  29 method::addFunc
  30
  31 This message is used to be able to add to an Object, to a Function, or to a FunctionList.
  32 code::nil.addFunc:: returns a function, if only one function is passed in the argument.
  33 code::function.addFunc:: then returns a FunctionList.
  34
  35 method::removeFunc
  36
  37 remove a function from the list.
  38
  39 returns:: the last function when only one function is left, or code::nil:: when the last function was removed.
  40
  41 discussion::
  42 code::addFunc:: and code::removeFunc:: are implemented for link::Classes/Nil::, link::Classes/Object:: and link::Classes/FunctionList::
  43
  44 code::
  45 nil.addFunc(f) // returns f
  46 obj.addFunc(f) // returns FunctionList([obj, f])
  47 nil.removeFunc(f) // returns nil
  48 obj.removeFunc(f) // returns nil, if f === obj, else obj is returned
  49 ::
  50
  51 examples::
  52
  53 code::
  54 // example
  55
  56 a = nil;
  57 a = a.addFunc { |x="", y=""| "this % is an % example\n".postf(x, y); 1 };
  58 a.postln;
  59 a = a.addFunc { |x="", y=""| "there is no % that is %\n".postf(x, y); 2 };
  60 a.value;
  61 a.value("text", "extraordinary well written")
  62 a.valueArray(["x", "y"]);
  63 ::
  64
  65 code::
  66 // Function:do vs FunctionList:do (same)
  67 a.do { |x| x.value };
  68 { 4 }.do { |x| x.value.postln }
  69
  70 (
  71 ().use {
  72         ~x = "array";
  73         ~y = "ominous";
  74         a.valueEnvir;
  75         a.valueEnvir("list");
  76 }
  77 )
  78 ::
  79
  80 code::
  81 // removing a function
  82 x = { "removal test".postln };
  83 a.addFunc(x);
  84 a.value;
  85 a = a.removeFunc(x);
  86 a.value;
  87
  88 // mathematics
  89 a = nil;
  90 a = a.addFunc({ 1.0.rand }).addFunc({ [0, 1].choose });
  91 a = a.squared.linexp(0, 1, 1.0, 500);
  92
  93 a.value;
  94 ::
  95
  96 code::
  97 // compatibility with function multichannel expansion
  98 a = nil;
  99 a = a.addFunc { |x=0| if(x > 0) { 7 } { 1000.rand } };
 100 a = a.addFunc { |x=0| if(x < 0) { 17 } { -1000.rand } };
 101 a.value
 102
 103 a = a.flop;
 104 a.value
 105 a.value([-1, 1])
 106 ::
 107
 108 code::
 109 // typical usage in a Document action
 110 // see also SCView: addAction example.
 111
 112 d = Document.current;
 113 d.keyDownAction = { "You touched the keyboard.".postln };
 114
 115 d.keyDownAction = d.keyDownAction.addFunc {:x, x<-(1..), :: "already % times\n\n".postf(x) };
 116
 117
 118 d.keyDownAction = nil;
 119
 120 // even if you don't know if there is already an action defined
 121 // one can add one.
 122
 123 (
 124 d.keyDownAction = nil;
 125 d.keyDownAction = d.keyDownAction.addFunc {:x, x<-(1..), :: "already % times\n\n".postf(x) };
 126
 127 );
 128
 129 d.keyDownAction = nil;
 130 ::
 131
 132
 133