From 42ec7286b2d36a9ba22925f816a17cb1cc2aa5ce Mon Sep 17 00:00:00 2001 From: chai Date: Sat, 30 Oct 2021 11:32:16 +0800 Subject: + Penlight --- .../Penlight/docs/libraries/pl.utils.html | 1384 ++++++++++++++++++++ 1 file changed, 1384 insertions(+) create mode 100644 Data/Libraries/Penlight/docs/libraries/pl.utils.html (limited to 'Data/Libraries/Penlight/docs/libraries/pl.utils.html') diff --git a/Data/Libraries/Penlight/docs/libraries/pl.utils.html b/Data/Libraries/Penlight/docs/libraries/pl.utils.html new file mode 100644 index 0000000..ee1773a --- /dev/null +++ b/Data/Libraries/Penlight/docs/libraries/pl.utils.html @@ -0,0 +1,1384 @@ + + + + + Penlight Documentation + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module pl.utils

+

Generally useful routines.

+

See the Guide.

+ +

Dependencies: pl.compat, all exported fields and functions from + pl.compat are also available in this module.

+ + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
pack (...)pack an argument list into a table.
unpack (t[, i[, t]])unpack a table and return its contents.
printf (fmt, ...)print an arbitrary number of arguments using a format.
fprintf (f, fmt, ...)write an arbitrary number of arguments to a file using a format.
import (t, T)take a table and 'inject' it into the local namespace.
choose (cond, value1, value2)return either of two values, depending on a condition.
array_tostring (t[, temp[, tostr]])convert an array of values to strings.
is_type (obj, tp)is the object of the specified type?
+

Tables

+ + + + + + + + + +
patternsSome standard patterns
stdmtStandard meta-tables as used by other Penlight modules
+

Error handling

+ + + + + + + + + + + + + + + + + + + + + +
assert_arg (n, val, tp, verify, msg, lev)assert that the given argument is in fact of the correct type.
function_arg (idx, f, msg)process a function argument.
assert_string (n, val)assert the common case that the argument is a string.
on_error (mode)control the error strategy used by Penlight.
raise (err)used by Penlight functions to return errors.
+

File handling

+ + + + + + + + + + + + + +
readfile (filename, is_bin)return the contents of a file as a string
writefile (filename, str, is_bin)write a string to a file
readlines (filename)return the contents of a file as a list of lines
+

OS functions

+ + + + + + + + + + + + + +
executeex (cmd, bin)execute a shell command and return the output.
quote_arg (argument)Quote and escape an argument of a command.
quit ([code], msg, ...)error out of this program gracefully.
+

String functions

+ + + + + + + + + + + + + +
escape (s)escape any Lua 'magic' characters in a string
split (s, re, plain, n)split a string into a list of strings separated by a delimiter.
splitv (s, re, plain, n)split a string into a number of return values.
+

Functional

+ + + + + + + + + + + + + + + + + + + + + +
memoize (func)'memoize' a function (cache returned value for next call).
add_function_factory (mt, fun)associate a function factory with a type.
string_lambda (lf)an anonymous function as a string.
bind1 (fn, p)bind the first argument of the function to a value.
bind2 (fn, p)bind the second argument of the function to a value.
+

Deprecation

+ + + + + + + + + +
set_deprecation_func (func)Sets a deprecation warning function.
raise_deprecation (opts)raises a deprecation warning.
+ +
+
+ + +

Functions

+ +
+
+ + pack (...) +
+
+ pack an argument list into a table. + + +

Parameters:

+
    +
  • ... + any arguments +
    • +
+ +

Returns:

+
    + + a table with field n set to the length +
+ + +

See also:

+ + + +
+
+ + unpack (t[, i[, t]]) +
+
+ unpack a table and return its contents.

+ +

NOTE: this implementation differs from the Lua implementation in the way + that this one DOES honor the n field in the table t, such that it is 'nil-safe'. + + +

Parameters:

+
    +
  • t + index of the last element to unpack, defaults to t.n or #t + (optional) +
    • +
  • i + index from which to start unpacking, defaults to 1 + (optional) +
    • +
  • t + index of the last element to unpack, defaults to t.n or #t + (optional) +
    • +
+ +

Returns:

+
    + + multiple return values from the table +
+ + +

See also:

+ + +

Usage:

+
    + 
    local t = table.pack(nil, nil, nil, 4)
+local a, b, c, d = table.unpack(t)   -- this unpack is NOT nil-safe, so d == nil
+
+local a, b, c, d = utils.unpack(t)   -- this is nil-safe, so d == 4
    +
+ +
+
+ + printf (fmt, ...) +
+
+ print an arbitrary number of arguments using a format. + Output will be sent to stdout. + + +

Parameters:

