Module pl.utils

Generally useful routines.

See the Guide.

Functions

quit (code, ...) end this program gracefully.
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.
escape (s) escape any ‘magic’ characters in a string
choose (cond, value1, value2) return either of two values, depending on a condition.
readfile (filename, is_bin) return the contents of a file as a string
writefile (filename, str) write a string to a file
readlines (filename) return the contents of a file as a list of lines
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 values.
execute (cmd) execute a shell command.
memoize (func) ‘memoize’ a function (cache returned value for next call).
is_callable (obj) is the object either a function or a callable object?.
is_type (obj, tp) is the object of the specified type?.
type (obj) a string representation of a type.
is_integer (x) is this number an integer?
add_function_factory (mt, fun) associate a function factory with a type.
string_lambda (lf) an anonymous function as a string.
function_arg (idx, f, msg) process a function argument.
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.
assert_arg (n, val, tp, verify, msg, lev) assert that the given argument is in fact of the correct type.
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.
load (code, name, mode, env) load a code string or bytecode chunk.

Lua 5.2 Compatible Functions

table.pack (...) pack an argument list into a table.
package.searchpath (mod, path) return the full path where a Lua module name would be matched.


Functions

quit (code, ...)
end this program gracefully.

Parameters:

  • code: The exit code or a message to be printed
  • ...: extra arguments for message’s format'

see also:

printf (fmt, ...)
print an arbitrary number of arguments using a format.

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
  • T: An optional destination table (defaults to callers environment)
escape (s)
escape any ‘magic’ characters in a string

Parameters:

  • s: The input string
choose (cond, value1, value2)
return either of two values, depending on a condition.

Parameters:

  • cond: A condition
  • value1: Value returned if cond is true
  • value2: Value returned if cond is false (can be optional)
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)
write a string to a file

Parameters:

  • filename: The file path
  • str: The string

Returns:

  1. true or nil
  2. 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:

errror if filename is not a 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 values.

Parameters:

  • s: the string
  • re: the delimiter, default space

Usage:

    first,next = splitv('jane:doe',':')

Returns:

    n values

see also:

execute (cmd)
execute a shell command. This is a compatibility function that returns the same for Lua 5.1 and Lua 5.2

Parameters:

  • cmd: a shell command

Returns:

  1. true if successful
  2. actual return code
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.
is_callable (obj)
is the object either a function or a callable object?.

Parameters:

  • obj: Object to check.
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
type (obj)
a string representation of a type. For tables with metatables, we assume that the metatable has a _name field. Knows about Lua file objects.

Parameters:

  • obj: an object

Returns:

    a string like ‘number’, ‘table’ or ‘List’
is_integer (x)
is this number an integer?

Parameters:

  • x: a number

Raises:

error if x is not a number
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: metatable
  • fun: 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

Usage:

  • string_lambda '|x|x+1' (2) == 3
  • string_lambda '_+1 (2) == 3

Returns:

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

see also:

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:

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
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 verfication function
  • msg: an optional custom message
  • lev: optional stack position for trace, default 2

Usage:

  • assert_arg(1,t,'table')
  • assert_arg(n,val,'string',path.isdir,'not a directory')

Raises:

if the argument n is not the correct type
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

Raises:

val must be a string
on_error (mode)
control the error strategy used by Penlight. Controls how utils.raise works; the default is for it to return nil and the error string, but if the mode is ‘error’ then it will throw an error. If mode is ‘quit’ it will immediately terminate 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

Parameters:

  • err: the error string.

see also:

load (code, name, mode, env)
load a code string or bytecode chunk.

Parameters:

  • code: Lua code as a string or bytecode
  • name: for source errors
  • mode: kind of chunk, ’t' for text, ‘b’ for bytecode, ‘bt’ for all (default)
  • env: the environment for the new chunk (default nil)

Returns:

  1. compiled chunk
  2. error message (chunk is nil)

Lua 5.2 Compatible Functions

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

Parameters:

  • ...: any arguments

Returns:

  1. a table with field n set to the length
  2. the length
package.searchpath (mod, path)
return the full path where a Lua module name would be matched.

Parameters:

  • mod: module name, possibly dotted
  • path: a path in the same form as package.path or package.cpath

see also:

generated by LDoc 1.2