path: root/modules/luci-base/luasrc/util.luadoc

---[[
LuCI utility functions.
]]
module "luci.util"

---[[
Create a Class object (Python-style object model).

The class object can be instantiated by calling itself.
Any class functions or shared parameters can be attached to this object.
Attaching a table to the class object makes this table shared between
all instances of this class. For object parameters use the __init__ function.
Classes can inherit member functions and values from a base class.
Class can be instantiated by calling them. All parameters will be passed
to the __init__ function of this class - if such a function exists.
The __init__ function must be used to set any object parameters that are not shared
with other objects of this class. Any return values will be ignored.
@class function
@name class
@param base	The base class to inherit from (optional)
@return		A class object
@see			instanceof
@see			clone
]]

---[[
Test whether the given object is an instance of the given class.

@class function
@name instanceof
@param object	Object instance
@param class		Class object to test against
@return			Boolean indicating whether the object is an instance
@see				class
@see				clone
]]

---[[
Create a new or get an already existing thread local store associated with

the current active coroutine. A thread local store is private a table object
whose values can't be accessed from outside of the running coroutine.
@class function
@name threadlocal
@return	Table value representing the corresponding thread local store
]]

---[[
Write given object to stderr.

@class function
@name perror
@param obj	Value to write to stderr
@return		Boolean indicating whether the write operation was successful
]]

---[[
Recursively dumps a table to stdout, useful for testing and debugging.

@class function
@name dumptable
@param t	Table value to dump
@param maxdepth	Maximum depth
@return	Always nil
]]

---[[
Create valid XML PCDATA from given string.

@class function
@name pcdata
@param value	String value containing the data to escape
@return		String value containing the escaped data
]]

---[[
Strip HTML tags from given string.

@class function
@name striptags
@param value	String containing the HTML text
@return	String with HTML tags stripped of
]]

---[[
Safely quote value for use in shell commands.

@class function
@name shellquote
@param value  String containing the value to quote
@return Single-quote enclosed string with embedded quotes escaped
]]

---[[
Splits given string on a defined separator sequence and return a table

containing the resulting substrings. The optional max parameter specifies
the number of bytes to process, regardless of the actual length of the given
string. The optional last parameter, regex, specifies whether the separator
sequence is interpreted as regular expression.
@class function
@name split
@param str		String value containing the data to split up
@param pat		String with separator pattern (optional, defaults to "\n")
@param max		Maximum times to split (optional)
@param regex 	Boolean indicating whether to interpret the separator
--					pattern as regular expression (optional, default is false)
@return			Table containing the resulting substrings
]]

---[[
Remove leading and trailing whitespace from given string value.

@class function
@name trim
@param str	String value containing whitespace padded data
@return		String value with leading and trailing space removed
]]

---[[
Count the occurrences of given substring in given string.

@class function
@name cmatch
@param str		String to search in
@param pattern	String containing pattern to find
@return			Number of found occurrences
]]

---[[
Return a matching iterator for the given value. The iterator will return

one token per invocation, the tokens are separated by whitespace. If the
input value is a table, it is transformed into a string first. A nil value
will result in a valid interator which aborts with the first invocation.
@class function
@name imatch
@param val		The value to scan (table, string or nil)
@return			Iterator which returns one token per call
]]

---[[
Parse certain units from the given string and return the canonical integer

value or 0 if the unit is unknown. Upper- or lower case is irrelevant.
Recognized units are:
--	o "y"	- one year   (60*60*24*366)
 o "m"	- one month  (60*60*24*31)
 o "w"	- one week   (60*60*24*7)
 o "d"	- one day    (60*60*24)
 o "h"	- one hour	 (60*60)
 o "min"	- one minute (60)
 o "kb"  - one kilobyte (1024)
 o "mb"	- one megabyte (1024*1024)
 o "gb"	- one gigabyte (1024*1024*1024)
 o "kib" - one si kilobyte (1000)
 o "mib"	- one si megabyte (1000*1000)
 o "gib"	- one si gigabyte (1000*1000*1000)
@class function
@name parse_units
@param ustr	String containing a numerical value with trailing unit
@return		Number containing the canonical value
]]