+
    +
  • fmt + The format (see string.format) +
    • +
  • ... + Extra arguments for format +
    • +
+ + + + + +
+
+ + fprintf (f, fmt, ...) +
+
+ write an arbitrary number of arguments to a file using a format. + + +

Parameters:

+
    +
  • f + File handle to write to. +
    • +
  • fmt + The format (see string.format). +
    • +
  • ... + Extra arguments for format +
    • +
+ + + + + +
+
+ + import (t, T) +
+
+ take a table and 'inject' it into the local namespace. + + +

Parameters:

+
    +
  • t + The table (table), or module name (string), defaults to this utils module table +
    • +
  • T + An optional destination table (defaults to callers environment) +
    • +
+ + + + + +
+
+ + choose (cond, value1, value2) +
+
+ return either of two values, depending on a condition. + + +

Parameters:

+
    +
  • cond + A condition +
    • +
  • value1 + Value returned if cond is truthy +
    • +
  • value2 + Value returned if cond is falsy +
    • +
+ + + + + +
+
+ + array_tostring (t[, temp[, tostr]]) +
+
+ convert an array of values to strings. + + +

Parameters:

+
    +
  • t + a list-like table +
    • +
  • temp + (table) buffer to use, otherwise allocate + (optional) +
    • +
  • tostr + custom tostring function, called with (value,index). Defaults to tostring. + (optional) +
    • +
+ +

Returns:

+
    + + the converted buffer +
+ + + + +
+
+ + is_type (obj, tp) +
+
+ is the object of the specified type? + If the type is a string, then use type, otherwise compare with metatable + + +

Parameters:

+
    +
  • obj + An object to check +
    • +
  • tp + String of what type it should be +
    • +
+ +

Returns:

+
    + + boolean +
+ + + +

Usage:

+
    + 
    utils.is_type("hello world", "string")   --> true
+-- or check metatable
+local my_mt = {}
+local my_obj = setmetatable(my_obj, my_mt)
+utils.is_type(my_obj, my_mt)  --> true
    +
+ +
+
+

Tables

+ +
+
+ + patterns +
+
+ Some standard patterns + + +

Fields:

+
    +
  • FLOAT + floating point number +
    • +
  • INTEGER + integer number +
    • +
  • IDEN + identifier +
    • +
  • FILE + file +
    • +
+ + + + + +
+
+ + stdmt +
+
+ Standard meta-tables as used by other Penlight modules + + +

Fields:

+
    +
  • List + the List metatable +
    • +
  • Map + the Map metatable +
    • +
  • Set + the Set metatable +
    • +
  • MultiMap + the MultiMap metatable +
    • +
+ + + + + +
+
+

Error handling

+ +
+
+ + assert_arg (n, val, tp, verify, msg, lev) +
+
+ assert that the given argument is in fact of the correct type. + + +

Parameters:

+
    +
  • n + argument index +
    • +
  • val + the value +
    • +
  • tp + the type +
    • +
  • verify + an optional verification function +
    • +
  • msg + an optional custom message +
    • +
  • lev + optional stack position for trace, default 2 +
    • +
+ +

Returns:

+
    + + the validated value +
+ +

Raises:

+ if val is not the correct type + + +

Usage:

+
    + 
    local param1 = assert_arg(1,"hello",'table')  --> error: argument 1 expected a 'table', got a 'string'
+local param4 = assert_arg(4,'!@#$%^&*','string',path.isdir,'not a directory')
+     --> error: argument 4: '!@#$%^&*' not a directory
    +
+ +
+
+ + function_arg (idx, f, msg) +
+
+ process a function argument. + This is used throughout Penlight and defines what is meant by a function: + Something that is callable, or an operator string as defined by pl.operator, + such as '>' or '#'. If a function factory has been registered for the type, it will + be called to get the function. + + +

Parameters:

+
    +
  • idx + argument index +
    • +
  • f + a function, operator string, or callable object +
    • +
  • msg + optional error message +
    • +
+ +

Returns:

+
    + + a callable +
+ +

Raises:

+ if idx is not a number or if f is not callable + + + +
+
+ + assert_string (n, val) +
+
+ assert the common case that the argument is a string. + + +

Parameters:

+
    +
  • n + argument index +
    • +
  • val + a value that must be a string +
    • +
+ +

Returns:

+
    + + the validated value +
+ +

Raises:

+ val must be a string + + +

Usage:

+
    + 
    local val = 42
+local param2 = utils.assert_string(2, val) --> error: argument 2 expected a 'string', got a 'number'
    +
+ +
+
+ + on_error (mode) +
+
+ +

control the error strategy used by Penlight. + This is a global setting that controls how utils.raise behaves:

+ +
    +
  • 'default': return nil + error (this is the default)
    • +
  • 'error': throw a Lua error
    • +
  • 'quit': exit the program
    • +
