Module `pl.utils`

Generally useful routines.

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

patterns	Some standard patterns
stdmt	Standard 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:

n

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

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'

Parameters:

err the error string.

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:

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:

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:

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",
}
-- 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'

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

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

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

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.

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

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)"

Penlight

Contents

Libraries

Classes

Manual

Examples

Module pl.utils

Functions

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Usage:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Tables

Fields:

Fields:

Error handling

Parameters:

Returns:

Raises:

Usage:

Parameters:

Returns:

Raises:

Parameters:

Returns:

Raises:

Usage:

Parameters:

See also:

Parameters:

See also:

Usage:

File handling

Parameters:

Returns:

Parameters:

Returns:

Raises:

Parameters:

Returns:

Raises:

OS functions

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

See also:

Usage:

String functions

Parameters:

Parameters:

Returns:

Raises:

See also:

Parameters:

Returns:

See also:

Usage:

Functional

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Usage:

Parameters:

Module `pl.utils`