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