From 9c7998803525011e41fffb5b3bb6f9bb991ce150 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Mon, 12 Feb 2024 18:01:48 +0300 Subject: [PATCH] style(utilities): Normalize coding style of function definitions --- core/utilities/init.lua | 96 ++++++++++++++++++++--------------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/core/utilities/init.lua b/core/utilities/init.lua index 76a84ebf5..55bac586c 100644 --- a/core/utilities/init.lua +++ b/core/utilities/init.lua @@ -18,14 +18,14 @@ local epsilon = 1E-12 -- include functions, other tables, data types, etc. -- @tparam table array Input. -- @tparam[opt=" "] string separator Separator. -utilities.concat = function (array, separator) +function utilities.concat (array, separator) return table.concat(utilities.map(tostring, array), separator) end --- Execute a callback function on each value in a table. -- @tparam function func Function to run on each value. -- @tparam table array Input list-like table. -utilities.map = function (func, array) +function utilities.map (func, array) local new_array = {} local last = #array for i = 1, last do @@ -39,7 +39,7 @@ end -- @param name Name of the required option. -- @param context User friendly name of the function or calling context. -- @param required_type The name of a data type that the option must sucessfully cast to. -utilities.required = function (options, name, context, required_type) +function utilities.required (options, name, context, required_type) if not options[name] then utilities.error(context.." needs a "..name.." parameter") end if required_type then return utilities.cast(required_type, options[name]) @@ -52,7 +52,7 @@ end -- of `pairs` that will iterate through the values in the order of their *sorted* keys. -- @tparam table input Input table. -- @usage for val in SU.sortedpairs({ b: "runs second", a: "runs first" ) do print(val) end -utilities.sortedpairs = function (input) +function utilities.sortedpairs (input) local keys = {} for k, _ in pairs(input) do keys[#keys+1] = k @@ -76,7 +76,7 @@ end -- @tparam integer stop Last key to replace. -- @tparam table replacement Table from which to pull key/values plairs to inject in array. -- @treturn table array First input array modified with values from replacement. -utilities.splice = function (array, start, stop, replacement) +function utilities.splice (array, start, stop, replacement) local ptr = start local room = stop - start + 1 local last = replacement and #replacement or 0 @@ -97,7 +97,7 @@ utilities.splice = function (array, start, stop, replacement) end -- TODO: Unused, now deprecated? -utilities.inherit = function (orig, spec) +function utilities.inherit (orig, spec) local new = pl.tablex.deepcopy(orig) if spec then for k,v in pairs(spec) do new[k] = v end @@ -120,7 +120,7 @@ end -- @tparam nil|bool|string value Input value such as a string to evaluate for thruthyness. -- @tparam[opt=false] boolean default Whether to assume inputs that don't specifically evaluate to something should be true or false. -- @treturn boolean -utilities.boolean = function (value, default) +function utilities.boolean (value, default) if value == false then return false end if value == true then return true end if value == "false" then return false end @@ -139,7 +139,7 @@ end -- a SILE.types.node.glue, but not a SILE.types.color. -- @tparam string wantedType Expected type. -- @return A value of the type wantedType. -utilities.cast = function (wantedType, value) +function utilities.cast (wantedType, value) local actualType = SU.type(value) wantedType = string.lower(wantedType) if wantedType:match(actualType) then return value @@ -182,7 +182,7 @@ end -- @tparam any value 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`. -- @treturn string -utilities.type = function(value) +function utilities.type (value) if type(value) == "number" then return math.floor(value) == value and "integer" or "number" elseif type(value) == "table" and value.prototype then @@ -208,7 +208,7 @@ end -- > glue = SILE.types.node.glue("6em") -- > SU.debug("foo", "A glue node", glue) -- [foo] A glue node G<6em> -utilities.debug = function (category, ...) +function utilities.debug (category, ...) if SILE.quiet then return end if utilities.debugging(category) then local inputs = pl.utils.pack(...) @@ -228,7 +228,7 @@ end --- Determine if a specific debug flag is set. -- @tparam string category Name of the flag status to check, e.g. "frames". -- @treturn boolean -utilities.debugging = function (category) +function utilities.debugging (category) return SILE.debugFlags.all and category ~= "profile" or SILE.debugFlags[category] end @@ -241,7 +241,7 @@ end -- a shim. -- @tparam string errorat The first release where the interface is no longer functional even with a shim. -- @tparam string extra Longer-form help to include in output separate from the expected one-liner of warning messages. -utilities.deprecated = function (old, new, warnat, errorat, extra) +function utilities.deprecated (old, new, warnat, errorat, extra) warnat, errorat = semver(warnat or 0), semver(errorat or 0) local current = SILE.version and semver(SILE.version:match("v([0-9]*.[0-9]*.[0-9]*)")) or warnat -- SILE.version is defined *after* most of SILE loads. It’s available at @@ -262,7 +262,7 @@ end --- 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. -- @tparam any ... Any number of values -utilities.dump = function (...) +function utilities.dump (...) local arg = { ... } -- Avoid things that Lua stuffs in arg like args to self() pl.pretty.dump(#arg == 1 and arg[1] or arg, "/dev/stderr") end @@ -273,7 +273,7 @@ local _skip_traceback_levels = 2 -- Outputs a warning message via `warn`, then finishes up anything it can without processing more content, then exits. -- @tparam string message The error message to give. -- @tparam boolean isbug Whether or not hitting this error is expected to be a code bug (as opposed to misakes in user input). -utilities.error = function (message, isbug) +function utilities.error (message, isbug) _skip_traceback_levels = 3 utilities.warn(message, isbug) _skip_traceback_levels = 2 @@ -286,7 +286,7 @@ end --- Output an information message. -- Basically like `warn`, except to source tracing information is added. -- @tparam string message -utilities.msg = function (message) +function utilities.msg (message) if SILE.quiet then return end io.stderr:write("\n! " .. message .. "\n") end @@ -295,7 +295,7 @@ end -- Outputs a warning message including identifying where in the processing SILE is at when the warning is given. -- @tparam string message The error message to give. -- @tparam boolean isbug Whether or not hitting this warning is expected to be a code bug (as opposed to misakes in user input). -utilities.warn = function (message, isbug) +function utilities.warn (message, isbug) utilities.msg(message) if SILE.traceback or isbug then io.stderr:write(" at:\n" .. SILE.traceStack:locationTrace()) @@ -318,7 +318,7 @@ end -- @tparam float lhs -- @tparam float rhs -- @treturn boolean -utilities.feq = function (lhs, rhs) +function utilities.feq (lhs, rhs) lhs = SU.cast("number", lhs) rhs = SU.cast("number", rhs) local abs = math.abs @@ -328,7 +328,7 @@ end --- Add up all the values in a table. -- @tparam table array Input list-like table. -- @treturn number Sum of all values. -utilities.sum = function (array) +function utilities.sum (array) local total = 0 local last = #array for i = 1, last do @@ -340,7 +340,7 @@ end --- 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. -utilities.max = function (...) +function utilities.max (...) local input = pl.utils.pack(...) local max = table.remove(input, 1) for _, val in ipairs(input) do @@ -352,7 +352,7 @@ end --- 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. -utilities.min = function (...) +function utilities.min (...) local input = pl.utils.pack(...) local min = input[1] for _, val in ipairs(input) do @@ -372,7 +372,7 @@ end -- whereas normal LUA VMs can be cooerced. -- @tparam number input Input value. -- @treturn string Four-digit precision foating point. -utilities.debug_round = function (input) +function utilities.debug_round (input) if input > 0 then input = input + .00000000000001 end if input < 0 then input = input - .00000000000001 end return string.format("%.4f", input) @@ -383,7 +383,7 @@ end -- { 1 = "a", 2 = "b" } which can be iterated using `ipairs()` without stopping after 1. -- @tparam table items List-like table potentially with holes. -- @treturn table List like table without holes. -utilities.compress = function (items) +function utilities.compress (items) local rv = {} local max = math.max(pl.utils.unpack(pl.tablex.keys(items))) for i = 1, max do if items[i] then rv[#rv+1] = items[i] end end @@ -392,7 +392,7 @@ end --- Reverse the order of a list-like table. -- @tparam table tbl Input list-like table. -utilities.flip_in_place = function (tbl) +function utilities.flip_in_place (tbl) local tmp, j for i = 1, math.floor(#tbl / 2) do tmp = tbl[i] @@ -403,7 +403,7 @@ utilities.flip_in_place = function (tbl) end -- TODO: Before documenting, consider whether this should be private to the one existing usage. -utilities.allCombinations = function (options) +function utilities.allCombinations (options) local count = 1 for i=1,#options do count = count * options[i] end return coroutine.wrap(function() @@ -421,13 +421,13 @@ utilities.allCombinations = function (options) end -utilities.rateBadness = function(inf_bad, shortfall, spring) +function utilities.rateBadness (inf_bad, shortfall, spring) if spring == 0 then return inf_bad end local bad = math.floor(100 * math.abs(shortfall / spring) ^ 3) return math.min(inf_bad, bad) end -utilities.rationWidth = function (target, width, ratio) +function utilities.rationWidth (target, width, ratio) if ratio < 0 and width.shrink:tonumber() > 0 then target:___add(width.shrink:tonumber() * ratio) elseif ratio > 0 and width.stretch:tonumber() > 0 then @@ -444,7 +444,7 @@ end -- @tparam string pattern Pattern on which to split the input. -- @treturn function An iterator function -- @usage for str in SU.gtoke("foo-bar-baz", "-") do print(str) end -utilities.gtoke = function (string, pattern) +function utilities.gtoke (string, pattern) string = string and tostring(string) or '' pattern = pattern and tostring(pattern) or "%s+" local length = #string @@ -469,7 +469,7 @@ end --- Convert a Unicode character to its corresponding codepoint. -- @tparam string uchar A single inicode character. -- @return number The Unicode code point where uchar is encoded. -utilities.codepoint = function (uchar) +function utilities.codepoint (uchar) local seq = 0 local val = -1 for i = 1, #uchar do @@ -491,7 +491,7 @@ end --- Covert a code point to a Unicode character. -- @tparam number|string codepoint Input code point value, either as a number or a string representing the decimal value "U+NNNN" or hex value "0xFFFF". -- @treturn string The character replestened by a codepoint descriptions. -utilities.utf8charfromcodepoint = function (codepoint) +function utilities.utf8charfromcodepoint (codepoint) local val = codepoint local cp = val local hex = (cp:match("[Uu]%+(%x+)") or cp:match("0[xX](%x+)")) @@ -512,7 +512,7 @@ end -- @tparam string ustr Input string. -- @tparam string endian Either "le" or "be" depending on the enconding endedness. -- @treturn string Serious of hex encoded code points. -utilities.utf16codes = function (ustr, endian) +function utilities.utf16codes (ustr, endian) local pos = 1 return function() if pos > #ustr then @@ -550,7 +550,7 @@ end -- to split it into 1, 2, 3, or 4 byte grups matching the UTF-8 encoding. -- @tparam string str Input UTF-8 encoded string. -- @treturn table A list-like table of UTF8 strings each representing a Unicode char from the input string. -utilities.splitUtf8 = function (str) +function utilities.splitUtf8 (str) local rv = {} for _, cp in luautf8.next, str do table.insert(rv, luautf8.char(cp)) @@ -563,7 +563,7 @@ end -- more than one byte. -- @tparam string str Input string. -- @treturn string A single Unicode character. -utilities.lastChar = function (str) +function utilities.lastChar (str) local chars = utilities.splitUtf8(str) return chars[#chars] end @@ -573,7 +573,7 @@ end -- more than one byte. -- @tparam string str Input string. -- @treturn string A single Unicode character. -utilities.firstChar = function (str) +function utilities.firstChar (str) local chars = utilities.splitUtf8(str) return chars[1] end @@ -586,7 +586,7 @@ local byte, floor, reverse = string.byte, math.floor, string.reverse -- @tparam string str Input string. -- @tparam number index Index of character to return. -- @treturn string A single Unicode character. -utilities.utf8charat = function (str, index) +function utilities.utf8charat (str, index) return str:sub(index):match("([%z\1-\127\194-\244][\128-\191]*)") end @@ -597,7 +597,7 @@ end --- Encode a string to a hexidecimal replesentation. -- @tparam string str Input UTF-8 string -- @treturn string Hexidecimal replesentation of str. -utilities.hexencoded = function (str) +function utilities.hexencoded (str) local ustr = "" for i = 1, #str do ustr = ustr..string.format("%02x", byte(str, i, i+1)) @@ -608,7 +608,7 @@ end --- Decode a hexidecimal replesentation into a string. -- @tparam string str Input hexidecimal encoded string. -- @treturn string UTF-8 string. -utilities.hexdecoded = function (str) +function utilities.hexdecoded (str) if #str % 2 == 1 then SU.error("Cannot decode hex string with odd len") end local ustr = "" for i = 1, #str, 2 do @@ -640,22 +640,22 @@ end --- Convert a UTF-8 string to big-endian UTF-16. -- @tparam string str UTF-8 encoded string. -- @treturn string Big-endian UTF-16 encoded string. -utilities.utf8_to_utf16be = function (str) return utf8_to_utf16(str, "be") end +function utilities.utf8_to_utf16be (str) return utf8_to_utf16(str, "be") end --- Convert a UTF-8 string to little-endian UTF-16. -- @tparam string str UTF-8 encoded string. -- @treturn string Little-endian UTF-16 encoded string. -utilities.utf8_to_utf16le = function (str) return utf8_to_utf16(str, "le") end +function utilities.utf8_to_utf16le (str) return utf8_to_utf16(str, "le") end --- Convert a UTF-8 string to big-endian UTF-16, then encode in hex. -- @tparam string str UTF-8 encoded string. -- @treturn string Hexidecimal representation of a big-endian UTF-16 encoded string. -utilities.utf8_to_utf16be_hexencoded = function (str) return utilities.hexencoded(utilities.utf8_to_utf16be(str)) end +function utilities.utf8_to_utf16be_hexencoded (str) return utilities.hexencoded(utilities.utf8_to_utf16be(str)) end --- Convert a UTF-8 string to little-endian UTF-16, then encode in hex. -- @tparam string str UTF-8 encoded string. -- @treturn string Hexidecimal representation of a little-endian UTF-16 encoded string. -utilities.utf8_to_utf16le_hexencoded = function (str) return utilities.hexencoded(utilities.utf8_to_utf16le(str)) end +function utilities.utf8_to_utf16le_hexencoded (str) return utilities.hexencoded(utilities.utf8_to_utf16le(str)) end local utf16_to_utf8 = function (str, endianness) local bom = utf16bom(endianness) @@ -671,14 +671,14 @@ end --- Convert a big-endian UTF-16 string to UTF-8. -- @tparam string str Big-endian UTF-16 encoded string. -- @treturn string UTF-8 encoded string. -utilities.utf16be_to_utf8 = function (str) return utf16_to_utf8(str, "be") end +function utilities.utf16be_to_utf8 (str) return utf16_to_utf8(str, "be") end --- Convert a little-endian UTF-16 string to UTF-8. -- @tparam string str Little-endian UTF-16 encoded string. -- @treturn string UTF-8 encoded string. -utilities.utf16le_to_utf8 = function (str) return utf16_to_utf8(str, "le") end +function utilities.utf16le_to_utf8 (str) return utf16_to_utf8(str, "le") end -utilities.breadcrumbs = function () +function utilities.breadcrumbs () local breadcrumbs = {} setmetatable (breadcrumbs, { @@ -720,28 +720,28 @@ utilities.collatedSort = require("core.utilities.sorting") utilities.ast = require("core.utilities.ast") utilities.debugAST = utilities.ast.debug -utilities.subContent = function (content) +function utilities.subContent (content) SU.deprecated("SU.subContent", "SU.ast.subContent", "0.15.0", "0.17.0", [[ Note that the new implementation no longer introduces an id="stuff" key.]]) return utilities.ast.subContent(content) end -utilities.hasContent = function(content) +function utilities.hasContent (content) SU.deprecated("SU.hasContent", "SU.ast.hasContent", "0.15.0", "0.17.0") return SU.ast.hasContent(content) end -utilities.contentToString = function (content) +function utilities.contentToString (content) SU.deprecated("SU.contentToString", "SU.ast.contentToString", "0.15.0", "0.17.0") return SU.ast.contentToString(content) end -utilities.walkContent = function (content, action) +function utilities.walkContent (content, action) SU.deprecated("SU.walkContent", "SU.ast.walkContent", "0.15.0", "0.17.0") SU.ast.walkContent(content, action) end -utilities.stripContentPos = function (content) +function utilities.stripContentPos (content) SU.deprecated("SU.stripContentPos", "SU.ast.stripContentPos", "0.15.0", "0.17.0") return SU.ast.stripContentPos(content) end