# 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.
array_tostring (t, temp, tostr) | convert an array of values to strings.
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:

  utils.fprintf
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

  ### Returns:

  n values

  ### See also:

  split

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

  func.bind1
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

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

  utils.raise
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:

  utils.on_error
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](http://lua-users.org/lists/lua-l/2010-06/msg00313.html)

  ### 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.3 Last updated Tue, 18 Aug 2015 11:21:53 +0200