---[[
LuCI utility functions.
-
-module "luci.util"
]]
+module "luci.util"
---[[
Create a Class object (Python-style object model).
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
+
+@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
+@class function
+@name instanceof
+@param object Object instance
@param class Class object to test against
-@return Boolean indicating whether the object is an instance
+@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.
-the current active coroutine. A thread local store is private a table object
+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
+
+@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
+@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
+@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
+@class function
+@name pcdata
+@param value String value containing the data to escape
+@return String value containing the escaped data
+]]
+
+---[[
+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.
-@class function
-@name striptags
-@param value String containing the HTML text
-@return String with HTML tags stripped of
+@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
+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
+]]
-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
+---[[
+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
+@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
+@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.
+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 occurences
+@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
+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.
-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
+@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.
-value or 0 if the unit is unknown. Upper- or lower case is irrelevant.
+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 "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
+
+@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
+@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
+@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
+@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
+
+@class function
+@name update
@param t Table which should be updated
-@param updates Table containing the values to update
-@return Always nil
+@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
+@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
+@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
+@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
+
+@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
+@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
+
+@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
+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)
-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
+@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
+
+@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
+
+@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
+
+@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
+@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
+@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
+@class function
+@name execi
+@param command String containing the command to execute
+@return Iterator
]]
---[[
Issue an ubus call.
-@class function
-@name ubus
+@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
+@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
+@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
+@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
+@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
+@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 / blobdiff