Module pl.utils

Generally useful routines.

See the Guide.

Functions

quit (code, msg, ...) 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) 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?.
function_arg (idx, f, msg) process a function argument.
bind1 (fn, p) bind the first 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.

Lua 5.2 Compatible Functions

load (code, name, mode, env) load a code string or bytecode chunk.
table.pack (...) pack an argument list into a table.


Functions

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

Parameters:

  • code: The exit code
  • msg: 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
readlines (filename)
return the contents of a file as a list of lines

Parameters:

  • filename: The file path

Returns:

    file contents as a table
split (s, re)
split a string into a list of strings separated by a delimiter.

Parameters:

  • s: The input string
  • re: A regular expression; defaults to spaces

Returns:

    a list-like table
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
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 '#'.

Parameters:

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

Returns:

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

see also:

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')
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
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:

Lua 5.2 Compatible Functions

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