Module xOscPattern
This class defines a syntax for matching/extracting/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
| get_arg_names () | get/set "display name" for each captured part, e.g. |
| get_complete () | test the input/output pattern and return the result (validate) |
| 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 |
| purely_literal () | Check if the pattern contains only literal values (no wildcards/tokens) return boolean |
| generate (args) | Create a new OSC message from internal or provided values |
| test_pattern (str_pattern) | Static methods |
| types_are_matching (this, that) | Check if pattern is matching same type of values as another pattern, disregarding any literal values being set - only look for the type/tag. |
Tables
| self.arguments | table |
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.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 |
| self.uid | string, 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 |
Functions
- get_arg_names ()
-
get/set "display name" for each captured part, e.g. {"x","y","z"}
(always matching the number of arguments - undefined names are left empty)
Returns:
-
table
- get_complete ()
- test the input/output pattern and return the result (validate)
- 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
- purely_literal ()
- Check if the pattern contains only literal values (no wildcards/tokens) return boolean
- generate (args)
-
Create a new OSC message from internal or provided values
Parameters:
- args
(table
)
Returns:
- renoise.Osc.Message or nil when failed
- string, message when failed
- args
(table
- test_pattern (str_pattern)
-
Static methods Check if the syntax is fundamentally flawed
Parameters:
- str_pattern check for initial forward slash
Returns:
-
boolean,string
- types_are_matching (this, that)
-
Check if pattern is matching same type of values as another pattern,
disregarding any literal values being set - only look for the type/tag.
For example, "/test %i" would match "/test 42" as they have the same path and are both matching an integer value...Parameters:
- this (xOscPattern)
- that (xOscPattern)
Returns:
-
boolean,string
Tables
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.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
- self.uid
- string, 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}