path: root/libs/luci-lib-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.

This is just a compatibility wrapper for luci.xml.padata()

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

---[[
Decode an URL-encoded string - optionally decoding the "+" sign to space.

@class				function
@name				urldecode
@param str			Input string in x-www-urlencoded format
@param decode_plus	Decode "+" signs to spaces if true (optional)
@return				The decoded string
@see				urlencode
]]

---[[
URL-encode given string.

@class				function
@name				urlencode
@param str			String to encode
@return				String containing the encoded data
@see				urldecode
]]

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

This is just a compatibility wrapper for luci.xml.striptags()

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

---[[
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
nterpreted 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 iterator 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
]]

---[[
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 unnecessary 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
]]