Module xOscPattern

This class defines a simple syntax for matching/extracting and generating OSC messages.

To start with, you define an "input pattern" for matching values - either a literal value (number or string), or a "wildcard". For example:

  -- Match message with four integers, third one equal to 48
  "/renoise/trigger/note_on %i %i 48 %i"

Wildcard and literal values

A wildcard is one of the supported OSC tags preceded by a percent sign. For example, the wildcard %f will match any floating point value. It's possible to mix literal values and wildcards.

Depending on how literal values are specified, and whether strict is set to true, they are interpreted as specific types:

"/some/integer 1"   <-- integer(strict)/number
"/some/integer 0x1" <-- integer(strict)/number
"/some/float 1.0"   <-- float(strict)/number
"/some/string true" <-- string

Strict mode and caching

Strict mode will look "more closely" at the literal values. This makes it possible to define a more restrictive/precise pattern and by default, is turned on.

A special tag (NUMBER) exists, which can accept any type of value which can be translated into a number. An example would be if you have a device which transmit integers as floating point, or vice versa.

Disabling strict interpretation will basically set all numeric tags to NUMBER instead of their more strict counterpart. The downside is that using a NUMBER will make the pattern unable to use caching.

Functions

parse_input_pattern () Define the OSC pattern and wildcards/literal values + also determines if pattern is cacheable
parse_output_pattern () Decide how outgoing messages are constructed + define a new "osc pattern" + rearrange the order of values via "$n" tokens
generate (args) Create a new OSC message from internal or provided values
test_pattern (str_pattern) Static methods

Tables

self.arguments table, value is undefined when wildcard

Fields

self.pattern_in string, pattern used for matching the input
self.pattern_out string, pattern for constructing new messages
self.complete boolean, true when message contain functioning patterns
self.callback_fn function, where to output message to
self.before_modified_observable called when patterns are changed
self.strict boolean, whether to interpret literal values strictly or not (if false, use xOscValue.TAG.NUMBER to represent all numbers)
self.precision number, avoid rounding errors when comparing floats
uid_counter int, unique identifier for the pattern
self.cacheable boolean, true when we can cache the incoming message
self.arg_names renoise.Document.ObservableStringList (this is just a convenience method for getting/setting the 'name' part of our xOscValues)
self.osc_pattern_in string, input pattern (set via 'pattern_in')
self.osc_pattern_out string, output pattern (set via 'patternin' or 'patternout')
self.output_args table output arguments/order e.g.


Functions

parse_input_pattern ()
Define the OSC pattern and wildcards/literal values + also determines if pattern is cacheable
parse_output_pattern ()
Decide how outgoing messages are constructed + define a new "osc pattern" + rearrange the order of values via "$n" tokens
generate (args)
Create a new OSC message from internal or provided values

Parameters:

  • args (table)

Returns:

  1. renoise.Osc.Message or nil when failed
  2. string, message when failed
test_pattern (str_pattern)
Static methods Check if the syntax is fundamentally flawed

Parameters:

  • str_pattern

Returns:

    boolean,string

Tables

self.arguments
table, value is undefined when wildcard

Fields

self.pattern_in
string, pattern used for matching the input
self.pattern_out
string, pattern for constructing new messages
self.complete
boolean, true when message contain functioning patterns
self.callback_fn
function, where to output message to
self.before_modified_observable
called when patterns are changed
self.strict
boolean, whether to interpret literal values strictly or not (if false, use xOscValue.TAG.NUMBER to represent all numbers)
self.precision
number, avoid rounding errors when comparing floats
uid_counter
int, unique identifier for the pattern
self.cacheable
boolean, true when we can cache the incoming message
self.arg_names
renoise.Document.ObservableStringList (this is just a convenience method for getting/setting the 'name' part of our xOscValues)
self.osc_pattern_in
string, input pattern (set via 'pattern_in')
self.osc_pattern_out
string, output pattern (set via 'patternin' or 'patternout')
self.output_args
table output arguments/order e.g. "/some/pattern $3 $1 $2" --> {3,1,2}
generated by LDoc 1.4.2