+---[[
+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
+]]
+
+---[[
+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 occurences 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 occurences
+]]
+
+---[[
+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 Boolean indicating whether the given value occurs within table
+]]
+
+---[[
+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
+]]
+
projects / project / luci.git / commitdiff