Module xLib
This is the core xLib class, containing a bunch of static helper methods .
About xLib
The xLib library is a suite of classes that extend the standard Renoise API. Each class aims to be implemented with static methods as widely as possible - this should make xLib compatible with most programming styles.
How to use
If you are planning to use xLib in your own project, you need to include this file or define the TRACE/LOG methods yourself (note: including xDebug will replace them with a more sophisticated version).
The recommended practice is to require any classes you need in the main.lua of your tool (as this also documents the exact requirements). Only interdependent classes are automatically resolved when you include them. To document this, they are located in their own folder - this keeps the project tidy.
Finally, to improve the performance of xLib, the entire library is using a single variable to reference the Renoise song object - called "rns". You will need to define/maintain this variable yourself (see below)
Functions
unpack_args (...) | Turn varargs into a table |
match_table_key (t, key) | Match item(s) in an associative array (provide key) |
scale_value (value, in_min, in_max, out_min, out_max) | scale_value: scale a value to a range within a range |
clamp_value (value, min_value, max_value) | clamp_value: ensure value is within min/max |
split (str, pat) | split string - original script: http://lua-users.org/wiki/SplitJoin |
trim (s) | remove trailing and leading whitespace from string. |
soft_wrap (str) | insert return code whenever we encounter dashes or spaces in a string TODO keep dashes, and allow a certain length per line |
get_hex_digits (val) | find number of hex digits needed to represent a number (e.g. |
sanitize_string (str) | prepare a string so it can be stored in XML attributes (strip illegal characters instead of trying to fix them) |
stringify_table (t) | take a table and convert into strings - useful e.g. |
parse_str (str) | receives a string argument and turn it into a proper object or value |
round_value (num) | round_value (from http://lua-users.org/wiki/SimpleRound) |
float_compare (val1, val2, precision) | compare two numbers with variable precision |
table_compare (t1, t2) | quick'n'dirty table compare (values in first level only) |
serialize_object (obj) | try serializing a value or return "???" the result should be a valid, quotable string |
serialize_table (t, max_depth) | serialize table into string, with some formatting options |
Functions
- unpack_args (...)
-
Turn varargs into a table
Parameters:
- ...
- match_table_key (t, key)
-
Match item(s) in an associative array (provide key)
Parameters:
- t (table)
- key (string)
Returns:
-
table
- scale_value (value, in_min, in_max, out_min, out_max)
-
scale_value: scale a value to a range within a range
Parameters:
- value (number) the value we wish to scale
- in_min (number)
- in_max (number)
- out_min (number)
- out_max (number)
Returns:
-
number
- clamp_value (value, min_value, max_value)
-
clamp_value: ensure value is within min/max
Parameters:
- value (number)
- min_value (number)
- max_value (number)
Returns:
-
number
- split (str, pat)
-
split string - original script: http://lua-users.org/wiki/SplitJoin
Parameters:
- str (string)
- pat (string) pattern
Returns:
-
table
- trim (s)
-
remove trailing and leading whitespace from string.
http://en.wikipedia.org/wiki/Trim_(8programming)
Parameters:
- s (string)
Returns:
-
string
- soft_wrap (str)
-
insert return code whenever we encounter dashes or spaces in a string
TODO keep dashes, and allow a certain length per line
Parameters:
- str (string)
Returns:
-
string
- get_hex_digits (val)
-
find number of hex digits needed to represent a number (e.g. 255 = 2)
Parameters:
- val (int)
Returns:
-
int
- sanitize_string (str)
-
prepare a string so it can be stored in XML attributes
(strip illegal characters instead of trying to fix them)
Parameters:
- str (string)
Returns:
-
string
- stringify_table (t)
-
take a table and convert into strings - useful e.g. for viewbuilder popup
(if table is associative, will use values)
Parameters:
- t (table)
Returns:
-
table
- parse_str (str)
-
receives a string argument and turn it into a proper object or value
Parameters:
- str (string), e.g. "renoise.song().transport.keyboard_velocity"
Returns:
- value (can be nil)
- string, error message when failed
- round_value (num)
-
round_value (from http://lua-users.org/wiki/SimpleRound)
Parameters:
- num
- float_compare (val1, val2, precision)
-
compare two numbers with variable precision
Parameters:
- val1
- val2
- precision val1 = math.floor(val1 * precision) val2 = math.floor(val2 * precision)
- table_compare (t1, t2)
-
quick'n'dirty table compare (values in first level only)
Parameters:
- t1
- t2
Returns:
-
boolean, true if identical
- serialize_object (obj)
-
try serializing a value or return "???"
the result should be a valid, quotable string
Parameters:
- obj , value or object
Returns:
-
string
- serialize_table (t, max_depth)
-
serialize table into string, with some formatting options
Parameters:
- t (table)
- max_depth (int), determine how many levels to process - optional
Returns:
-
table