HelpSource/Classes/OSCArgsMatcher.schelp

   1 CLASS:: OSCArgsMatcher
   2 summary:: Test for specific OSC arguments before evaluating a Function
   3 categories:: Undocumented classes
   4 related:: Classes/OSCFunc, Guides/OSC_communication
   5
   6 DESCRIPTION::
   7 OSCArgMatcher matches an argument template to a link::Classes/Function:: or similar object. When its value method is called, it evaluates the function if all of the arguments in its template pass a link::Reference/matchItem:: test.  Normally this is passed as the func arg for an link::Classes/OSCFunc:: or link::Classes/OSCdef::.
   8
   9
  10 CLASSMETHODS::
  11
  12 METHOD:: new
  13 Make a new OSCArgsMatcher
  14
  15 argument:: argTemplate
  16 An link::Classes/Array:: comprising a template for determining if incoming arguments match. For each argument that you wish to test, you may include a constant (for exact matching), code::nil:: (indicating that all possible values and types will match), or a link::Classes/Function:: to test the incoming argument (see link::Reference/matchItem:: for examples). These should be in the same order as the items in the incoming OSC message, starting from index 1. (Index 0 is the OSC address.)
  17
  18 argument:: func
  19 A link::Classes/Function:: or similar object which will respond to the incoming message. When evaluated it will be passed the arguments msg, time, addr, and recvPort, corresponding to the message as an link::Classes/Array:: in the form code::[OSCAddress, ...otherArgs]::, the time that the message was sent, a link::Classes/NetAddr:: corresponding to the IP address of the sender, and an link::Classes/Integer:: corresponding to the port on which the message was received.
  20
  21
  22 INSTANCEMETHODS::
  23 private:: init
  24
  25 METHOD:: value
  26 Test if an incoming message's arguments match, and if so evaluate this object's function. In normal usage (within an OSCFunc) this is done behind the scenes.
  27
  28 argument:: testMsg
  29 An link::Classes/Array:: in the form code::[OSCAddress, …msgArgs]::.
  30
  31 argument:: time
  32 The time that the message was sent as a link::Classes/Float::.
  33
  34 argument:: addr
  35 A link::Classes/NetAddr:: corresponding to the IP address of the sender.
  36
  37 argument:: recvPort
  38 An link::Classes/Integer:: corresponding to the port on which the message was received.
  39
  40
  41 EXAMPLES::
  42
  43 code::
  44 // Basic example (standalone use)
  45 m = OSCArgsMatcher([1, nil, 2], {'matches!'.postln});
  46 m.value(['/myAddress', 1, 3, 2], 0.0, NetAddr.localAddr, NetAddr.langPort); // matches!
  47
  48 // more typical usage, with an OSCFunc for finer grained matching
  49 s.boot;
  50 x = Synth(\default);
  51 OSCFunc(OSCArgsMatcher([x.nodeID], { 'ended!'.postln }), '/n_end', s.addr).oneShot;
  52 x.release(3);
  53 ::