Module pl.utils
Generally useful routines.
 See  the Guide.
 Dependencies: pl.compat, all exported fields and functions from
 pl.compat are also available in this module.
	
	| 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? | 
	
	| patterns | Some standard patterns | 
	
	| stdmt | Standard meta-tables as used by other Penlight modules | 
    
    
    - 
    
    pack (...)
    
- 
    pack an argument list into a table.
    Parameters:Returns:
        a table with field nset to the length
 See also:
- 
    
    unpack (t[, i[, t]])
    
- 
    unpack a table and return its contents. 
 NOTE: this implementation differs from the Lua implementation in the way
 that this one DOES honor the nfield in the tablet, such that it is 'nil-safe'.
 Parameters:
        - t
         index of the last element to unpack, defaults to t.nor#t(optional)
- i
         index from which to start unpacking, defaults to 1
         (optional)
        
- t
         index of the last element to unpack, defaults to t.nor#t(optional)
 Returns:
        multiple return values from the table
     See also:Usage:local t = table.pack(nil, nil, nil, 4)
local a, b, c, d = table.unpack(t)   
local a, b, c, d = utils.unpack(t)    
- 
    
    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")   local my_mt = {}
local my_obj = setmetatable(my_obj, my_mt)
utils.is_type(my_obj, my_mt)  
    - 
    
    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
        
 
    - 
    
    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:ifvalis not the correct typeUsage:local param1 = assert_arg(1,"hello",'table')  local param4 = assert_arg(4,'!@#$%^&*','string',path.isdir,'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 stringUsage:local val = 42
local param2 = utils.assert_string(2, val)  
- 
    
    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'
        
 See also:
- 
    
    raise (err)
    
- 
    used by Penlight functions to return errors.  Its global behaviour is controlled
 by utils.on_error.
 To use this function you MUST use it in conjunction with return, since it might
 returnnil + error.Parameters:See also:Usage:if some_condition then
  return utils.raise("some condition was not met")  end
    - 
    
    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:Returns:
        file contents as a table
     Raises:error if filename is not a string
    - 
    
    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.executeor 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",
}
- 
    
    quit ([code], msg, ...)
    
- 
    error out of this program gracefully.
    Parameters:
        - code
         The exit code, defaults to -1if omitted
         (optional)
- msg
         The exit message will be sent to stderr(will be formatted with the extra parameters)
- ...
         extra arguments for message's format'
        
 See also:Usage:utils.quit(-1, "Error '%s' happened", "42")
utils.quit("Error '%s' happened", "42")  
    - 
    
    escape (s)
    
- 
    escape any Lua 'magic' characters in a string
    Parameters:
- 
    
    split (s, re, plain, n)
    
- 
    split a string into a list of strings separated by a delimiter.
    Parameters:
        - s
         The input string
        
- re
         optional A Lua string pattern; defaults to '%s+'
        
- plain
         optional If truthy don't use Lua patterns
        
- n
         optional maximum number of elements (if there are more, the last will remian un-split)
        
 Returns:
        a list-like table
     Raises:error if s is not a stringSee also:
- 
    
    splitv (s, re, plain, n)
    
- 
    split a string into a number of return values.
 Identical to split but returns multiple sub-strings instead of
 a single list of sub-strings.
    Parameters:
        - s
         the string
        
- re
         A Lua string pattern; defaults to '%s+'
        
- plain
         don't use Lua patterns
        
- n
         optional maximum number of splits
        
 Returns:
        n values
     See also:Usage:first,next = splitv('user=jane=doe','=', false, 2)
assert(first == "user")
assert(next == "jane=doe")
    - 
    
    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: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_argSee also:Usage:local function f(msg, name)
  print(msg .. " " .. name)
end
local hello = utils.bind1(f, "Hello")
print(hello("world"))     print(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_argUsage:local function f(a, b, c)
  print(a .. " " .. b .. " " .. c)
end
local hello = utils.bind1(f, "world")
print(hello("Hello", "!"))  print(hello("Bye", "?"))    
    - 
    
    set_deprecation_func (func)
    
- 
    Sets a deprecation warning function.
 An application can override this function to support proper output of
 deprecation warnings. The warnings can be generated from libraries or
 functions by calling utils.raise_deprecation. The default function
 will write to the 'warn' system (introduced in Lua 5.4, or the compatibility
 function from the compat module for earlier versions).
 Note: only applications should set/change this function, libraries should not.
     Parameters:
        - func
         a callback with signature: function(msg, trace)both arguments are strings, the latter being optional.
 See also:Usage:utils.set_deprecation_func(function(msg, trace)
  ngx.log(ngx.WARN, msg, (trace and (" " .. trace) or nil))
end)
utils.set_deprecation_func()
- 
    
    raise_deprecation (opts)
    
- 
    raises a deprecation warning.
 For options see the usage example below.
 Note: the opts.deprecated_afterfield is the last version in which
 a feature or option was NOT YET deprecated! Because when writing the code it
 is quite often not known in what version the code will land. But the last
 released version is usually known.
 Parameters:See also:Usage:warn("@on")   
function stringx.islower(str)
  raise_deprecation {
    source = "Penlight " .. utils._VERSION,                       message = "function 'islower' was renamed to 'is_lower'",     version_removed = "2.0.0",                                    deprecated_after = "1.2.3",                                   no_trace = true,                                            }
  return stringx.is_lower(str)
end