---[[
Appends numerically indexed tables or single objects to a given table.

@class function
@name append
@param src	Target table
@param ...	Objects to insert
@return		Target table
]]

---[[
Combines two or more numerically indexed tables and single objects into one table.

@class function
@name combine
@param tbl1	Table value to combine
@param tbl2	Table value to combine
@param ...	More tables to combine
@return		Table value containing all values of given tables
]]

---[[
Checks whether the given table contains the given value.

@class function
@name contains
@param table	Table value
@param value	Value to search within the given table
@return		number indicating the first index at which the given value occurs
--			within table or false.
]]

---[[
Update values in given table with the values from the second given table.

Both table are - in fact - merged together.
@class function
@name update
@param t			Table which should be updated
@param updates	Table containing the values to update
@return			Always nil
]]

---[[
Retrieve all keys of given associative table.

@class function
@name keys
@param t	Table to extract keys from
@return	Sorted table containing the keys
]]

---[[
Clones the given object and return it's copy.

@class function
@name clone
@param object	Table value to clone
@param deep		Boolean indicating whether to do recursive cloning
@return			Cloned table value
]]

---[[
Create a dynamic table which automatically creates subtables.

@class function
@name dtable
@return	Dynamic Table
]]

---[[
Recursively serialize given data to lua code, suitable for restoring

with loadstring().
@class function
@name serialize_data
@param val	Value containing the data to serialize
@return		String value containing the serialized code
@see			restore_data
@see			get_bytecode
]]

---[[
Restore data previously serialized with serialize_data().

@class function
@name restore_data
@param str	String containing the data to restore
@return		Value containing the restored data structure
@see			serialize_data
@see			get_bytecode
]]

---[[
Return the current runtime bytecode of the given data. The byte code

will be stripped before it is returned.
@class function
@name get_bytecode
@param val	Value to return as bytecode
@return		String value containing the bytecode of the given data
]]

---[[
Strips unnescessary lua bytecode from given string. Information like line

numbers and debugging numbers will be discarded. Original version by
Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
@class function
@name strip_bytecode
@param code	String value containing the original lua byte code
@return		String value containing the stripped lua byte code
]]

---[[
Return a key, value iterator which returns the values sorted according to

the provided callback function.
@class function
@name spairs
@param t	The table to iterate
@param f A callback function to decide the order of elements
@return	Function value containing the corresponding iterator
]]

---[[
Return a key, value iterator for the given table.

The table pairs are sorted by key.
@class function
@name kspairs
@param t	The table to iterate
@return	Function value containing the corresponding iterator
]]

---[[
Return a key, value iterator for the given table.

The table pairs are sorted by value.
@class function
@name vspairs
@param t	The table to iterate
@return	Function value containing the corresponding iterator
]]

---[[
Test whether the current system is operating in big endian mode.

@class function
@name bigendian
@return	Boolean value indicating whether system is big endian
]]

---[[
Execute given commandline and gather stdout.

@class function
@name exec
@param command	String containing command to execute
@return			String containing the command's stdout
]]

---[[
Return a line-buffered iterator over the output of given command.

@class function
@name execi
@param command	String containing the command to execute
@return			Iterator
]]

---[[
Issue an ubus call.

@class function
@name ubus
@param object		String containing the ubus object to call
@param method		String containing the ubus method to call
@param values		Table containing the values to pass
@return			Table containin the ubus result
]]

---[[
Convert data structure to JSON

@class function
@name serialize_json
@param data		The data to serialize
@param writer	A function to write a chunk of JSON data (optional)
@return			String containing the JSON if called without write callback
]]

---[[
Returns the absolute path to LuCI base directory.

@class function
@name libpath
@return		String containing the directory path
]]

---[[
This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function

@class function
@name coxpcall
@param f		Lua function to be called protected
@param err	Custom error handler
@param ...	Parameters passed to the function
@return		A boolean whether the function call succeeded and the return
--				values of either the function or the error handler
]]

---[[
This is a coroutine-safe drop-in replacement for Lua's "pcall"-function

@class function
@name copcall
@param f		Lua function to be called protected
@param ...	Parameters passed to the function
@return		A boolean whether the function call succeeded and the returns
--				values of the function or the error object
]]