diff options
Diffstat (limited to 'libs/luci-lib-base/luasrc/util.luadoc')
| -rw-r--r-- | libs/luci-lib-base/luasrc/util.luadoc | 419 |
1 files changed, 419 insertions, 0 deletions
diff --git a/libs/luci-lib-base/luasrc/util.luadoc b/libs/luci-lib-base/luasrc/util.luadoc new file mode 100644 index 0000000000..3168d9c220 --- /dev/null +++ b/libs/luci-lib-base/luasrc/util.luadoc @@ -0,0 +1,419 @@ +---[[ +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 +]] + |