379 lines
9.7 KiB
Plaintext
379 lines
9.7 KiB
Plaintext
|
---[[
|
||
|
|
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 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
|
||
|
|
]]
|
||
|
|
|