+ + + + +

Parameters:

+
    +
  • mode + either 'default', 'quit' or 'error' +
    • +
+ + + +

See also:

+ + + +
+
+ + raise (err) +
+
+ used by Penlight functions to return errors. Its global behaviour is controlled + by utils.on_error. + To use this function you MUST use it in conjunction with return, since it might + return nil + error. + + +

Parameters:

+
    +
  • err + the error string. +
    • +
+ + + +

See also:

+ + +

Usage:

+
    + 
    if some_condition then
+  return utils.raise("some condition was not met")  -- MUST use 'return'!
+end
    +
+ +
+
+

File handling

+ +
+
+ + readfile (filename, is_bin) +
+
+ return the contents of a file as a string + + +

Parameters:

+
    +
  • filename + The file path +
    • +
  • is_bin + open in binary mode +
    • +
+ +

Returns:

+
    + + file contents +
+ + + + +
+
+ + writefile (filename, str, is_bin) +
+
+ write a string to a file + + +

Parameters:

+
    +
  • filename + The file path +
    • +
  • str + The string +
    • +
  • is_bin + open in binary mode +
    • +
+ +

Returns:

+
    +
  1. + true or nil
    2. +
  2. + error message
    3. +
+ +

Raises:

+ error if filename or str aren't strings + + + +
+
+ + readlines (filename) +
+
+ return the contents of a file as a list of lines + + +

Parameters:

+
    +
  • filename + The file path +
    • +
+ +

Returns:

+
    + + file contents as a table +
+ +

Raises:

+ error if filename is not a string + + + +
+
+

OS functions

+ +
+
+ + executeex (cmd, bin) +
+
+ execute a shell command and return the output. + This function redirects the output to tempfiles and returns the content of those files. + + +

Parameters:

+
    +
  • cmd + a shell command +
    • +
  • bin + boolean, if true, read output as binary file +
    • +
+ +

Returns:

+
    +
  1. + true if successful
    2. +
  2. + actual return code
    3. +
  3. + stdout output (string)
    4. +
  4. + errout output (string)
    5. +
+ + + + +
+
+ + quote_arg (argument) +
+
+ Quote and escape an argument of a command. + Quotes a single (or list of) argument(s) of a command to be passed + to os.execute, pl.utils.execute or pl.utils.executeex. + + +

Parameters:

+
    +
  • argument + (string or table/list) the argument to quote. If a list then + all arguments in the list will be returned as a single string quoted. +
    • +
+ +

Returns:

+
    + + quoted and escaped argument. +
+ + + +

Usage:

+
    + 
    local options = utils.quote_arg {
+    "-lluacov",
+    "-e",
+    "utils = print(require('pl.utils')._VERSION",
+}
+-- returns: -lluacov -e 'utils = print(require('\''pl.utils'\'')._VERSION'
    +
+ +
+
+ + quit ([code], msg, ...) +
+
+ error out of this program gracefully. + + +

Parameters:

+
    +
  • code + The exit code, defaults to -1 if omitted + (optional) +
    • +
  • msg + The exit message will be sent to stderr (will be formatted with the extra parameters) +
    • +
  • ... + extra arguments for message's format' +
    • +
+ + + +

See also:

+ + +

Usage:

+
    + 
    utils.quit(-1, "Error '%s' happened", "42")
+-- is equivalent to
+utils.quit("Error '%s' happened", "42")  --> Error '42' happened
    +
+ +
+
+

String functions

+ +
+
+ + escape (s) +
+
+ escape any Lua 'magic' characters in a string + + +

Parameters:

+
    +
  • s + The input string +
    • +
+ + + + + +
+
+ + split (s, re, plain, n) +
+
+ split a string into a list of strings separated by a delimiter. + + +

Parameters:

+
    +
  • s + The input string +
    • +
  • re + optional A Lua string pattern; defaults to '%s+' +
    • +
  • plain + optional If truthy don't use Lua patterns +
    • +
  • n + optional maximum number of elements (if there are more, the last will remian un-split) +
    • +
+ +

Returns:

+
    + + a list-like table +
+ +

Raises:

+ error if s is not a string + +

See also:

+ + + +
+
+ + splitv (s, re, plain, n) +
+
+ split a string into a number of return values. + Identical to split but returns multiple sub-strings instead of + a single list of sub-strings. + + +

Parameters:

+
    +
  • s + the string +
    • +
  • re + A Lua string pattern; defaults to '%s+' +
    • +
  • plain + don't use Lua patterns +
    • +
  • n + optional maximum number of splits +
    • +
+ +

Returns:

+
    + + n values +
+ + +

See also:

+ + +

Usage:

+
    + 
    first,next = splitv('user=jane=doe','=', false, 2)
