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

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

Usage:

first,next = splitv('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 ?"

Penlight

Contents

Libraries

Classes

Manual

Examples

Module pl.utils

Functions

Tables

Error handling

File handling

OS functions

String functions

Functional

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:

Parameters:

Returns:

See also:

Usage:

Functional

Parameters:

Module `pl.utils`