diff options
Diffstat (limited to 'modules/luci-base/luasrc/util.luadoc')
| -rw-r--r-- | modules/luci-base/luasrc/util.luadoc | 386 |
1 files changed, 210 insertions, 176 deletions
diff --git a/modules/luci-base/luasrc/util.luadoc b/modules/luci-base/luasrc/util.luadoc index 79a17a228..19c8010df 100644 --- a/modules/luci-base/luasrc/util.luadoc +++ b/modules/luci-base/luasrc/util.luadoc @@ -15,135 +15,164 @@ 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 + +@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 ]] ---[[ 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 +@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 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 +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 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 +@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) @@ -156,232 +185,237 @@ Recognized units are: 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 number indicating the first index at which the given value occurs --- within table or false. +@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 ]] |