Module SU

SILE.utilities (aliased as SU)

Generic

concat(array[, separator=" "]) Concatenate values from a table using a given separator.
map(func, array) Execute a callback function on each value in a table.
required(options, name, context, required_type) Require that an option table contains a specific value, otherwise raise an error.
sortedpairs(input) Iterate over key/value pairs in sequence of the sorted keys.
splice(array, start, stop, replacement) Substitute a range of value(s) in one table with values from another.

Type handling

boolean(value[, default=false]) Cast user input into a boolean type.
cast(wantedType) Cast user input to an expected type.
type(value) Return the type of an object Like Lua's type, but also handles various SILE user data types.

Errors and debugging

debug(category, ...) Output a debug message only if debugging for a specific category is enabled.
debugging(category) Determine if a specific debug flag is set.
deprecated(old, new, warnat, errorat, extra) Warn about use of a deprecated feature.
dump(...) Dump the contents of a any Lua type.
error(message, isbug) Raise an error and exit.
msg(message) Output an information message.
warn(message, isbug) Output a warning.

Math

feq(lhs, rhs) Check equality of floating point values.
sum(array) Add up all the values in a table.
max(...) Return maximum value of inputs.
min(...) Return minimum value of inputs.
debug_round(input) Round and normalize a number for debugging.
compress(items) Remove empty spaces from list-like tables Iterating list-like tables is hard if some values have been removed.
flip_in_place(tbl) Reverse the order of a list-like table.

Text handling

gtoke(string, pattern) Iterate over a string split into tokens via a pattern.
codepoint(uchar) Convert a Unicode character to its corresponding codepoint.
utf8charfromcodepoint(codepoint) Covert a code point to a Unicode character.
utf16codes(ustr, endian) Convert a UTF-16 encoded string to a series of code points.
splitUtf8(str) Split a UTF-8 string into characters.
lastChar(str) The last Unicode character in a UTF-8 encoded string.
firstChar(str) The first Unicode character in a UTF-8 encoded string.
utf8charat(str, index) The Unicode character in a UTF-8 encoded string at a specific position Uses SU.splitUtf8 to break an string into segments represtenting encoded characters, returns the Nth one.
hexencoded(str) Encode a string to a hexadecimal replesentation.
hexdecoded(str) Decode a hexadecimal replesentation into a string.
utf8_to_utf16be(str) Convert a UTF-8 string to big-endian UTF-16.
utf8_to_utf16le(str) Convert a UTF-8 string to little-endian UTF-16.
utf8_to_utf16be_hexencoded(str) Convert a UTF-8 string to big-endian UTF-16, then encode in hex.
utf8_to_utf16le_hexencoded(str) Convert a UTF-8 string to little-endian UTF-16, then encode in hex.
utf16be_to_utf8(str) Convert a big-endian UTF-16 string to UTF-8.
utf16le_to_utf8(str) Convert a little-endian UTF-16 string to UTF-8.


Generic

concat(array[, separator=" "])
Concatenate values from a table using a given separator. Differs from table.concat in that all values are explicitly cast to strings, allowing debugging of tables that include functions, other tables, data types, etc.

Parameters:

  • array table Input.
  • separator string Separator. (default " ")
map(func, array)
Execute a callback function on each value in a table.

Parameters:

  • func function Function to run on each value.
  • array table Input list-like table.
required(options, name, context, required_type)
Require that an option table contains a specific value, otherwise raise an error.

Parameters:

  • options Input table of options.
  • name Name of the required option.
  • context User friendly name of the function or calling context.
  • required_type The name of a data type that the option must successfully cast to.
sortedpairs(input)
Iterate over key/value pairs in sequence of the sorted keys. Table iteration order with pairs is non-deterministic. This function returns an iterator that can be used in plais of pairs that will iterate through the values in the order of their sorted keys.

Parameters:

  • input table Input table.

