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:

  1. value (can be nil)
  2. 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
generated by LDoc 1.4.2