Move inline documentation into separate files.

Signed-off-by: Jo-Philipp Wich <jow@openwrt.org>

1 files changed, 378 insertions, 0 deletions

diff --git a/modules/luci-base/luasrc/util.luadoc b/modules/luci-base/luasrc/util.luadoc
new file mode 100644
index 000000000..1c09b7a9a
--- /dev/null
+++ b/modules/luci-base/luasrc/util.luadoc
@@ -0,0 +1,378 @@
+---[[
+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
+]]
+