Module SU
SILE.utilities (aliased as SU)
-
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:
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.
-
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
-
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).
-
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:
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.
-
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:
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.