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, is_bin) 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.
array_tostring (t, temp, tostr) convert an array of values to strings.
quote_arg (argument) Quote an argument of a command.
executeex (cmd, bin) execute a shell command and return the output.
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.
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.
is_type (obj, tp) is the object of the specified type?.
load (code, name, mode, env) load a code string or bytecode chunk.
getfenv (f) Get environment of a function.
setfenv (f, env) Set environment of a function
execute (cmd) execute a shell command.


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, is_bin)
write a string to a file

Parameters:

  • filename The file path
  • str The string
  • is_bin open in binary mode

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

Returns:

    n values

See also:

Usage:

    first,next = splitv('jane:doe',':')
array_tostring (t, temp, tostr)
convert an array of values to strings.

Parameters:

  • t a list-like table
  • temp buffer to use, otherwise allocate
  • tostr custom tostring function, called with (value,index). Otherwise use tostring

Returns:

    the converted buffer
quote_arg (argument)
Quote an argument of a command. Quotes a single argument of a command to be passed to os.execute, pl.utils.execute or pl.utils.executeex.

Parameters:

  • argument string the argument.

Returns:

    quoted argument.
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:

  1. true if successful
  2. actual return code
  3. stdout output (string)
  4. errout output (string)
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
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
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 verification function
  • msg an optional custom message
  • lev optional stack position for trace, default 2

Raises:

if the argument n is not the correct type

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

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:

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
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)
getfenv (f)
Get environment of a function. With Lua 5.2, may return nil for a function with no global references! Based on code by Sergey Rozhenko

Parameters:

  • f a function or a call stack reference
setfenv (f, env)
Set environment of a function

Parameters:

  • f a function or a call stack reference
  • env a table that becomes the new environment of f
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
generated by LDoc 1.4.4 Last updated 2016-08-14 19:25:18