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.
| 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? |
| patterns |
Some standard patterns |
| stdmt |
Standard meta-tables as used by other Penlight modules |
-
pack (...)
-
pack an argument list into a table.
Parameters:
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)
local a, b, c, d = utils.unpack(t)
-
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") local my_mt = {}
local my_obj = setmetatable(my_obj, my_mt)
utils.is_type(my_obj, my_mt)
-
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
-
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') local param4 = assert_arg(4,'!@#$%^&*','string',path.isdir,'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)
-
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:
See also:
Usage:
if some_condition then
return utils.raise("some condition was not met") end
-
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:
-
true or nil
-
error message
Raises:
error if filename or str aren't strings
-
readlines (filename)
-
return the contents of a file as a list of lines
Parameters:
Returns:
file contents as a table
Raises:
error if filename is not a string
-
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:
-
true if successful
-
actual return code
-
stdout output (string)
-
errout output (string)
-
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",
}
-
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")
utils.quit("Error '%s' happened", "42")
-
escape (s)
-
escape any Lua 'magic' characters in a string
Parameters:
-
split (s, re, plain, n)
-
split a string into a list of strings separated by a delimiter.
Parameters:
- s
The input string
- re
A Lua string pattern; defaults to '%s+'
- plain
don't use Lua patterns
- n
optional maximum number of splits
Returns:
a list-like table
Raises:
error if s is not a string
-
splitv (s, re)
-
split a string into a number of return values.
Parameters:
- s
the string
- re
the delimiter, default space
Returns:
n values
See also:
Usage:
first,next = splitv('jane:doe',':')
-
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:
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")) print(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", "!")) print(hello("Bye", "?"))