+assert(first == "user")
+assert(next == "jane=doe")
    +
+ +
+
+

Functional

+ +
+
+ + memoize (func) +
+
+ 'memoize' a function (cache returned value for next call). + This is useful if you have a function which is relatively expensive, + but you don't know in advance what values will be required, so + building a table upfront is wasteful/impossible. + + +

Parameters:

+
    +
  • func + a function of at least one argument +
    • +
+ +

Returns:

+
    + + a function with at least one argument, which is used as the key. +
+ + + + +
+
+ + add_function_factory (mt, fun) +
+
+ associate a function factory with a type. + A function factory takes an object of the given type and + returns a function for evaluating it + + +

Parameters:

+
    +
  • mt + tab + metatable +
    • +
  • fun + func + a callable that returns a function +
    • +
+ + + + + +
+
+ + string_lambda (lf) +
+
+ an anonymous function as a string. This string is either of the form + '|args| expression' or is a function of one argument, '_' + + +

Parameters:

+
    +
  • lf + function as a string +
    • +
+ +

Returns:

+
    + + a function +
+ + + +

Usage:

+
    + 
    string_lambda '|x|x+1' (2) == 3
+string_lambda '_+1' (2) == 3
    +
+ +
+
+ + bind1 (fn, p) +
+
+ bind the first argument of the function to a value. + + +

Parameters:

+
    +
  • fn + a function of at least two values (may be an operator string) +
    • +
  • p + a value +
    • +
+ +

Returns:

+
    + + a function such that f(x) is fn(p,x) +
+ +

Raises:

+ same as function_arg + +

See also:

+ + +

Usage:

+
    + 
    local function f(msg, name)
+  print(msg .. " " .. name)
+end
+
+local hello = utils.bind1(f, "Hello")
+
+print(hello("world"))     --> "Hello world"
+print(hello("sunshine"))  --> "Hello sunshine"
    +
+ +
+
+ + bind2 (fn, p) +
+
+ bind the second argument of the function to a value. + + +

Parameters:

+
    +
  • fn + a function of at least two values (may be an operator string) +
    • +
  • p + a value +
    • +
+ +

Returns:

+
    + + a function such that f(x) is fn(x,p) +
+ +

Raises:

+ same as function_arg + + +

Usage:

+
    + 
    local function f(a, b, c)
+  print(a .. " " .. b .. " " .. c)
+end
+
+local hello = utils.bind1(f, "world")
+
+print(hello("Hello", "!"))  --> "Hello world !"
+print(hello("Bye", "?"))    --> "Bye world ?"
    +
+ +
+
+

Deprecation

+ +
+
+ + set_deprecation_func (func) +
+
+ Sets a deprecation warning function. + An application can override this function to support proper output of + deprecation warnings. The warnings can be generated from libraries or + functions by calling utils.raise_deprecation. The default function + will write to the 'warn' system (introduced in Lua 5.4, or the compatibility + function from the compat module for earlier versions).

+ +

Note: only applications should set/change this function, libraries should not. + + +

Parameters:

+
    +
  • func + a callback with signature: function(msg, trace) both arguments are strings, the latter being optional. +
    • +
+ + + +

See also:

+ + +

Usage:

+
    + 
    -- write to the Nginx logs with OpenResty
+utils.set_deprecation_func(function(msg, trace)
+  ngx.log(ngx.WARN, msg, (trace and (" " .. trace) or nil))
+end)
+
+-- disable deprecation warnings
+utils.set_deprecation_func()
    +
+ +
+
+ + raise_deprecation (opts) +
+
+ raises a deprecation warning. + For options see the usage example below.

+ +

Note: the opts.deprecated_after field is the last version in which + a feature or option was NOT YET deprecated! Because when writing the code it + is quite often not known in what version the code will land. But the last + released version is usually known. + + +

Parameters:

+
    +
  • opts + options table +
    • +
+ + + +

See also:

+ + +

Usage:

+
    + 
    warn("@on")   -- enable Lua warnings, they are usually off by default
+
+function stringx.islower(str)
+  raise_deprecation {
+    source = "Penlight " .. utils._VERSION,                   -- optional
+    message = "function 'islower' was renamed to 'is_lower'", -- required
+    version_removed = "2.0.0",                                -- optional
+    deprecated_after = "1.2.3",                               -- optional
+    no_trace = true,                                          -- optional
+  }
+  return stringx.is_lower(str)
+end
+-- output: "[Penlight 1.9.2] function 'islower' was renamed to 'is_lower' (deprecated after 1.2.3, scheduled for removal in 2.0.0)"
    +
+ +
+
+ + +
+
+
+generated by LDoc 1.4.6 +
+
+ + -- cgit v1.1-26-g67d0