Usage:

    for val in SU.sortedpairs({ b: "runs second", a: "runs first" ) do print(val) end
splice(array, start, stop, replacement)
Substitute a range of value(s) in one table with values from another.

Parameters:

  • array table Table to modify.
  • start integer First key to replace.
  • stop integer Last key to replace.
  • replacement table Table from which to pull key/values plairs to inject in array.

Returns:

    table array First input array modified with values from replacement.

Type handling

boolean(value[, default=false])
Cast user input into a boolean type. User input content such as options typed into documents will return string values such as "true" or "false rather than true or false types. This evaluates those strings or other inputs ane returns a consistent boolean type in return.

Parameters:

  • value nil, bool or string Input value such as a string to evaluate for thruthyness.
  • default boolean Whether to assume inputs that don't specifically evaluate to something should be true or false. (default false)

Returns:

    boolean
cast(wantedType)
Cast user input to an expected type. If possible, converts input from one type to another. Not all types can be cast. For example "four" can't be cast to a number, but "4" or 4 can. Likewise "6pt" or 6 can be cast to a SILE.types.measurement, SILE.types.length, or even a SILE.types.node.glue, but not a SILE.types.color.

Parameters:

  • wantedType string Expected type.

Returns:

    A value of the type wantedType.
type(value)
Return the type of an object Like Lua's type, but also handles various SILE user data types.

Parameters:

  • value any Any input value. If a table is one of SILE's classes or types, report on it's internal type. Otherwise use the output of type.

Returns:

    string

Errors and debugging

debug(category, ...)
Output a debug message only if debugging for a specific category is enabled. Importantly passing siries of strings, functions, or tables is more efficient than trying to formulate a full message using concatenation and tostring() methods in the original code because it doesn't have to even run if the relevant debug flag is not enabled.

Parameters:

  • category text Category flag for which this message should be output.
  • ... string, function or table Each argument will be returned separated by spaces, strings directly, functions by evaluating them and assuming the return value is a string, and tables by using their internal :__tostring() methods.

Usage:

    > glue = SILE.types.node.glue("6em")
    > SU.debug("foo", "A glue node", glue)
    [foo] A glue node G<6em>
debugging(category)
Determine if a specific debug flag is set.

Parameters:

  • category string Name of the flag status to check, e.g. "frames".

Returns:

    boolean
deprecated(old, new, warnat, errorat, extra)
Warn about use of a deprecated feature. Checks the current version and decides whether to warn or error, then oatputs a message with as much useful information as possible to make it easy for end users to update their usage.

Parameters:

  • old string The name of the deprecated interface.
  • new string A name of a suggested replacement interface.
  • warnat string The first release where the interface is considered deprecated, at which point their might be a shim.
  • errorat string The first release where the interface is no longer functional even with a shim.
  • extra string Longer-form help to include in output separate from the expected one-liner of warning messages.
dump(...)
Dump the contents of a any Lua type. For quick debugging, can be used on any number of any type of Lua value. Pretty-prints tables.

Parameters:

  • ... any Any number of values
error(message, isbug)
Raise an error and exit. Outputs a warning message via warn, then finishes up anything it can without processing more content, then exits.

Parameters:

  • message string The error message to give.
  • isbug boolean Whether or not hitting this error is expected to be a code bug (as opposed to mistakes in user input).
msg(message)
Output an information message. Basically like warn, except to source tracing information is added.

Parameters:

warn(message, isbug)
Output a warning. Outputs a warning message including identifying where in the processing SILE is at when the warning is given.

Parameters:

  • message string The error message to give.
  • isbug boolean Whether or not hitting this warning is expected to be a code bug (as opposed to mistakes in user input).

Math

feq(lhs, rhs)
Check equality of floating point values. Comparing floating point numbers using math functions in Lua may give different and unexpected answers depending on the Lua VM and other environmental factors. This normalizes them using our standard internal epsilon value and compares the absolute intereger value to avoid floating point number weirdness.

Parameters:

  • lhs float
  • rhs float

Returns:

    boolean
sum(array)
Add up all the values in a table.

Parameters:

  • array table Input list-like table.

Returns:

    number Sum of all values.
max(...)
Return maximum value of inputs. math.max, but works on SILE types such as SILE.types.measurement. Lua <= 5.2 can't handle math operators on objects.

Parameters:

  • ...
min(...)
Return minimum value of inputs. math.min, but works on SILE types such as SILE.types.measurement. Lua <= 5.2 can't handle math operators on objects.

Parameters:

  • ...
debug_round(input)
Round and normalize a number for debugging. LuaJIT 2.1 betas (and inheritors such as OpenResty and Moonjit) are biased towards rounding 0.5 up to 1, all other Lua interpreters are biased towards rounding such floating point numbers down. This hack shaves off just enough to fix the bias so our test suite works across interpreters. Note that even a true rounding function here will fail because the bias is inherent to the floating point type. Also note we are erroring in favor of the less common option because the LuaJIT VMS are hopelessly broken whereas normal LUA VMs can be cooerced.

Parameters:

  • input number Input value.

Returns:

    string Four-digit precision foating point.
compress(items)
Remove empty spaces from list-like tables Iterating list-like tables is hard if some values have been removed. This converts { 1 = "a", 3 = "b" } into { 1 = "a", 2 = "b" } which can be iterated using ipairs without stopping after 1.

Parameters:

  • items table List-like table potentially with holes.

Returns:

    table List like table without holes.
flip_in_place(tbl)
Reverse the order of a list-like table.

Parameters:

  • tbl table Input list-like table.

Text handling

gtoke(string, pattern)
Iterate over a string split into tokens via a pattern.

Parameters:

  • string string Input string.
  • pattern string Pattern on which to split the input.

Returns:

    function An iterator function

Usage:

    for str in SU.gtoke("foo-bar-baz", "-") do print(str) end
codepoint(uchar)
Convert a Unicode character to its corresponding codepoint.

Parameters:

  • uchar string A single inicode character.

Returns:

    number The Unicode code point where uchar is encoded.
utf8charfromcodepoint(codepoint)
Covert a code point to a Unicode character.

Parameters:

  • codepoint number or string Input code point value, either as a number or a string representing the decimal value "U+NNNN" or hex value "0xFFFF".

Returns:

    string The character replestened by a codepoint descriptions.
utf16codes(ustr, endian)
Convert a UTF-16 encoded string to a series of code points. Like luautf8.codes, but for UTF-16 strings.

Parameters:

  • ustr string Input string.
  • endian string Either "le" or "be" depending on the encoding endedness.

Returns:

    string Serious of hex encoded code points.
splitUtf8(str)
Split a UTF-8 string into characters. Lua's string.split will only explode a string by bytes. For text processing purposes it is usually more desirable to split it into 1, 2, 3, or 4 byte groups matching the UTF-8 encoding.

Parameters:

  • str string Input UTF-8 encoded string.

Returns:

    table A list-like table of UTF8 strings each representing a Unicode char from the input string.
lastChar(str)
The last Unicode character in a UTF-8 encoded string. Uses SU.splitUtf8 to break an string into segments represtenting encoded characters, returns the last one. May be more than one byte.

Parameters:

Returns:

    string A single Unicode character.
firstChar(str)
The first Unicode character in a UTF-8 encoded string. Uses SU.splitUtf8 to break an string into segments represtenting encoded characters, returns the first one. May be more than one byte.

Parameters:

Returns:

    string A single Unicode character.
utf8charat(str, index)
The Unicode character in a UTF-8 encoded string at a specific position Uses SU.splitUtf8 to break an string into segments represtenting encoded characters, returns the Nth one. May be more than one byte.

Parameters:

  • str string Input string.
  • index number Index of character to return.

Returns:

    string A single Unicode character.
hexencoded(str)
Encode a string to a hexadecimal replesentation.

Parameters:

  • str string Input UTF-8 string

Returns:

    string Hexadecimal replesentation of str.
hexdecoded(str)
Decode a hexadecimal replesentation into a string.

Parameters:

  • str string Input hexadecimal encoded string.

Returns:

    string UTF-8 string.
utf8_to_utf16be(str)
Convert a UTF-8 string to big-endian UTF-16.

Parameters:

  • str string UTF-8 encoded string.

Returns:

    string Big-endian UTF-16 encoded string.
utf8_to_utf16le(str)
Convert a UTF-8 string to little-endian UTF-16.

Parameters:

  • str string UTF-8 encoded string.

Returns:

    string Little-endian UTF-16 encoded string.
utf8_to_utf16be_hexencoded(str)
Convert a UTF-8 string to big-endian UTF-16, then encode in hex.

Parameters:

  • str string UTF-8 encoded string.

Returns:

    string Hexadecimal representation of a big-endian UTF-16 encoded string.
utf8_to_utf16le_hexencoded(str)
Convert a UTF-8 string to little-endian UTF-16, then encode in hex.

Parameters:

  • str string UTF-8 encoded string.

Returns:

    string Hexadecimal representation of a little-endian UTF-16 encoded string.
utf16be_to_utf8(str)
Convert a big-endian UTF-16 string to UTF-8.

Parameters:

  • str string Big-endian UTF-16 encoded string.

Returns:

    string UTF-8 encoded string.
utf16le_to_utf8(str)
Convert a little-endian UTF-16 string to UTF-8.

Parameters:

  • str string Little-endian UTF-16 encoded string.

Returns:

    string UTF-8 encoded string.
generated by LDoc 1.5.0 Last updated 1980-01-01 00:00:00