HelpSource/Classes/OSCArgsMatcher.schelp

   1 CLASS:: OSCArgsMatcher
   2 summary:: Test for specific OSC arguments before evaluating a Function
   3 categories:: External Control>OSC>Matchers
   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.  This is used by link::Classes/OSCMessageDispatcher:: and link::Classes/OSCMessagePatternDispatcher:: to match incoming OSC messages to instances of link::Classes/OSCFunc:: or link::Classes/OSCdef:: using sender address. This class is private, and generally users should not need to address instances directly.
   8
   9 CLASSMETHODS::
  10
  11 METHOD:: new
  12 Make a new OSCArgsMatcher
  13
  14 argument:: argTemplate
  15 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.)
  16
  17 argument:: func
  18 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.
  19
  20
  21 INSTANCEMETHODS::
  22 private:: init
  23
  24 METHOD:: value
  25 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.
  26
  27 argument:: testMsg
  28 An link::Classes/Array:: in the form code::[OSCAddress, …msgArgs]::.
  29
  30 argument:: time
  31 The time that the message was sent as a link::Classes/Float::.
  32
  33 argument:: addr
  34 A link::Classes/NetAddr:: corresponding to the IP address of the sender.
  35
  36 argument:: recvPort
  37 An link::Classes/Integer:: corresponding to the port on which the message was received.
  38
  39
  40 EXAMPLES::
  41
  42 code::
  43 // Basic example (standalone use)
  44 m = OSCArgsMatcher([1, nil, 2], {'matches!'.postln});
  45 m.value(['/myAddress', 1, 3, 2], 0.0, NetAddr.localAddr, NetAddr.langPort); // matches!
  46 ::