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 file.

Usage #

Import this module with util = require 'aegisub.util'

Table functions #

Duplicating tables in various ways is a common task. util provides some functions to handle the most common cases.

copy #

Synopsis: newtable = util.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. For example, if oldtable.st refers to a table, newtable.st will refer to the same table, and changes made to newtable.st will also be reflected in oldtable.st and vice versa.

deep_copy #

Synopsis: newtable = util.deep_copy(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.

Colour functions #

It is often useful to do various transformations on colour data. Several functions for this are included.

ass_color #

Synopsis: colorstring = util.ass_color(r, g, b)

Makes an ASS colour string in the form &HBBGGRR from the given r, g and b arguments.

Warning: The arguments are not checked for range. Values outside the 0..255 range will produce garbage output.

ass_alpha #

Synopsis: alphastring = util.ass_alpha(a)

Makes an ASS alpha string in the form &HAA& from the given a argument.

Does not check input range.

ass_style_color #

Synopsis: colorstring = util.ass_style_color(r, g, b, a)

Makes an ASS colour string suitable for use in Style definitions, i.e. in format &HAABBGGRR.

Does not check input range.

extract_color #

Synopsis: r, g, b, a = util.extract_color(colorstring)

Extracts colour components from a colour string. Several formats of colour strings are recognised:

• Style definition: &HAABBGGRR
• Inline override: &HBBGGRR&
• Alpha override: &HAA&
• HTML with alpha: #RRGGBBAA

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, nil is returned.

r, g, b, a = extract_color("&H7F&")

alpha_from_style #

Synopsis: alphastring = util.alpha_from_style(coloralphastring)

Returns the alpha part of a colour string, as an alpha override string, i.e. &HAA& format. This function is a composition of extract_color and ass_alpha.

color_from_style #

Synopsis: colorstring = util.color_from_style(coloralphastring)

Returns the colour part of a colour string, as a colour override string, i.e. &HBBGGRR& format. This function is a composition of extract_color and ass_color.

HSV_to_RGB #

Synopsis: r, g, b = util.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 s and v are 0..1. These are not range checked. Output range of r, g and b are 0..255.

String functions #

Because the Lua standard string library is fairly limited, a few additional helper functions are provided. See also unicode.

string.trim #

Synopsis: outstring = util.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 %s class to match spaces, which in some legacy encodings will result in it also matching some prefix bytes in UTF-8 encoded text.

string.headtail #

Synopsis: head, tail = util.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.

If instring does not contain any space characters it returns instring, "".

string.words #

Synopsis: for word in util.words(instring) do ... end

Returns an iterator function for use in a for loop, to loop over all the words in the string using string.headtail semantics.

Numeric functions #

Functions to handle various operations on numbers.

clamp #

703outval = util.clamp(inval, min, max)

Clamps inval to be in range min..max.

interpolate #

Synopsis: outval = util.interpolate(t, a, b)

Interpolates between a and b. t is the time variable in range 0..1. Values outside this range are clamped.

interpolate_color #

Synopsis: outcolor = util.interpolate_color(t, color1, color2)

Interpolate between color1 and color2 with t as time variable in range 0..1. color1, color2 and outcolor are colour strings, and outcolour will be in colour override format.

interpolate_alpha #

Synopsis: outalpha = util.interpolate_alpha(t, alpha1, alpha2)

Similar to interpolate_color, but interpolates alpha values instead. Also works on colour strings, and will return an alpha override string.