Aegisub / Automation / Lua / Modules / utils.lua
The Automation 4 Lua include file
utils.lua contains various support
functions to aid writing Lua scripts. There is no general theme for the
Duplicating tables in various ways is a common task.
some functions to handle the most common cases.
newtable = table.copy(oldtable)
Makes a shallow copy of the table passed as parameter. Shallow here means
that it does not dive into contained tables and copy those as well, so if
oldtable.st refers to a table,
newtable.st will refer to the same
table, such that modifying
newtable.st will also be reflected in
oldtable.st and vice versa.
table.copy. Included to help transitioning from Automation 3.
newtable = table.copy_deep(oldtable)
Makes a deep copy of the table passed as parameter. While this function attempts to handle circular references and not do infinite recursion on them, it might not work in all cases. You will rarely need to use this function; if you think you need to do a deep copy, consider your task an extra time.
Warning: This function has not been heavily tested.
It is often useful to do various transformations on colour data. Several functions for this are included.
colorstring = ass_color(r, g, b)
Makes an ASS colour string in the form
&HBBGGRR from the given
Warning: The arguments are not checked for range. Values outside the 0..255 range will produce garbage output.
alphastring = ass_alpha(a)
Makes an ASS alpha string in the form
&HAA& from the given
Does not check input range.
colorstring = ass_style_color(r, g, b, a)
Makes an ASS colour string suitable for use in Style definitions, i.e. in
Does not check input range.
r, g, b, a = extract_color(colorstring)
Extracts colour components from a colour string. Several formats of colour strings are recognised:
- Style definition:
- Inline override:
- Alpha override:
- HTML with alpha:
Note that this function always returns four numbers when passed a valid
colour string. Unused values (depends on the format of the colour string)
are assigned 0 (zero.) If an unrecognised colour string is passed,
r, g, b, a = extract_color("&H7F&")
b will be 0;
a will be 127.
alphastring = alpha_from_style(coloralphastring)
Returns the alpha part of a colour string, as an alpha override string,
&HAA& format. This function is a composition of
colorstring = color_from_style(coloralphastring)
Returns the colour part of a colour string, as a colour override string,
&HBBGGRR& format. This function is a composition of
r, g, b = HSV_to_RGB(h, s, v)
Transforms a colour given in Hue, Saturation, Value space into Red, Green, Blue space.
h is given in degrees. The nominal range is 0..359; values outside this
range will be translated into it. Input range of
v are 0..1.
These are not range checked. Output range of
b are 0..255.
Because the Lua standard
string library is fairly limited, a few
additional helper functions are provided. See also unicode.lua.
outstring = string.trim(instring)
Removes all space characters at the start and end of the input string, and returns the transformed string.
Warning: This function is not UTF-8 safe. It uses the Lua regex
to match spaces, which in some legacy encodings will result in it also
matching some prefix bytes in UTF-8 encoded text.
head, tail = string.headtail(instring)
Splits a string by first space-sequence into a "head" and a "tail", similar to the handling of linked lists in several functional languages.
instring does not contain any space characters it returns
for word in string.words(instring) do ... end
Returns an iterator function for use in a
for loop, to loop over all the
words in the string using
Functions to handle various operations on numbers.
outval = clamp(inval, min, max)
inval to be in range
outval = interpolate(t, a, b)
t is the time variable in range 0..1.
Values outside this range are clamped.
outcolor = interpolate_color(t, color1, color2)
t as time variable in
outcolor are colour strings,
outcolour will be in colour override format.
outalpha = interpolate_alpha(t, alpha1, alpha2)
interpolate_color, but interpolates alpha values instead. Also
works on colour strings, and will return an alpha override string.