Move inline documentation into separate files.

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

libs/luci-lib-json/luasrc/json.lua

@@ -25,14 +25,9 @@ local char      = string.char
 
 local getmetatable = getmetatable
 
---- LuCI JSON-Library
--- @cstyle	instance
 module "luci.json"
 
 
---- Directly decode a JSON string
--- @param json JSON-String
--- @return Lua object
 function decode(json, ...)
 	local a = ActiveDecoder(function() return nil end, ...)
 	a.chunk = json
@@ -41,9 +36,6 @@ function decode(json, ...)
 end
 
 
---- Direcly encode a Lua object into a JSON string.
--- @param obj Lua Object
--- @return JSON string
 function encode(obj, ...)
 	local out = {}
 	local e = Encoder(obj, 1, ...):source()
@@ -56,19 +48,10 @@ function encode(obj, ...)
 end
 
 
---- Null replacement function
--- @return null
 function null()
 	return null
 end
 
---- Create a new JSON-Encoder.
--- @class	function
--- @name	Encoder
--- @param data			Lua-Object to be encoded.
--- @param buffersize	Blocksize of returned data source.
--- @param fastescape	Use non-standard escaping (don't escape control chars)
--- @return JSON-Encoder
 Encoder = util.class()
 
 function Encoder.__init__(self, data, buffersize, fastescape)
@@ -80,8 +63,6 @@ function Encoder.__init__(self, data, buffersize, fastescape)
 	getmetatable(self).__call = Encoder.source
 end
 
---- Create an LTN12 source providing the encoded JSON-Data.
--- @return LTN12 source
 function Encoder.source(self)
 	local source = coroutine.create(self.dispatch)
 	return function()
@@ -208,11 +189,6 @@ Encoder.parsers = {
 }
 
 
---- Create a new JSON-Decoder.
--- @class	function
--- @name	Decoder
--- @param customnull Use luci.json.null instead of nil for decoding null
--- @return JSON-Decoder
 Decoder = util.class()
 
 function Decoder.__init__(self, customnull)
@@ -220,8 +196,6 @@ function Decoder.__init__(self, customnull)
 	getmetatable(self).__call = Decoder.sink
 end
 
---- Create an LTN12 sink from the decoder object which accepts the JSON-Data.
--- @return LTN12 sink
 function Decoder.sink(self)
 	local sink = coroutine.create(self.dispatch)
 	return function(...)
@@ -230,8 +204,6 @@ function Decoder.sink(self)
 end
 
 
---- Get the decoded data packets after the rawdata has been sent to the sink.
--- @return Decoded data
 function Decoder.get(self)
 	return self.data
 end
@@ -526,11 +498,6 @@ Decoder.parsers = {
 }
 
 
---- Create a new Active JSON-Decoder.
--- @class	function
--- @name	ActiveDecoder
--- @param   customnull	Use luci.json.null instead of nil for decoding null
--- @return  Active JSON-Decoder
 ActiveDecoder = util.class(Decoder)
 
 function ActiveDecoder.__init__(self, source, customnull)
@@ -541,8 +508,6 @@ function ActiveDecoder.__init__(self, source, customnull)
 end
 
 
---- Fetches one JSON-object from given source
--- @return Decoded object
 function ActiveDecoder.get(self)
 	local chunk, src_err, object
 	if not self.chunk then

libs/luci-lib-json/luasrc/json.luadoc

@@ -0,0 +1,94 @@
+---[[
+LuCI JSON-Library
+
+@cstyle	instance
+module "luci.json"
+]]
+
+---[[
+Directly decode a JSON string
+
+@class function
+@name decode
+@param json JSON-String
+@return Lua object
+]]
+
+---[[
+Direcly encode a Lua object into a JSON string.
+
+@class function
+@name encode
+@param obj Lua Object
+@return JSON string
+]]
+
+---[[
+Null replacement function
+
+@class function
+@name null
+@return null
+]]
+
+---[[
+Create a new JSON-Encoder.
+
+@class	function
+@name	Encoder
+@param data			Lua-Object to be encoded.
+@param buffersize	Blocksize of returned data source.
+@param fastescape	Use non-standard escaping (don't escape control chars)
+@return JSON-Encoder
+]]
+
+---[[
+Create an LTN12 source providing the encoded JSON-Data.
+
+@class function
+@name Encoder.source
+@return LTN12 source
+]]
+
+---[[
+Create a new JSON-Decoder.
+
+@class	function
+@name	Decoder
+@param customnull Use luci.json.null instead of nil for decoding null
+@return JSON-Decoder
+]]
+
+---[[
+Create an LTN12 sink from the decoder object which accepts the JSON-Data.
+
+@class function
+@name Decoder.sink
+@return LTN12 sink
+]]
+
+---[[
+Get the decoded data packets after the rawdata has been sent to the sink.
+
+@class function
+@name Decoder.get
+@return Decoded data
+]]
+
+---[[
+Create a new Active JSON-Decoder.
+
+@class	function
+@name	ActiveDecoder
+@param   customnull	Use luci.json.null instead of nil for decoding null
+@return  Active JSON-Decoder
+]]
+
+---[[
+Fetches one JSON-object from given source
+
+@class function
+@name ActiveDecoder.get
+@return Decoded object
+]]
+

libs/luci-lib-rpcc/luasrc/rpcc.lua

@@ -9,17 +9,10 @@ local nixio = require "nixio", require "nixio.util"
 local tostring, assert, setmetatable = tostring, assert, setmetatable
 local error = error
 
---- LuCI RPC Client.
--- @cstyle instance
 module "luci.rpcc"
 
 RQLIMIT = 32 * nixio.const.buffersize
 
---- Create a new JSON-RPC stream client.
--- @class function
--- @param fd File descriptor
--- @param v1 Use protocol version 1.0
--- @return RPC Client
 Client = util.class()
 
 function Client.__init__(self, fd, v1)
@@ -29,11 +22,6 @@ function Client.__init__(self, fd, v1)
 	self.v1 = v1
 end
 
---- Request an RP call and get the response.
--- @param method Remote method
--- @param params Parameters
--- @param notification Notification only?
--- @return response 
 function Client.request(self, method, params, notification)
 	local oldchunk = self.decoder and self.decoder.chunk
 	self.decoder = json.ActiveDecoder(self.fd:blocksource(nil, RQLIMIT))
@@ -58,9 +46,6 @@ function Client.request(self, method, params, notification)
 	end
 end
 
---- Create a transparent RPC proxy.
--- @param prefix Method prefix
--- @return RPC Proxy object
 function Client.proxy(self, prefix)
 	prefix = prefix or ""
 	return setmetatable({}, {

libs/luci-lib-rpcc/luasrc/rpcc.luadoc

@@ -0,0 +1,36 @@
+---[[
+LuCI RPC Client.
+
+@cstyle instance
+module "luci.rpcc"
+]]
+
+---[[
+Create a new JSON-RPC stream client.
+
+@class function
+@param fd File descriptor
+@param v1 Use protocol version 1.0
+@return RPC Client
+]]
+
+---[[
+Request an RP call and get the response.
+
+@class function
+@name Client.request
+@param method Remote method
+@param params Parameters
+@param notification Notification only?
+@return response 
+]]
+
+---[[
+Create a transparent RPC proxy.
+
+@class function
+@name Client.proxy
+@param prefix Method prefix
+@return RPC Proxy object
+]]
+

libs/luci-lib-rpcc/luasrc/rpcc/ruci.lua

@@ -5,16 +5,11 @@ local util = require "luci.util"
 local rawget, setmetatable = rawget, setmetatable
 local ipairs = ipairs
 
---- Transparent UCI over RPC client.
--- @cstyle instance
 module "luci.rpcc.ruci"
 
 
 local Proxy = util.class()
 
---- Create a new UCI over RPC proxy.
--- @param rpccl RPC client
--- @return Network transparent UCI module 
 function factory(rpccl)
 	return {
 		cursor = function(...)

libs/luci-lib-rpcc/luasrc/rpcc/ruci.luadoc

@@ -0,0 +1,16 @@
+---[[
+Transparent UCI over RPC client.
+
+@cstyle instance
+module "luci.rpcc.ruci"
+]]
+
+---[[
+Create a new UCI over RPC proxy.
+
+@class function
+@name factory
+@param rpccl RPC client
+@return Network transparent UCI module 
+]]
+

modules/luci-base/luasrc/dispatcher.lua

@@ -1,7 +1,6 @@
 -- Copyright 2008 Steven Barth <steven@midlink.org>
 -- Licensed to the public under the Apache License 2.0.
 
---- LuCI web dispatcher.
 local fs = require "nixio.fs"
 local sys = require "luci.sys"
 local util = require "luci.util"
@@ -23,9 +22,6 @@ local index = nil
 local fi
 
 
---- Build the URL relative to the server webroot from given virtual path.
--- @param ...	Virtual path
--- @return 		Relative URL
 function build_url(...)
 	local path = {...}
 	local url = { http.getenv("SCRIPT_NAME") or "" }
@@ -49,9 +45,6 @@ function build_url(...)
 	return table.concat(url, "")
 end
 
---- Check whether a dispatch node shall be visible
--- @param node	Dispatch node
--- @return		Boolean indicating whether the node should be visible
 function node_visible(node)
    if node then
 	  return not (
@@ -64,9 +57,6 @@ function node_visible(node)
    return false
 end
 
---- Return a sorted table of visible childs within a given node
--- @param node	Dispatch node
--- @return		Ordered table of child node names
 function node_childs(node)
 	local rv = { }
 	if node then
@@ -86,9 +76,6 @@ function node_childs(node)
 end
 
 
---- Send a 404 error code and render the "error404" template if available.
--- @param message	Custom error message (optional)
--- @return			false
 function error404(message)
 	http.status(404, "Not Found")
 	message = message or "Not Found"
@@ -101,9 +88,6 @@ function error404(message)
 	return false
 end
 
---- Send a 500 error code and render the "error500" template if available.
--- @param message	Custom error message (optional)#
--- @return			false
 function error500(message)
 	util.perror(message)
 	if not context.template_header_sent then
@@ -144,8 +128,6 @@ function authenticator.htmlauth(validator, accs, default)
 
 end
 
---- Dispatch an HTTP request.
--- @param request	LuCI HTTP Request object
 function httpdispatch(request, prefix)
 	http.context.request = request
 
@@ -184,8 +166,6 @@ function httpdispatch(request, prefix)
 	--context._disable_memtrace()
 end
 
---- Dispatches a LuCI virtual path.
--- @param request	Virtual path
 function dispatch(request)
 	--context._disable_memtrace = require "luci.debug".trap_memtrace("l")
 	local ctx = context
@@ -453,7 +433,6 @@ function dispatch(request)
 	end
 end
 
---- Generate the dispatching index using the native file-cache based strategy.
 function createindex()
 	local controllers = { }
 	local base = "%s/controller/" % util.libpath()
@@ -517,7 +496,6 @@ function createindex()
 	end
 end
 
---- Create the dispatching tree from the index.
 -- Build the index before if it does not exist yet.
 function createtree()
 	if not index then
@@ -556,9 +534,6 @@ function createtree()
 	return tree
 end
 
---- Register a tree modifier.
--- @param	func	Modifier function
--- @param	order	Modifier order value (optional)
 function modifier(func, order)
 	context.modifiers[#context.modifiers+1] = {
 		func = func,
@@ -568,12 +543,6 @@ function modifier(func, order)
 	}
 end
 
---- Clone a node of the dispatching tree to another position.
--- @param	path	Virtual path destination
--- @param	clone	Virtual path source
--- @param	title	Destination node title (optional)
--- @param	order	Destination node order value (optional)
--- @return			Dispatching tree node
 function assign(path, clone, title, order)
 	local obj  = node(unpack(path))
 	obj.nodes  = nil
@@ -587,12 +556,6 @@ function assign(path, clone, title, order)
 	return obj
 end
 
---- Create a new dispatching node and define common parameters.
--- @param	path	Virtual path
--- @param	target	Target function to call when dispatched.
--- @param	title	Destination node title
--- @param	order	Destination node order value (optional)
--- @return			Dispatching tree node
 function entry(path, target, title, order)
 	local c = node(unpack(path))
 
@@ -604,17 +567,11 @@ function entry(path, target, title, order)
 	return c
 end
 
---- Fetch or create a dispatching node without setting the target module or
 -- enabling the node.
--- @param	...		Virtual path
--- @return			Dispatching tree node
 function get(...)
 	return _create_node({...})
 end
 
---- Fetch or create a new dispatching node.
--- @param	...		Virtual path
--- @return			Dispatching tree node
 function node(...)
 	local c = _create_node({...})
 
@@ -674,13 +631,10 @@ function _firstchild()
    dispatch(path)
 end
 
---- Alias the first (lowest order) page automatically
 function firstchild()
    return { type = "firstchild", target = _firstchild }
 end
 
---- Create a redirect to another dispatching node.
--- @param	...		Virtual path destination
 function alias(...)
 	local req = {...}
 	return function(...)
@@ -692,9 +646,6 @@ function alias(...)
 	end
 end
 
---- Rewrite the first x path values of the request.
--- @param	n		Number of path values to replace
--- @param	...		Virtual path to replace removed path values with
 function rewrite(n, ...)
 	local req = {...}
 	return function(...)
@@ -733,9 +684,6 @@ local function _call(self, ...)
 	end
 end
 
---- Create a function-call dispatching target.
--- @param	name	Target function of local controller
--- @param	...		Additional parameters passed to the function
 function call(name, ...)
 	return {type = "call", argv = {...}, name = name, target = _call}
 end
@@ -745,8 +693,6 @@ local _template = function(self, ...)
 	require "luci.template".render(self.view)
 end
 
---- Create a template render dispatching target.
--- @param	name	Template to be rendered
 function template(name)
 	return {type = "template", view = name, target = _template}
 end
@@ -852,8 +798,6 @@ local function _cbi(self, ...)
 	end
 end
 
---- Create a CBI model dispatching target.
--- @param	model	CBI model to be rendered
 function cbi(model, config)
 	return {type = "cbi", config = config, model = model, target = _cbi}
 end
@@ -866,9 +810,6 @@ local function _arcombine(self, ...)
 	target:target(unpack(argv))
 end
 
---- Create a combined dispatching target for non argv and argv requests.
--- @param trg1	Overview Target
--- @param trg2	Detail Target
 function arcombine(trg1, trg2)
 	return {type = "arcombine", env = getfenv(), target = _arcombine, targets = {trg1, trg2}}
 end
@@ -897,19 +838,12 @@ local function _form(self, ...)
 	tpl.render("footer")
 end
 
---- Create a CBI form model dispatching target.
--- @param	model	CBI form model tpo be rendered
 function form(model)
 	return {type = "cbi", model = model, target = _form}
 end
 
---- Access the luci.i18n translate() api.
--- @class  function
--- @name   translate
--- @param  text    Text to translate
 translate = i18n.translate
 
---- No-op function used to mark translation entries for menu labels.
 -- This function does not actually translate the given argument but
 -- is used by build/i18n-scan.pl to find translatable entries.
 function _(text)

modules/luci-base/luasrc/dispatcher.luadoc

@@ -0,0 +1,220 @@
+---[[
+LuCI web dispatcher.
+]]
+module "luci.dispatcher"
+
+---[[
+Build the URL relative to the server webroot from given virtual path.
+
+@class function
+@name build_url
+@param ...	Virtual path
+@return 		Relative URL
+]]
+
+---[[
+Check whether a dispatch node shall be visible
+
+@class function
+@name node_visible
+@param node	Dispatch node
+@return		Boolean indicating whether the node should be visible
+]]
+
+---[[
+Return a sorted table of visible childs within a given node
+
+@class function
+@name node_childs
+@param node	Dispatch node
+@return		Ordered table of child node names
+]]
+
+---[[
+Send a 404 error code and render the "error404" template if available.
+
+@class function
+@name error404
+@param message	Custom error message (optional)
+@return			false
+]]
+
+---[[
+Send a 500 error code and render the "error500" template if available.
+
+@class function
+@name error500
+@param message	Custom error message (optional)#
+@return			false
+]]
+
+---[[
+Dispatch an HTTP request.
+
+@class function
+@name httpdispatch
+@param request	LuCI HTTP Request object
+]]
+
+---[[
+Dispatches a LuCI virtual path.
+
+@class function
+@name dispatch
+@param request	Virtual path
+]]
+
+---[[
+Generate the dispatching index using the native file-cache based strategy.
+
+
+@class function
+@name createindex
+]]
+
+---[[
+Create the dispatching tree from the index.
+
+Build the index before if it does not exist yet.
+
+@class function
+@name createtree
+]]
+
+---[[
+Register a tree modifier.
+
+@class function
+@name modifier
+@param	func	Modifier function
+@param	order	Modifier order value (optional)
+]]
+
+---[[
+Clone a node of the dispatching tree to another position.
+
+@class function
+@name assign
+@param	path	Virtual path destination
+@param	clone	Virtual path source
+@param	title	Destination node title (optional)
+@param	order	Destination node order value (optional)
+@return			Dispatching tree node
+]]
+
+---[[
+Create a new dispatching node and define common parameters.
+
+@class function
+@name entry
+@param	path	Virtual path
+@param	target	Target function to call when dispatched.
+@param	title	Destination node title
+@param	order	Destination node order value (optional)
+@return			Dispatching tree node
+]]
+
+---[[
+Fetch or create a dispatching node without setting the target module or
+
+enabling the node.
+@class function
+@name get
+@param	...		Virtual path
+@return			Dispatching tree node
+]]
+
+---[[
+Fetch or create a new dispatching node.
+
+@class function
+@name node
+@param	...		Virtual path
+@return			Dispatching tree node
+]]
+
+---[[
+Alias the first (lowest order) page automatically
+
+
+@class function
+@name firstchild
+]]
+
+---[[
+Create a redirect to another dispatching node.
+
+@class function
+@name alias
+@param	...		Virtual path destination
+]]
+
+---[[
+Rewrite the first x path values of the request.
+
+@class function
+@name rewrite
+@param	n		Number of path values to replace
+@param	...		Virtual path to replace removed path values with
+]]
+
+---[[
+Create a function-call dispatching target.
+
+@class function
+@name call
+@param	name	Target function of local controller
+@param	...		Additional parameters passed to the function
+]]
+
+---[[
+Create a template render dispatching target.
+
+@class function
+@name template
+@param	name	Template to be rendered
+]]
+
+---[[
+Create a CBI model dispatching target.
+
+@class function
+@name cbi
+@param	model	CBI model to be rendered
+]]
+
+---[[
+Create a combined dispatching target for non argv and argv requests.
+
+@class function
+@name arcombine
+@param trg1	Overview Target
+@param trg2	Detail Target
+]]
+
+---[[
+Create a CBI form model dispatching target.
+
+@class function
+@name form
+@param	model	CBI form model tpo be rendered
+]]
+
+---[[
+Access the luci.i18n translate() api.
+
+@class  function
+@name   translate
+@param  text    Text to translate
+]]
+
+---[[
+No-op function used to mark translation entries for menu labels.
+
+This function does not actually translate the given argument but
+is used by build/i18n-scan.pl to find translatable entries.
+
+@class function
+@name _
+]]
+

modules/luci-base/luasrc/http.lua

@@ -11,7 +11,6 @@ local table = require "table"
 local ipairs, pairs, next, type, tostring, error =
 	ipairs, pairs, next, type, tostring, error
 
---- LuCI Web Framework high-level HTTP functions.
 module "luci.http"
 
 context = util.threadlocal()
@@ -101,7 +100,6 @@ function Request._parse_input(self)
 	self.parsed_input = true
 end
 
---- Close the HTTP-Connection.
 function close()
 	if not context.eoh then
 		context.eoh = true
@@ -114,52 +112,31 @@ function close()
 	end
 end
 
---- Return the request content if the request was of unknown type.
--- @return	HTTP request body
--- @return	HTTP request body length
 function content()
 	return context.request:content()
 end
 
---- Get a certain HTTP input value or a table of all input values.
--- @param name		Name of the GET or POST variable to fetch
--- @param noparse	Don't parse POST data before getting the value
--- @return			HTTP input value or table of all input value
 function formvalue(name, noparse)
 	return context.request:formvalue(name, noparse)
 end
 
---- Get a table of all HTTP input values with a certain prefix.
--- @param prefix	Prefix
--- @return			Table of all HTTP input values with given prefix
 function formvaluetable(prefix)
 	return context.request:formvaluetable(prefix)
 end
 
---- Get the value of a certain HTTP-Cookie.
--- @param name		Cookie Name
--- @return			String containing cookie data
 function getcookie(name)
 	return context.request:getcookie(name)
 end
 
---- Get the value of a certain HTTP environment variable
 -- or the environment table itself.
--- @param name		Environment variable
--- @return			HTTP environment value or environment table
 function getenv(name)
 	return context.request:getenv(name)
 end
 
---- Set a handler function for incoming user file uploads.
--- @param callback	Handler function
 function setfilehandler(callback)
 	return context.request:setfilehandler(callback)
 end
 
---- Send a HTTP-Header.
--- @param key	Header key
--- @param value Header value
 function header(key, value)
 	if not context.headers then
 		context.headers = {}
@@ -168,8 +145,6 @@ function header(key, value)
 	coroutine.yield(2, key, value)
 end
 
---- Set the mime type of following content data.
--- @param mime	Mimetype of following content
 function prepare_content(mime)
 	if not context.headers or not context.headers["content-type"] then
 		if mime == "application/xhtml+xml" then
@@ -183,15 +158,10 @@ function prepare_content(mime)
 	end
 end
 
---- Get the RAW HTTP input source
--- @return	HTTP LTN12 source
 function source()
 	return context.request.input
 end
 
---- Set the HTTP status code and status message.
--- @param code		Status code
--- @param message	Status message
 function status(code, message)
 	code = code or 200
 	message = message or "OK"
@@ -199,12 +169,8 @@ function status(code, message)
 	coroutine.yield(1, code, message)
 end
 
---- Send a chunk of content data to the client.
 -- This function is as a valid LTN12 sink.
 -- If the content chunk is nil this function will automatically invoke close.
--- @param content	Content chunk
--- @param src_err	Error object from source (optional)
--- @see close
 function write(content, src_err)
 	if not content then
 		if src_err then
@@ -237,24 +203,16 @@ function write(content, src_err)
 	end
 end
 
---- Splice data from a filedescriptor to the client.
--- @param fp	File descriptor
--- @param size	Bytes to splice (optional)
 function splice(fd, size)
 	coroutine.yield(6, fd, size)
 end
 
---- Redirects the client to a new URL and closes the connection.
--- @param url	Target URL
 function redirect(url)
 	status(302, "Found")
 	header("Location", url)
 	close()
 end
 
---- Create a querystring out of a table of key - value pairs.
--- @param table		Query string source table
--- @return			Encoded HTTP query string
 function build_querystring(q)
 	local s = { "?" }
 
@@ -269,21 +227,10 @@ function build_querystring(q)
 	return table.concat(s, "")
 end
 
---- Return the URL-decoded equivalent of a string.
--- @param str		URL-encoded string
--- @param no_plus	Don't decode + to " "
--- @return			URL-decoded string
--- @see urlencode
 urldecode = protocol.urldecode
 
---- Return the URL-encoded equivalent of a string.
--- @param str		Source string
--- @return			URL-encoded string
--- @see urldecode
 urlencode = protocol.urlencode
 
---- Send the given data as JSON encoded string.
--- @param data		Data to send
 function write_json(x)
 	util.serialize_json(x, write)
 end

modules/luci-base/luasrc/http.luadoc

@@ -0,0 +1,166 @@
+---[[
+LuCI Web Framework high-level HTTP functions.
+
+module "luci.http"
+]]
+
+---[[
+Close the HTTP-Connection.
+
+
+@class function
+@name close
+]]
+
+---[[
+Return the request content if the request was of unknown type.
+
+@class function
+@name content
+@return	HTTP request body
+@return	HTTP request body length
+]]
+
+---[[
+Get a certain HTTP input value or a table of all input values.
+
+@class function
+@name formvalue
+@param name		Name of the GET or POST variable to fetch
+@param noparse	Don't parse POST data before getting the value
+@return			HTTP input value or table of all input value
+]]
+
+---[[
+Get a table of all HTTP input values with a certain prefix.
+
+@class function
+@name formvaluetable
+@param prefix	Prefix
+@return			Table of all HTTP input values with given prefix
+]]
+
+---[[
+Get the value of a certain HTTP-Cookie.
+
+@class function
+@name getcookie
+@param name		Cookie Name
+@return			String containing cookie data
+]]
+
+---[[
+Get the value of a certain HTTP environment variable
+
+or the environment table itself.
+@class function
+@name getenv
+@param name		Environment variable
+@return			HTTP environment value or environment table
+]]
+
+---[[
+Set a handler function for incoming user file uploads.
+
+@class function
+@name setfilehandler
+@param callback	Handler function
+]]
+
+---[[
+Send a HTTP-Header.
+
+@class function
+@name header
+@param key	Header key
+@param value Header value
+]]
+
+---[[
+Set the mime type of following content data.
+
+@class function
+@name prepare_content
+@param mime	Mimetype of following content
+]]
+
+---[[
+Get the RAW HTTP input source
+
+@class function
+@name source
+@return	HTTP LTN12 source
+]]
+
+---[[
+Set the HTTP status code and status message.
+
+@class function
+@name status
+@param code		Status code
+@param message	Status message
+]]
+
+---[[
+Send a chunk of content data to the client.
+
+This function is as a valid LTN12 sink.
+If the content chunk is nil this function will automatically invoke close.
+@class function
+@name write
+@param content	Content chunk
+@param src_err	Error object from source (optional)
+@see close
+]]
+
+---[[
+Splice data from a filedescriptor to the client.
+
+@class function
+@name splice
+@param fp	File descriptor
+@param size	Bytes to splice (optional)
+]]
+
+---[[
+Redirects the client to a new URL and closes the connection.
+
+@class function
+@name redirect
+@param url	Target URL
+]]
+
+---[[
+Create a querystring out of a table of key - value pairs.
+
+@class function
+@name build_querystring
+@param table		Query string source table
+@return			Encoded HTTP query string
+]]
+
+---[[
+Return the URL-decoded equivalent of a string.
+
+@param str		URL-encoded string
+@param no_plus	Don't decode + to " "
+@return			URL-decoded string
+@see urlencode
+]]
+
+---[[
+Return the URL-encoded equivalent of a string.
+
+@param str		Source string
+@return			URL-encoded string
+@see urldecode
+]]
+
+---[[
+Send the given data as JSON encoded string.
+
+@class function
+@name write_json
+@param data		Data to send
+]]
+

modules/luci-base/luasrc/http/protocol.lua

@@ -1,7 +1,6 @@
 -- Copyright 2008 Freifunk Leipzig / Jo-Philipp Wich <jow@openwrt.org>
 -- Licensed to the public under the Apache License 2.0.
 
---- LuCI http protocol class.
 -- This class contains several functions useful for http message- and content
 -- decoding and to retrive form data from raw http messages.
 module("luci.http.protocol", package.seeall)
@@ -10,12 +9,7 @@ local ltn12 = require("luci.ltn12")
 
 HTTP_MAX_CONTENT      = 1024*8		-- 8 kB maximum content size
 
---- Decode an urlencoded string - optionally without decoding
 -- the "+" sign to " " - and return the decoded string.
--- @param str		Input string in x-www-urlencoded format
--- @param no_plus	Don't decode "+" signs to spaces
--- @return			The decoded string
--- @see				urlencode
 function urldecode( str, no_plus )
 
 	local function __chrdec( hex )
@@ -33,15 +27,10 @@ function urldecode( str, no_plus )
 	return str
 end
 
---- Extract and split urlencoded data pairs, separated bei either "&" or ";"
 -- from given url or string. Returns a table with urldecoded values.
 -- Simple parameters are stored as string values associated with the parameter
 -- name within the table. Parameters with multiple values are stored as array
 -- containing the corresponding values.
--- @param url	The url or string which contains x-www-urlencoded form data
--- @param tbl	Use the given table for storing values (optional)
--- @return		Table containing the urldecoded parameters
--- @see			urlencode_params
 function urldecode_params( url, tbl )
 
 	local params = tbl or { }
@@ -73,10 +62,6 @@ function urldecode_params( url, tbl )
 	return params
 end
 
---- Encode given string to x-www-urlencoded format.
--- @param str	String to encode
--- @return		String containing the encoded data
--- @see			urldecode
 function urlencode( str )
 
 	local function __chrenc( chr )
@@ -95,12 +80,8 @@ function urlencode( str )
 	return str
 end
 
---- Encode each key-value-pair in given table to x-www-urlencoded format,
 -- separated by "&". Tables are encoded as parameters with multiple values by
 -- repeating the parameter name with each value.
--- @param tbl	Table with the values
--- @return		String containing encoded values
--- @see			urldecode_params
 function urlencode_params( tbl )
 	local enc = ""
 
@@ -122,9 +103,6 @@ end
 -- (Internal function)
 -- Initialize given parameter and coerce string into table when the parameter
 -- already exists.
--- @param tbl	Table where parameter should be created
--- @param key	Parameter name
--- @return		Always nil
 local function __initval( tbl, key )
 	if tbl[key] == nil then
 		tbl[key] = ""
@@ -138,11 +116,6 @@ end
 -- (Internal function)
 -- Append given data to given parameter, either by extending the string value
 -- or by appending it to the last string in the parameter's value table.
--- @param tbl	Table containing the previously initialized parameter value
--- @param key	Parameter name
--- @param chunk	String containing the data to append
--- @return		Always nil
--- @see			__initval
 local function __appendval( tbl, key, chunk )
 	if type(tbl[key]) == "table" then
 		tbl[key][#tbl[key]] = tbl[key][#tbl[key]] .. chunk
@@ -155,12 +128,6 @@ end
 -- Finish the value of given parameter, either by transforming the string value
 -- or - in the case of multi value parameters - the last element in the
 -- associated values table.
--- @param tbl		Table containing the previously initialized parameter value
--- @param key		Parameter name
--- @param handler	Function which transforms the parameter value
--- @return			Always nil
--- @see				__initval
--- @see				__appendval
 local function __finishval( tbl, key, handler )
 	if handler then
 		if type(tbl[key]) == "table" then
@@ -259,10 +226,7 @@ process_states['headers'] = function( msg, chunk )
 end
 
 
---- Creates a ltn12 source from the given socket. The source will return it's
 -- data line by line with the trailing \r\n stripped of.
--- @param sock	Readable network socket
--- @return		Ltn12 source function
 function header_source( sock )
 	return ltn12.source.simplify( function()
 
@@ -289,7 +253,6 @@ function header_source( sock )
 	end )
 end
 
---- Decode a mime encoded http message body with multipart/form-data
 -- Content-Type. Stores all extracted data associated with its parameter name
 -- in the params table withing the given message object. Multiple parameter
 -- values are stored as tables, ordinary ones as strings.
@@ -300,12 +263,6 @@ end
 --  o Table containing decoded (name, file) and raw (headers) mime header data
 --  o String value containing a chunk of the file data
 --  o Boolean which indicates wheather the current chunk is the last one (eof)
--- @param src		Ltn12 source function
--- @param msg		HTTP message object
--- @param filecb	File callback function (optional)
--- @return			Value indicating successful operation (not nil means "ok")
--- @return			String containing the error if unsuccessful
--- @see				parse_message_header
 function mimedecode_message_body( src, msg, filecb )
 
 	if msg and msg.env.CONTENT_TYPE then
@@ -449,15 +406,9 @@ function mimedecode_message_body( src, msg, filecb )
 	return ltn12.pump.all( src, snk )
 end
 
---- Decode an urlencoded http message body with application/x-www-urlencoded
 -- Content-Type. Stores all extracted data associated with its parameter name
 -- in the params table withing the given message object. Multiple parameter
 -- values are stored as tables, ordinary ones as strings.
--- @param src	Ltn12 source function
--- @param msg	HTTP message object
--- @return		Value indicating successful operation (not nil means "ok")
--- @return		String containing the error if unsuccessful
--- @see			parse_message_header
 function urldecode_message_body( src, msg )
 
 	local tlen   = 0
@@ -507,12 +458,8 @@ function urldecode_message_body( src, msg )
 	return ltn12.pump.all( src, snk )
 end
 
---- Try to extract an http message header including information like protocol
 -- version, message headers and resulting CGI environment variables from the
 -- given ltn12 source.
--- @param src	Ltn12 source function
--- @return		HTTP message object
--- @see			parse_message_body
 function parse_message_header( src )
 
 	local ok   = true
@@ -582,19 +529,12 @@ function parse_message_header( src )
 	return msg
 end
 
---- Try to extract and decode a http message body from the given ltn12 source.
 -- This function will examine the Content-Type within the given message object
 -- to select the appropriate content decoder.
 -- Currently the application/x-www-urlencoded and application/form-data
 -- mime types are supported. If the encountered content encoding can't be
 -- handled then the whole message body will be stored unaltered as "content"
 -- property within the given message object.
--- @param src		Ltn12 source function
--- @param msg		HTTP message object
--- @param filecb	File data callback (optional, see mimedecode_message_body())
--- @return			Value indicating successful operation (not nil means "ok")
--- @return			String containing the error if unsuccessful
--- @see				parse_message_header
 function parse_message_body( src, msg, filecb )
 	-- Is it multipart/mime ?
 	if msg.env.REQUEST_METHOD == "POST" and msg.env.CONTENT_TYPE and
@@ -655,8 +595,6 @@ function parse_message_body( src, msg, filecb )
 	end
 end
 
---- Table containing human readable messages for several http status codes.
--- @class table
 statusmsg = {
 	[200] = "OK",
 	[206] = "Partial Content",

modules/luci-base/luasrc/http/protocol.luadoc

@@ -0,0 +1,142 @@
+---[[
+LuCI http protocol class.
+
+This class contains several functions useful for http message- and content
+decoding and to retrive form data from raw http messages.
+]]
+module "luci.http.protocol"
+
+---[[
+Decode an urlencoded string - optionally without decoding
+
+the "+" sign to " " - and return the decoded string.
+@class function
+@name urldecode
+@param str		Input string in x-www-urlencoded format
+@param no_plus	Don't decode "+" signs to spaces
+@return			The decoded string
+@see				urlencode
+]]
+
+---[[
+Extract and split urlencoded data pairs, separated bei either "&" or ";"
+
+from given url or string. Returns a table with urldecoded values.
+Simple parameters are stored as string values associated with the parameter
+name within the table. Parameters with multiple values are stored as array
+containing the corresponding values.
+@class function
+@name urldecode_params
+@param url	The url or string which contains x-www-urlencoded form data
+@param tbl	Use the given table for storing values (optional)
+@return		Table containing the urldecoded parameters
+@see			urlencode_params
+]]
+
+---[[
+Encode given string to x-www-urlencoded format.
+
+@class function
+@name urlencode
+@param str	String to encode
+@return		String containing the encoded data
+@see			urldecode
+]]
+
+---[[
+Encode each key-value-pair in given table to x-www-urlencoded format,
+
+separated by "&". Tables are encoded as parameters with multiple values by
+repeating the parameter name with each value.
+@class function
+@name urlencode_params
+@param tbl	Table with the values
+@return		String containing encoded values
+@see			urldecode_params
+]]
+
+---[[
+Creates a ltn12 source from the given socket. The source will return it's
+
+data line by line with the trailing \r\n stripped of.
+@class function
+@name header_source
+@param sock	Readable network socket
+@return		Ltn12 source function
+]]
+
+---[[
+Decode a mime encoded http message body with multipart/form-data
+
+Content-Type. Stores all extracted data associated with its parameter name
+in the params table withing the given message object. Multiple parameter
+values are stored as tables, ordinary ones as strings.
+If an optional file callback function is given then it is feeded with the
+file contents chunk by chunk and only the extracted file name is stored
+within the params table. The callback function will be called subsequently
+with three arguments:
+ o Table containing decoded (name, file) and raw (headers) mime header data
+ o String value containing a chunk of the file data
+ o Boolean which indicates wheather the current chunk is the last one (eof)
+@class function
+@name mimedecode_message_body
+@param src		Ltn12 source function
+@param msg		HTTP message object
+@param filecb	File callback function (optional)
+@return			Value indicating successful operation (not nil means "ok")
+@return			String containing the error if unsuccessful
+@see				parse_message_header
+]]
+
+---[[
+Decode an urlencoded http message body with application/x-www-urlencoded
+
+Content-Type. Stores all extracted data associated with its parameter name
+in the params table withing the given message object. Multiple parameter
+values are stored as tables, ordinary ones as strings.
+@class function
+@name urldecode_message_body
+@param src	Ltn12 source function
+@param msg	HTTP message object
+@return		Value indicating successful operation (not nil means "ok")
+@return		String containing the error if unsuccessful
+@see			parse_message_header
+]]
+
+---[[
+Try to extract an http message header including information like protocol
+
+version, message headers and resulting CGI environment variables from the
+given ltn12 source.
+@class function
+@name parse_message_header
+@param src	Ltn12 source function
+@return		HTTP message object
+@see			parse_message_body
+]]
+
+---[[
+Try to extract and decode a http message body from the given ltn12 source.
+
+This function will examine the Content-Type within the given message object
+to select the appropriate content decoder.
+Currently the application/x-www-urlencoded and application/form-data
+mime types are supported. If the encountered content encoding can't be
+handled then the whole message body will be stored unaltered as "content"
+property within the given message object.
+@class function
+@name parse_message_body
+@param src		Ltn12 source function
+@param msg		HTTP message object
+@param filecb	File data callback (optional, see mimedecode_message_body())
+@return			Value indicating successful operation (not nil means "ok")
+@return			String containing the error if unsuccessful
+@see				parse_message_header
+]]
+
+---[[
+Table containing human readable messages for several http status codes.
+
+@class table
+]]
+

modules/luci-base/luasrc/http/protocol/conditionals.lua

@@ -1,7 +1,6 @@
 -- Copyright 2008 Freifunk Leipzig / Jo-Philipp Wich <jow@openwrt.org>
 -- Licensed to the public under the Apache License 2.0.
 
---- LuCI http protocol implementation - HTTP/1.1 bits.
 -- This class provides basic ETag handling and implements most of the
 -- conditional HTTP/1.1 headers specified in RFC2616 Sct. 14.24 - 14.28 .
 module("luci.http.protocol.conditionals", package.seeall)
@@ -9,22 +8,14 @@ module("luci.http.protocol.conditionals", package.seeall)
 local date = require("luci.http.protocol.date")
 
 
---- Implement 14.19 / ETag.
--- @param stat	A file.stat structure
--- @return		String containing the generated tag suitable for ETag headers
 function mk_etag( stat )
 	if stat ~= nil then
 		return string.format( '"%x-%x-%x"', stat.ino, stat.size, stat.mtime )
 	end
 end
 
---- 14.24 / If-Match
 -- Test whether the given message object contains an "If-Match" header and
 -- compare it against the given stat object.
--- @param req	HTTP request message object
--- @param stat	A file.stat object
--- @return		Boolean indicating whether the precondition is ok
--- @return		Alternative status code if the precondition failed
 function if_match( req, stat )
 	local h    = req.headers
 	local etag = mk_etag( stat )
@@ -43,14 +34,8 @@ function if_match( req, stat )
 	return true
 end
 
---- 14.25 / If-Modified-Since
 -- Test whether the given message object contains an "If-Modified-Since" header
 -- and compare it against the given stat object.
--- @param req	HTTP request message object
--- @param stat	A file.stat object
--- @return		Boolean indicating whether the precondition is ok
--- @return		Alternative status code if the precondition failed
--- @return		Table containing extra HTTP headers if the precondition failed
 function if_modified_since( req, stat )
 	local h = req.headers
 
@@ -72,14 +57,8 @@ function if_modified_since( req, stat )
 	return true
 end
 
---- 14.26 / If-None-Match
 -- Test whether the given message object contains an "If-None-Match" header and
 -- compare it against the given stat object.
--- @param req	HTTP request message object
--- @param stat	A file.stat object
--- @return		Boolean indicating whether the precondition is ok
--- @return		Alternative status code if the precondition failed
--- @return		Table containing extra HTTP headers if the precondition failed
 function if_none_match( req, stat )
 	local h      = req.headers
 	local etag   = mk_etag( stat )
@@ -105,26 +84,16 @@ function if_none_match( req, stat )
 	return true
 end
 
---- 14.27 / If-Range
 -- The If-Range header is currently not implemented due to the lack of general
 -- byte range stuff in luci.http.protocol . This function will always return
 -- false, 412 to indicate a failed precondition.
--- @param req	HTTP request message object
--- @param stat	A file.stat object
--- @return		Boolean indicating whether the precondition is ok
--- @return		Alternative status code if the precondition failed
 function if_range( req, stat )
 	-- Sorry, no subranges (yet)
 	return false, 412
 end
 
---- 14.28 / If-Unmodified-Since
 -- Test whether the given message object contains an "If-Unmodified-Since"
 -- header and compare it against the given stat object.
--- @param req	HTTP request message object
--- @param stat	A file.stat object
--- @return		Boolean indicating whether the precondition is ok
--- @return		Alternative status code if the precondition failed
 function if_unmodified_since( req, stat )
 	local h = req.headers
 

modules/luci-base/luasrc/http/protocol/conditionals.luadoc

@@ -0,0 +1,85 @@
+---[[
+LuCI http protocol implementation - HTTP/1.1 bits.
+
+This class provides basic ETag handling and implements most of the
+conditional HTTP/1.1 headers specified in RFC2616 Sct. 14.24 - 14.28 .
+]]
+module "luci.http.protocol.conditionals"
+
+---[[
+Implement 14.19 / ETag.
+
+@class function
+@name mk_etag
+@param stat	A file.stat structure
+@return		String containing the generated tag suitable for ETag headers
+]]
+
+---[[
+14.24 / If-Match
+
+Test whether the given message object contains an "If-Match" header and
+compare it against the given stat object.
+@class function
+@name if_match
+@param req	HTTP request message object
+@param stat	A file.stat object
+@return		Boolean indicating whether the precondition is ok
+@return		Alternative status code if the precondition failed
+]]
+
+---[[
+14.25 / If-Modified-Since
+
+Test whether the given message object contains an "If-Modified-Since" header
+and compare it against the given stat object.
+@class function
+@name if_modified_since
+@param req	HTTP request message object
+@param stat	A file.stat object
+@return		Boolean indicating whether the precondition is ok
+@return		Alternative status code if the precondition failed
+@return		Table containing extra HTTP headers if the precondition failed
+]]
+
+---[[
+14.26 / If-None-Match
+
+Test whether the given message object contains an "If-None-Match" header and
+compare it against the given stat object.
+@class function
+@name if_none_match
+@param req	HTTP request message object
+@param stat	A file.stat object
+@return		Boolean indicating whether the precondition is ok
+@return		Alternative status code if the precondition failed
+@return		Table containing extra HTTP headers if the precondition failed
+]]
+
+---[[
+14.27 / If-Range
+
+The If-Range header is currently not implemented due to the lack of general
+byte range stuff in luci.http.protocol . This function will always return
+false, 412 to indicate a failed precondition.
+@class function
+@name if_range
+@param req	HTTP request message object
+@param stat	A file.stat object
+@return		Boolean indicating whether the precondition is ok
+@return		Alternative status code if the precondition failed
+]]
+
+---[[
+14.28 / If-Unmodified-Since
+
+Test whether the given message object contains an "If-Unmodified-Since"
+header and compare it against the given stat object.
+@class function
+@name if_unmodified_since
+@param req	HTTP request message object
+@param stat	A file.stat object
+@return		Boolean indicating whether the precondition is ok
+@return		Alternative status code if the precondition failed
+]]
+

modules/luci-base/luasrc/http/protocol/date.lua

@@ -1,7 +1,6 @@
 -- Copyright 2008 Freifunk Leipzig / Jo-Philipp Wich <jow@openwrt.org>
 -- Licensed to the public under the Apache License 2.0.
 
---- LuCI http protocol implementation - date helper class.
 -- This class contains functions to parse, compare and format http dates.
 module("luci.http.protocol.date", package.seeall)
 
@@ -13,9 +12,6 @@ MONTHS = {
 	"Sep", "Oct", "Nov", "Dec"
 }
 
---- Return the time offset in seconds between the UTC and given time zone.
--- @param tz	Symbolic or numeric timezone specifier
--- @return		Time offset to UTC in seconds
 function tz_offset(tz)
 
 	if type(tz) == "string" then
@@ -39,9 +35,6 @@ function tz_offset(tz)
 	return 0
 end
 
---- Parse given HTTP date string and convert it to unix epoch time.
--- @param data	String containing the date
--- @return		Unix epoch time
 function to_unix(date)
 
 	local wd, day, mon, yr, hr, min, sec, tz = date:match(
@@ -75,19 +68,10 @@ function to_unix(date)
 	return 0
 end
 
---- Convert the given unix epoch time to valid HTTP date string.
--- @param time	Unix epoch time
--- @return		String containing the formatted date
 function to_http(time)
 	return os.date( "%a, %d %b %Y %H:%M:%S GMT", time )
 end
 
---- Compare two dates which can either be unix epoch times or HTTP date strings.
--- @param d1	The first date or epoch time to compare
--- @param d2	The first date or epoch time to compare
--- @return		-1  -  if d1 is lower then d2
--- @return		0   -  if both dates are equal
--- @return		1   -  if d1 is higher then d2
 function compare(d1, d2)
 
 	if d1:match("[^0-9]") then d1 = to_unix(d1) end

modules/luci-base/luasrc/http/protocol/date.luadoc

@@ -0,0 +1,46 @@
+---[[
+LuCI http protocol implementation - date helper class.
+
+This class contains functions to parse, compare and format http dates.
+]]
+module "luci.http.protocol.date"
+
+---[[
+Return the time offset in seconds between the UTC and given time zone.
+
+@class function
+@name tz_offset
+@param tz	Symbolic or numeric timezone specifier
+@return		Time offset to UTC in seconds
+]]
+
+---[[
+Parse given HTTP date string and convert it to unix epoch time.
+
+@class function
+@name to_unix
+@param data	String containing the date
+@return		Unix epoch time
+]]
+
+---[[
+Convert the given unix epoch time to valid HTTP date string.
+
+@class function
+@name to_http
+@param time	Unix epoch time
+@return		String containing the formatted date
+]]
+
+---[[
+Compare two dates which can either be unix epoch times or HTTP date strings.
+
+@class function
+@name compare
+@param d1	The first date or epoch time to compare
+@param d2	The first date or epoch time to compare
+@return		-1  -  if d1 is lower then d2
+@return		0   -  if both dates are equal
+@return		1   -  if d1 is higher then d2
+]]
+

modules/luci-base/luasrc/http/protocol/mime.lua

@@ -1,15 +1,12 @@
 -- Copyright 2008 Freifunk Leipzig / Jo-Philipp Wich <jow@openwrt.org>
 -- Licensed to the public under the Apache License 2.0.
 
---- LuCI http protocol implementation - mime helper class.
 -- This class provides functions to guess mime types from file extensions and
 -- vice versa.
 module("luci.http.protocol.mime", package.seeall)
 
 require("luci.util")
 
---- MIME mapping table containg extension - mimetype relations.
--- @class table
 MIME_TYPES = {
     ["txt"]   = "text/plain";
     ["js"]    = "text/javascript";
@@ -54,10 +51,7 @@ MIME_TYPES = {
     ["avi"]   = "video/x-msvideo";
 }
 
---- Extract extension from a filename and return corresponding mime-type or
 -- "application/octet-stream" if the extension is unknown.
--- @param filename	The filename for which the mime type is guessed
--- @return			String containign the determined mime type
 function to_mime(filename)
 	if type(filename) == "string" then
 		local ext = filename:match("[^%.]+$")
@@ -70,10 +64,7 @@ function to_mime(filename)
 	return "application/octet-stream"
 end
 
---- Return corresponding extension for a given mime type or nil if the
 -- given mime-type is unknown.
--- @param mimetype	The mimetype to retrieve the extension from
--- @return			String with the extension or nil for unknown type
 function to_ext(mimetype)
 	if type(mimetype) == "string" then
 		for ext, type in luci.util.kspairs( MIME_TYPES ) do

modules/luci-base/luasrc/http/protocol/mime.luadoc

@@ -0,0 +1,34 @@
+---[[
+LuCI http protocol implementation - mime helper class.
+
+This class provides functions to guess mime types from file extensions and
+vice versa.
+]]
+module "luci.http.protocol.mime"
+
+---[[
+MIME mapping table containg extension - mimetype relations.
+
+@class table
+]]
+
+---[[
+Extract extension from a filename and return corresponding mime-type or
+
+"application/octet-stream" if the extension is unknown.
+@class function
+@name to_mime
+@param filename	The filename for which the mime type is guessed
+@return			String containign the determined mime type
+]]
+
+---[[
+Return corresponding extension for a given mime type or nil if the
+
+given mime-type is unknown.
+@class function
+@name to_ext
+@param mimetype	The mimetype to retrieve the extension from
+@return			String with the extension or nil for unknown type
+]]
+

modules/luci-base/luasrc/i18n.lua

@@ -1,7 +1,6 @@
 -- Copyright 2008 Steven Barth <steven@midlink.org>
 -- Licensed to the public under the Apache License 2.0.
 
---- LuCI translation library.
 module("luci.i18n", package.seeall)
 require("luci.util")
 
@@ -13,27 +12,16 @@ loaded  = {}
 context = luci.util.threadlocal()
 default = "en"
 
---- Clear the translation table.
 function clear()
 end
 
---- Load a translation and copy its data into the translation table.
--- @param file	Language file
--- @param lang	Two-letter language code
--- @param force	Force reload even if already loaded (optional)
--- @return		Success status
 function load(file, lang, force)
 end
 
---- Load a translation file using the default translation language.
 -- Alternatively load the translation of the fallback language.
--- @param file	Language file
--- @param force	Force reload even if already loaded (optional)
 function loadc(file, force)
 end
 
---- Set the context default translation language.
--- @param lang	Two-letter language code
 function setlanguage(lang)
 	context.lang   = lang:gsub("_", "-")
 	context.parent = (context.lang:match("^([a-z][a-z])_"))
@@ -46,36 +34,22 @@ function setlanguage(lang)
 	return context.lang
 end
 
---- Return the translated value for a specific translation key.
--- @param key	Default translation text
--- @return		Translated string
 function translate(key)
 	return tparser.translate(key) or key
 end
 
---- Return the translated value for a specific translation key and use it as sprintf pattern.
--- @param key		Default translation text
--- @param ...		Format parameters
--- @return			Translated and formatted string
 function translatef(key, ...)
 	return tostring(translate(key)):format(...)
 end
 
---- Return the translated value for a specific translation key
 -- and ensure that the returned value is a Lua string value.
 -- This is the same as calling <code>tostring(translate(...))</code>
--- @param key		Default translation text
--- @return			Translated string
 function string(key)
 	return tostring(translate(key))
 end
 
---- Return the translated value for a specific translation key and use it as sprintf pattern.
 -- Ensure that the returned value is a Lua string value.
 -- This is the same as calling <code>tostring(translatef(...))</code>
--- @param key		Default translation text
--- @param ...		Format parameters
--- @return			Translated and formatted string
 function stringf(key, ...)
 	return tostring(translate(key)):format(...)
 end

modules/luci-base/luasrc/i18n.luadoc

@@ -0,0 +1,84 @@
+---[[
+LuCI translation library.
+]]
+module "luci.i18n"
+
+---[[
+Clear the translation table.
+
+
+@class function
+@name clear
+]]
+
+---[[
+Load a translation and copy its data into the translation table.
+
+@class function
+@name load
+@param file	Language file
+@param lang	Two-letter language code
+@param force	Force reload even if already loaded (optional)
+@return		Success status
+]]
+
+---[[
+Load a translation file using the default translation language.
+
+Alternatively load the translation of the fallback language.
+@class function
+@name loadc
+@param file	Language file
+@param force	Force reload even if already loaded (optional)
+]]
+
+---[[
+Set the context default translation language.
+
+@class function
+@name setlanguage
+@param lang	Two-letter language code
+]]
+
+---[[
+Return the translated value for a specific translation key.
+
+@class function
+@name translate
+@param key	Default translation text
+@return		Translated string
+]]
+
+---[[
+Return the translated value for a specific translation key and use it as sprintf pattern.
+
+@class function
+@name translatef
+@param key		Default translation text
+@param ...		Format parameters
+@return			Translated and formatted string
+]]
+
+---[[
+Return the translated value for a specific translation key
+
+and ensure that the returned value is a Lua string value.
+This is the same as calling <code>tostring(translate(...))</code>
+@class function
+@name string
+@param key		Default translation text
+@return			Translated string
+]]
+
+---[[
+Return the translated value for a specific translation key and use it as sprintf pattern.
+
+Ensure that the returned value is a Lua string value.
+This is the same as calling <code>tostring(translatef(...))</code>
+@class function
+@name stringf
+@param key		Default translation text
+@param ...		Format parameters
+@return			Translated and formatted string
+]]
+

modules/luci-base/luasrc/ltn12.lua

@@ -39,7 +39,6 @@ local string = require("string")
 local table = require("table")
 local base = _G
 
---- Diego Nehab's LTN12 - Filters, sources, sinks and pumps.
 -- See http://lua-users.org/wiki/FiltersSourcesAndSinks for design concepts 
 module("luci.ltn12")
 
@@ -56,16 +55,8 @@ _VERSION = "LTN12 1.0.1"
 -- Filter stuff
 -----------------------------------------------------------------------------
 
---- LTN12 Filter constructors
--- @class module
--- @name luci.ltn12.filter
 
---- Return a high level filter that cycles a low-level filter
 -- by passing it each chunk and updating a context between calls. 
--- @param low   Low-level filter
--- @param ctx   Context
--- @param extra Extra argument passed to the low-level filter
--- @return LTN12 filter
 function filter.cycle(low, ctx, extra)
     base.assert(low)
     return function(chunk)
@@ -75,10 +66,7 @@ function filter.cycle(low, ctx, extra)
     end
 end
 
---- Chain a bunch of filters together.
 -- (thanks to Wim Couwenberg)
--- @param ... filters to be chained
--- @return LTN12 filter
 function filter.chain(...)
     local n = table.getn(arg)
     local top, index = 1, 1
@@ -112,34 +100,22 @@ end
 -- Source stuff
 -----------------------------------------------------------------------------
 
---- LTN12 Source constructors
--- @class module
--- @name luci.ltn12.source
 
 -- create an empty source
 local function empty()
     return nil
 end
 
---- Create an empty source.
--- @return LTN12 source
 function source.empty()
     return empty
 end
 
---- Return a source that just outputs an error.
--- @param err Error object
--- @return LTN12 source
 function source.error(err)
     return function()
         return nil, err
     end
 end
 
---- Create a file source.
--- @param handle File handle ready for reading
--- @param io_err IO error object
--- @return LTN12 source
 function source.file(handle, io_err)
     if handle then
         return function()
@@ -151,9 +127,6 @@ function source.file(handle, io_err)
     else return source.error(io_err or "unable to open file") end
 end
 
---- Turn a fancy source into a simple source.
--- @param src fancy source
--- @return LTN12 source
 function source.simplify(src)
     base.assert(src)
     return function()
@@ -164,9 +137,6 @@ function source.simplify(src)
     end
 end
 
---- Create a string source.
--- @param s Data
--- @return LTN12 source
 function source.string(s)
     if s then
         local i = 1
@@ -179,9 +149,6 @@ function source.string(s)
     else return source.empty() end
 end
 
---- Creates rewindable source.
--- @param src LTN12 source to be made rewindable
--- @return LTN12 source
 function source.rewind(src)
     base.assert(src)
     local t = {}
@@ -196,10 +163,6 @@ function source.rewind(src)
     end
 end
 
---- Chain a source and a filter together.
--- @param src LTN12 source
--- @param f LTN12 filter
--- @return LTN12 source
 function source.chain(src, f)
     base.assert(src and f)
     local last_in, last_out = "", ""
@@ -247,11 +210,8 @@ function source.chain(src, f)
     end
 end
 
---- Create a source that produces contents of several sources.
 -- Sources will be used one after the other, as if they were concatenated
 -- (thanks to Wim Couwenberg)
--- @param ... LTN12 sources
--- @return LTN12 source
 function source.cat(...)
     local src = table.remove(arg, 1)
     return function()
@@ -268,13 +228,7 @@ end
 -- Sink stuff
 -----------------------------------------------------------------------------
 
---- LTN12 sink constructors
--- @class module
--- @name luci.ltn12.sink
 
---- Create a sink that stores into a table.
--- @param t output table to store into
--- @return LTN12 sink
 function sink.table(t)
     t = t or {}
     local f = function(chunk, err)
@@ -284,9 +238,6 @@ function sink.table(t)
     return f, t
 end
 
---- Turn a fancy sink into a simple sink.
--- @param snk fancy sink
--- @return LTN12 sink
 function sink.simplify(snk)
     base.assert(snk)
     return function(chunk, err)
@@ -297,10 +248,6 @@ function sink.simplify(snk)
     end
 end
 
---- Create a file sink.
--- @param handle file handle to write to
--- @param io_err IO error
--- @return LTN12 sink
 function sink.file(handle, io_err)
     if handle then
         return function(chunk, err)
@@ -317,25 +264,16 @@ local function null()
     return 1
 end
 
---- Create a sink that discards data.
--- @return LTN12 sink
 function sink.null()
     return null
 end
 
---- Create a sink that just returns an error.
--- @param err Error object
--- @return LTN12 sink
 function sink.error(err)
     return function()
         return nil, err
     end
 end
 
---- Chain a sink with a filter.
--- @param f LTN12 filter
--- @param snk LTN12 sink
--- @return LTN12 sink
 function sink.chain(f, snk)
     base.assert(f and snk)
     return function(chunk, err)
@@ -356,15 +294,7 @@ end
 -- Pump stuff
 -----------------------------------------------------------------------------
 
---- LTN12 pump functions
--- @class module
--- @name luci.ltn12.pump
 
---- Pump one chunk from the source to the sink.
--- @param src LTN12 source
--- @param snk LTN12 sink
--- @return Chunk of data or nil if an error occured
--- @return Error object
 function pump.step(src, snk)
     local chunk, src_err = src()
     local ret, snk_err = snk(chunk, src_err)
@@ -372,12 +302,6 @@ function pump.step(src, snk)
     else return nil, src_err or snk_err end
 end
 
---- Pump all data from a source to a sink, using a step function.
--- @param src LTN12 source
--- @param snk LTN12 sink
--- @param step step function (optional)
--- @return 1 if the operation succeeded otherwise nil
--- @return Error object
 function pump.all(src, snk, step)
     base.assert(src and snk)
     step = step or pump.step

modules/luci-base/luasrc/model/ipkg.lua

@@ -15,7 +15,6 @@ local table = table
 local ipkg = "opkg --force-removal-of-dependent-packages --force-overwrite --nocase"
 local icfg = "/etc/opkg.conf"
 
---- LuCI OPKG call abstraction library
 module "luci.model.ipkg"
 
 
@@ -93,54 +92,31 @@ local function _lookup(act, pkg)
 end
 
 
---- Return information about installed and available packages.
--- @param pkg Limit output to a (set of) packages
--- @return Table containing package information
 function info(pkg)
 	return _lookup("info", pkg)
 end
 
---- Return the package status of one or more packages.
--- @param pkg Limit output to a (set of) packages
--- @return Table containing package status information
 function status(pkg)
 	return _lookup("status", pkg)
 end
 
---- Install one or more packages.
--- @param ... List of packages to install
--- @return Boolean indicating the status of the action
--- @return OPKG return code, STDOUT and STDERR
 function install(...)
 	return _action("install", ...)
 end
 
---- Determine whether a given package is installed.
--- @param pkg Package
--- @return Boolean
 function installed(pkg)
 	local p = status(pkg)[pkg]
 	return (p and p.Status and p.Status.installed)
 end
 
---- Remove one or more packages.
--- @param ... List of packages to install
--- @return Boolean indicating the status of the action
--- @return OPKG return code, STDOUT and STDERR
 function remove(...)
 	return _action("remove", ...)
 end
 
---- Update package lists.
--- @return Boolean indicating the status of the action
--- @return OPKG return code, STDOUT and STDERR
 function update()
 	return _action("update")
 end
 
---- Upgrades all installed packages.
--- @return Boolean indicating the status of the action
--- @return OPKG return code, STDOUT and STDERR
 function upgrade()
 	return _action("upgrade")
 end
@@ -174,33 +150,19 @@ function _list(action, pat, cb)
 	end
 end
 
---- List all packages known to opkg.
--- @param pat	Only find packages matching this pattern, nil lists all packages
--- @param cb	Callback function invoked for each package, receives name, version and description as arguments
--- @return	nothing
 function list_all(pat, cb)
 	_list("list", pat, cb)
 end
 
---- List installed packages.
--- @param pat	Only find packages matching this pattern, nil lists all packages
--- @param cb	Callback function invoked for each package, receives name, version and description as arguments
--- @return	nothing
 function list_installed(pat, cb)
 	_list("list_installed", pat, cb)
 end
 
---- Find packages that match the given pattern.
--- @param pat	Find packages whose names or descriptions match this pattern, nil results in zero results
--- @param cb	Callback function invoked for each patckage, receives name, version and description as arguments
--- @return	nothing
 function find(pat, cb)
 	_list("find", pat, cb)
 end
 
 
---- Determines the overlay root used by opkg.
--- @return		String containing the directory path of the overlay root.
 function overlay_root()
 	local od = "/"
 	local fd = io.open(icfg, "r")

modules/luci-base/luasrc/model/ipkg.luadoc

@@ -0,0 +1,109 @@
+---[[
+LuCI OPKG call abstraction library
+
+module "luci.model.ipkg"
+]]
+
+---[[
+Return information about installed and available packages.
+
+@class function
+@name info
+@param pkg Limit output to a (set of) packages
+@return Table containing package information
+]]
+
+---[[
+Return the package status of one or more packages.
+
+@class function
+@name status
+@param pkg Limit output to a (set of) packages
+@return Table containing package status information
+]]
+
+---[[
+Install one or more packages.
+
+@class function
+@name install
+@param ... List of packages to install
+@return Boolean indicating the status of the action
+@return OPKG return code, STDOUT and STDERR
+]]
+
+---[[
+Determine whether a given package is installed.
+
+@class function
+@name installed
+@param pkg Package
+@return Boolean
+]]
+
+---[[
+Remove one or more packages.
+
+@class function
+@name remove
+@param ... List of packages to install
+@return Boolean indicating the status of the action
+@return OPKG return code, STDOUT and STDERR
+]]
+
+---[[
+Update package lists.
+
+@class function
+@name update
+@return Boolean indicating the status of the action
+@return OPKG return code, STDOUT and STDERR
+]]
+
+---[[
+Upgrades all installed packages.
+
+@class function
+@name upgrade
+@return Boolean indicating the status of the action
+@return OPKG return code, STDOUT and STDERR
+]]
+
+---[[
+List all packages known to opkg.
+
+@class function
+@name list_all
+@param pat	Only find packages matching this pattern, nil lists all packages
+@param cb	Callback function invoked for each package, receives name, version and description as arguments
+@return	nothing
+]]
+
+---[[
+List installed packages.
+
+@class function
+@name list_installed
+@param pat	Only find packages matching this pattern, nil lists all packages
+@param cb	Callback function invoked for each package, receives name, version and description as arguments
+@return	nothing
+]]
+
+---[[
+Find packages that match the given pattern.
+
+@class function
+@name find
+@param pat	Find packages whose names or descriptions match this pattern, nil results in zero results
+@param cb	Callback function invoked for each patckage, receives name, version and description as arguments
+@return	nothing
+]]
+
+---[[
+Determines the overlay root used by opkg.
+
+@class function
+@name overlay_root
+@return		String containing the directory path of the overlay root.
+]]
+

modules/luci-base/luasrc/model/uci.lua

@@ -12,26 +12,18 @@ local require, getmetatable = require, getmetatable
 local error, pairs, ipairs = error, pairs, ipairs
 local type, tostring, tonumber, unpack = type, tostring, tonumber, unpack
 
---- LuCI UCI model library.
 -- The typical workflow for UCI is:  Get a cursor instance from the
 -- cursor factory, modify data (via Cursor.add, Cursor.delete, etc.),
 -- save the changes to the staging area via Cursor.save and finally
 -- Cursor.commit the data to the actual config files.
 -- LuCI then needs to Cursor.apply the changes so deamons etc. are
 -- reloaded.
--- @cstyle	instance
 module "luci.model.uci"
 
---- Create a new UCI-Cursor.
--- @class function
--- @name cursor
--- @return	UCI-Cursor
 cursor = uci.cursor
 
 APIVERSION = uci.APIVERSION
 
---- Create a new Cursor initialized to the state directory.
--- @return UCI cursor
 function cursor_state()
 	return cursor(nil, "/var/state")
 end
@@ -42,9 +34,6 @@ inst_state = cursor_state()
 
 local Cursor = getmetatable(inst)
 
---- Applies UCI configuration changes
--- @param configlist		List of UCI configurations
--- @param command			Don't apply only return the command
 function Cursor.apply(self, configlist, command)
 	configlist = self:_affected(configlist)
 	if command then
@@ -56,10 +45,6 @@ function Cursor.apply(self, configlist, command)
 end
 
 
---- Delete all sections of a given type that match certain criteria.
--- @param config		UCI config
--- @param type			UCI section type
--- @param comparator	Function that will be called for each section and
 -- returns a boolean whether to delete the current section (optional)
 function Cursor.delete_all(self, config, stype, comparator)
 	local del = {}
@@ -90,12 +75,6 @@ function Cursor.delete_all(self, config, stype, comparator)
 	end
 end
 
---- Create a new section and initialize it with data.
--- @param config	UCI config
--- @param type		UCI section type
--- @param name		UCI section name (optional)
--- @param values	Table of key - value pairs to initialize the section with
--- @return			Name of created section
 function Cursor.section(self, config, type, name, values)
 	local stat = true
 	if name then
@@ -112,10 +91,6 @@ function Cursor.section(self, config, type, name, values)
 	return stat and name
 end
 
---- Updated the data of a section using data from a table.
--- @param config	UCI config
--- @param section	UCI section name (optional)
--- @param values	Table of key - value pairs to update the section with
 function Cursor.tset(self, config, section, values)
 	local stat = true
 	for k, v in pairs(values) do
@@ -126,21 +101,11 @@ function Cursor.tset(self, config, section, values)
 	return stat
 end
 
---- Get a boolean option and return it's value as true or false.
--- @param config	UCI config
--- @param section	UCI section name
--- @param option	UCI option
--- @return			Boolean
 function Cursor.get_bool(self, ...)
 	local val = self:get(...)
 	return ( val == "1" or val == "true" or val == "yes" or val == "on" )
 end
 
---- Get an option or list and return values as table.
--- @param config	UCI config
--- @param section	UCI section name
--- @param option	UCI option
--- @return			UCI value
 function Cursor.get_list(self, config, section, option)
 	if config and section and option then
 		local val = self:get(config, section, option)
@@ -149,12 +114,6 @@ function Cursor.get_list(self, config, section, option)
 	return nil
 end
 
---- Get the given option from the first section with the given type.
--- @param config	UCI config
--- @param type		UCI section type
--- @param option	UCI option (optional)
--- @param default	Default value (optional)
--- @return			UCI value
 function Cursor.get_first(self, conf, stype, opt, def)
 	local rv = def
 
@@ -178,12 +137,6 @@ function Cursor.get_first(self, conf, stype, opt, def)
 	return rv
 end
 
---- Set given values as list.
--- @param config	UCI config
--- @param section	UCI section name
--- @param option	UCI option
--- @param value		UCI value
--- @return			Boolean whether operation succeeded
 function Cursor.set_list(self, config, section, option, value)
 	if config and section and option then
 		return self:set(
@@ -238,10 +191,8 @@ function Cursor._affected(self, configlist)
 	return reloadlist
 end
 
---- Create a sub-state of this cursor. The sub-state is tied to the parent
 -- curser, means it the parent unloads or loads configs, the sub state will
 -- do so as well.
--- @return			UCI state cursor tied to the parent cursor
 function Cursor.substate(self)
 	Cursor._substates = Cursor._substates or { }
 	Cursor._substates[self] = Cursor._substates[self] or cursor_state()
@@ -265,118 +216,18 @@ function Cursor.unload(self, ...)
 end
 
 
---- Add an anonymous section.
--- @class function
--- @name Cursor.add
--- @param config	UCI config
--- @param type		UCI section type
--- @return			Name of created section
 
---- Get a table of saved but uncommitted changes.
--- @class function
--- @name Cursor.changes
--- @param config	UCI config
--- @return			Table of changes
--- @see Cursor.save
 
---- Commit saved changes.
--- @class function
--- @name Cursor.commit
--- @param config	UCI config
--- @return			Boolean whether operation succeeded
--- @see Cursor.revert
--- @see Cursor.save
 
---- Deletes a section or an option.
--- @class function
--- @name Cursor.delete
--- @param config	UCI config
--- @param section	UCI section name
--- @param option	UCI option (optional)
--- @return			Boolean whether operation succeeded
 
---- Call a function for every section of a certain type.
--- @class function
--- @name Cursor.foreach
--- @param config	UCI config
--- @param type		UCI section type
--- @param callback	Function to be called
--- @return			Boolean whether operation succeeded
 
---- Get a section type or an option
--- @class function
--- @name Cursor.get
--- @param config	UCI config
--- @param section	UCI section name
--- @param option	UCI option (optional)
--- @return			UCI value
 
---- Get all sections of a config or all values of a section.
--- @class function
--- @name Cursor.get_all
--- @param config	UCI config
--- @param section	UCI section name (optional)
--- @return			Table of UCI sections or table of UCI values
 
---- Manually load a config.
--- @class function
--- @name Cursor.load
--- @param config	UCI config
--- @return			Boolean whether operation succeeded
--- @see Cursor.save
--- @see Cursor.unload
 
---- Revert saved but uncommitted changes.
--- @class function
--- @name Cursor.revert
--- @param config	UCI config
--- @return			Boolean whether operation succeeded
--- @see Cursor.commit
--- @see Cursor.save
 
---- Saves changes made to a config to make them committable.
--- @class function
--- @name Cursor.save
--- @param config	UCI config
--- @return			Boolean whether operation succeeded
--- @see Cursor.load
--- @see Cursor.unload
 
---- Set a value or create a named section.
--- @class function
--- @name Cursor.set
--- @param config	UCI config
--- @param section	UCI section name
--- @param option	UCI option or UCI section type
--- @param value		UCI value or nil if you want to create a section
--- @return			Boolean whether operation succeeded
 
---- Get the configuration directory.
--- @class function
--- @name Cursor.get_confdir
--- @return			Configuration directory
 
---- Get the directory for uncomitted changes.
--- @class function
--- @name Cursor.get_savedir
--- @return			Save directory
 
---- Set the configuration directory.
--- @class function
--- @name Cursor.set_confdir
--- @param directory	UCI configuration directory
--- @return			Boolean whether operation succeeded
 
---- Set the directory for uncommited changes.
--- @class function
--- @name Cursor.set_savedir
--- @param directory	UCI changes directory
--- @return			Boolean whether operation succeeded
 
---- Discard changes made to a config.
--- @class function
--- @name Cursor.unload
--- @param config	UCI config
--- @return			Boolean whether operation succeeded
--- @see Cursor.load
--- @see Cursor.save

modules/luci-base/luasrc/model/uci.luadoc

@@ -0,0 +1,291 @@
+---[[
+LuCI UCI model library.
+
+The typical workflow for UCI is:  Get a cursor instance from the
+cursor factory, modify data (via Cursor.add, Cursor.delete, etc.),
+save the changes to the staging area via Cursor.save and finally
+Cursor.commit the data to the actual config files.
+LuCI then needs to Cursor.apply the changes so deamons etc. are
+reloaded.
+@cstyle	instance
+module "luci.model.uci"
+]]
+
+---[[
+Create a new UCI-Cursor.
+
+@class function
+@name cursor
+@return	UCI-Cursor
+]]
+
+---[[
+Create a new Cursor initialized to the state directory.
+
+@class function
+@name cursor_state
+@return UCI cursor
+]]
+
+---[[
+Applies UCI configuration changes
+
+@class function
+@name Cursor.apply
+@param configlist		List of UCI configurations
+@param command			Don't apply only return the command
+]]
+
+---[[
+Delete all sections of a given type that match certain criteria.
+
+@class function
+@name Cursor.delete_all
+@param config		UCI config
+@param type			UCI section type
+@param comparator	Function that will be called for each section and
+returns a boolean whether to delete the current section (optional)
+]]
+
+---[[
+Create a new section and initialize it with data.
+
+@class function
+@name Cursor.section
+@param config	UCI config
+@param type		UCI section type
+@param name		UCI section name (optional)
+@param values	Table of key - value pairs to initialize the section with
+@return			Name of created section
+]]
+
+---[[
+Updated the data of a section using data from a table.
+
+@class function
+@name Cursor.tset
+@param config	UCI config
+@param section	UCI section name (optional)
+@param values	Table of key - value pairs to update the section with
+]]
+
+---[[
+Get a boolean option and return it's value as true or false.
+
+@class function
+@name Cursor.get_bool
+@param config	UCI config
+@param section	UCI section name
+@param option	UCI option
+@return			Boolean
+]]
+
+---[[
+Get an option or list and return values as table.
+
+@class function
+@name Cursor.get_list
+@param config	UCI config
+@param section	UCI section name
+@param option	UCI option
+@return			UCI value
+]]
+
+---[[
+Get the given option from the first section with the given type.
+
+@class function
+@name Cursor.get_first
+@param config	UCI config
+@param type		UCI section type
+@param option	UCI option (optional)
+@param default	Default value (optional)
+@return			UCI value
+]]
+
+---[[
+Set given values as list.
+
+@class function
+@name Cursor.set_list
+@param config	UCI config
+@param section	UCI section name
+@param option	UCI option
+@param value		UCI value
+@return			Boolean whether operation succeeded
+]]
+
+---[[
+Create a sub-state of this cursor. The sub-state is tied to the parent
+
+curser, means it the parent unloads or loads configs, the sub state will
+do so as well.
+@class function
+@name Cursor.substate
+@return			UCI state cursor tied to the parent cursor
+]]
+
+---[[
+Add an anonymous section.
+
+@class function
+@name Cursor.add
+@param config	UCI config
+@param type		UCI section type
+@return			Name of created section
+]]
+
+---[[
+Get a table of saved but uncommitted changes.
+
+@class function
+@name Cursor.changes
+@param config	UCI config
+@return			Table of changes
+@see Cursor.save
+]]
+
+---[[
+Commit saved changes.
+
+@class function
+@name Cursor.commit
+@param config	UCI config
+@return			Boolean whether operation succeeded
+@see Cursor.revert
+@see Cursor.save
+]]
+
+---[[
+Deletes a section or an option.
+
+@class function
+@name Cursor.delete
+@param config	UCI config
+@param section	UCI section name
+@param option	UCI option (optional)
+@return			Boolean whether operation succeeded
+]]
+
+---[[
+Call a function for every section of a certain type.
+
+@class function
+@name Cursor.foreach
+@param config	UCI config
+@param type		UCI section type
+@param callback	Function to be called
+@return			Boolean whether operation succeeded
+]]
+
+---[[
+Get a section type or an option
+
+@class function
+@name Cursor.get
+@param config	UCI config
+@param section	UCI section name
+@param option	UCI option (optional)
+@return			UCI value
+]]
+
+---[[
+Get all sections of a config or all values of a section.
+
+@class function
+@name Cursor.get_all
+@param config	UCI config
+@param section	UCI section name (optional)
+@return			Table of UCI sections or table of UCI values
+]]
+
+---[[
+Manually load a config.
+
+@class function
+@name Cursor.load
+@param config	UCI config
+@return			Boolean whether operation succeeded
+@see Cursor.save
+@see Cursor.unload
+]]
+
+---[[
+Revert saved but uncommitted changes.
+
+@class function
+@name Cursor.revert
+@param config	UCI config
+@return			Boolean whether operation succeeded
+@see Cursor.commit
+@see Cursor.save
+]]
+
+---[[
+Saves changes made to a config to make them committable.
+
+@class function
+@name Cursor.save
+@param config	UCI config
+@return			Boolean whether operation succeeded
+@see Cursor.load
+@see Cursor.unload
+]]
+
+---[[
+Set a value or create a named section.
+
+@class function
+@name Cursor.set
+@param config	UCI config
+@param section	UCI section name
+@param option	UCI option or UCI section type
+@param value		UCI value or nil if you want to create a section
+@return			Boolean whether operation succeeded
+]]
+
+---[[
+Get the configuration directory.
+
+@class function
+@name Cursor.get_confdir
+@return			Configuration directory
+]]
+
+---[[
+Get the directory for uncomitted changes.
+
+@class function
+@name Cursor.get_savedir
+@return			Save directory
+]]
+
+---[[
+Set the configuration directory.
+
+@class function
+@name Cursor.set_confdir
+@param directory	UCI configuration directory
+@return			Boolean whether operation succeeded
+]]
+
+---[[
+Set the directory for uncommited changes.
+
+@class function
+@name Cursor.set_savedir
+@param directory	UCI changes directory
+@return			Boolean whether operation succeeded
+]]
+
+---[[
+Discard changes made to a config.
+
+@class function
+@name Cursor.unload
+@param config	UCI config
+@return			Boolean whether operation succeeded
+@see Cursor.load
+@see Cursor.save
+]]
+

modules/luci-base/luasrc/sys.lua

@@ -16,27 +16,14 @@ local tonumber, ipairs, pairs, pcall, type, next, setmetatable, require, select
 	tonumber, ipairs, pairs, pcall, type, next, setmetatable, require, select
 
 
---- LuCI Linux and POSIX system utilities.
 module "luci.sys"
 
---- Execute a given shell command and return the error code
--- @class		function
--- @name		call
--- @param 		...		Command to call
--- @return		Error code of the command
 function call(...)
 	return os.execute(...) / 256
 end
 
---- Execute a given shell command and capture its standard output
--- @class		function
--- @name		exec
--- @param command	Command to call
--- @return			String containg the return the output of the command
 exec = luci.util.exec
 
---- Retrieve information about currently mounted file systems.
--- @return 	Table containing mount information
 function mounts()
 	local data = {}
 	local k = {"fs", "blocks", "used", "available", "percent", "mountpoint"}
@@ -82,20 +69,11 @@ function mounts()
 	return data
 end
 
---- Retrieve environment variables. If no variable is given then a table
 -- containing the whole environment is returned otherwise this function returns
 -- the corresponding string value for the given name or nil if no such variable
 -- exists.
--- @class		function
--- @name		getenv
--- @param var	Name of the environment variable to retrieve (optional)
--- @return		String containg the value of the specified variable
--- @return		Table containing all variables if no variable name is given
 getenv = nixio.getenv
 
---- Get or set the current hostname.
--- @param		String containing a new hostname to set (optional)
--- @return		String containing the system hostname
 function hostname(newname)
 	if type(newname) == "string" and #newname > 0 then
 		fs.writefile( "/proc/sys/kernel/hostname", newname )
@@ -105,11 +83,6 @@ function hostname(newname)
 	end
 end
 
---- Returns the contents of a documented referred by an URL.
--- @param url	 The URL to retrieve
--- @param stream Return a stream instead of a buffer
--- @param target Directly write to target file name
--- @return		String containing the contents of given the URL
 function httpget(url, stream, target)
 	if not target then
 		local source = stream and io.popen or luci.util.exec
@@ -120,46 +93,30 @@ function httpget(url, stream, target)
 	end
 end
 
---- Initiate a system reboot.
--- @return	Return value of os.execute()
 function reboot()
 	return os.execute("reboot >/dev/null 2>&1")
 end
 
---- Retrieves the output of the "logread" command.
--- @return	String containing the current log buffer
 function syslog()
 	return luci.util.exec("logread")
 end
 
---- Retrieves the output of the "dmesg" command.
--- @return	String containing the current log buffer
 function dmesg()
 	return luci.util.exec("dmesg")
 end
 
---- Generates a random id with specified length.
--- @param bytes	Number of bytes for the unique id
--- @return		String containing hex encoded id
 function uniqueid(bytes)
 	local rand = fs.readfile("/dev/urandom", bytes)
 	return rand and nixio.bin.hexlify(rand)
 end
 
---- Returns the current system uptime stats.
--- @return	String containing total uptime in seconds
 function uptime()
 	return nixio.sysinfo().uptime
 end
 
 
---- LuCI system utilities / network related functions.
--- @class	module
--- @name	luci.sys.net
 net = {}
 
---- Returns the current arp-table entries as two-dimensional table.
--- @return	Table of table containing the current arp entries.
 --			The following fields are defined for arp entry objects:
 --			{ "IP address", "HW address", "HW type", "Flags", "Mask", "Device" }
 function net.arptable(callback)
@@ -269,8 +226,6 @@ local function _nethints(what, callback)
 	end
 end
 
---- Returns a two-dimensional table of mac address hints.
--- @return  Table of table containing known hosts from various sources.
 --          Each entry contains the values in the following order:
 --          [ "mac", "name" ]
 function net.mac_hints(callback)
@@ -293,8 +248,6 @@ function net.mac_hints(callback)
 	end
 end
 
---- Returns a two-dimensional table of IPv4 address hints.
--- @return  Table of table containing known hosts from various sources.
 --          Each entry contains the values in the following order:
 --          [ "ip", "name" ]
 function net.ipv4_hints(callback)
@@ -317,8 +270,6 @@ function net.ipv4_hints(callback)
 	end
 end
 
---- Returns a two-dimensional table of IPv6 address hints.
--- @return  Table of table containing known hosts from various sources.
 --          Each entry contains the values in the following order:
 --          [ "ip", "name" ]
 function net.ipv6_hints(callback)
@@ -341,8 +292,6 @@ function net.ipv6_hints(callback)
 	end
 end
 
---- Returns conntrack information
--- @return	Table with the currently tracked IP connections
 function net.conntrack(callback)
 	local connt = {}
 	if fs.access("/proc/net/nf_conntrack", "r") then
@@ -387,8 +336,6 @@ function net.conntrack(callback)
 	return connt
 end
 
---- Determine the names of available network interfaces.
--- @return	Table containing all current interface names
 function net.devices()
 	local devs = {}
 	for k, v in ipairs(nixio.getifaddrs()) do
@@ -400,8 +347,6 @@ function net.devices()
 end
 
 
---- Return information about available network interfaces.
--- @return	Table containing all current interface names and their information
 function net.deviceinfo()
 	local devs = {}
 	for k, v in ipairs(nixio.getifaddrs()) do
@@ -430,8 +375,6 @@ function net.deviceinfo()
 end
 
 
---- Returns the current kernel routing table entries.
--- @return	Table of tables with properties of the corresponding routes.
 --			The following fields are defined for route entry tables:
 --			{ "dest", "gateway", "metric", "refcount", "usecount", "irtt",
 --			  "flags", "device" }
@@ -477,8 +420,6 @@ function net.routes(callback)
 	return routes
 end
 
---- Returns the current ipv6 kernel routing table entries.
--- @return	Table of tables with properties of the corresponding routes.
 --			The following fields are defined for route entry tables:
 --			{ "source", "dest", "nexthop", "metric", "refcount", "usecount",
 --			  "flags", "device" }
@@ -540,30 +481,18 @@ function net.routes6(callback)
 	end
 end
 
---- Tests whether the given host responds to ping probes.
--- @param host	String containing a hostname or IPv4 address
--- @return		Number containing 0 on success and >= 1 on error
 function net.pingtest(host)
 	return os.execute("ping -c1 '"..host:gsub("'", '').."' >/dev/null 2>&1")
 end
 
 
---- LuCI system utilities / process related functions.
--- @class	module
--- @name	luci.sys.process
 process = {}
 
---- Get the current process id.
--- @class function
--- @name  process.info
--- @return	Number containing the current pid
 function process.info(key)
 	local s = {uid = nixio.getuid(), gid = nixio.getgid()}
 	return not key and s or s[key]
 end
 
---- Retrieve information about currently running processes.
--- @return 	Table containing process information
 function process.list()
 	local data = {}
 	local k
@@ -596,51 +525,22 @@ function process.list()
 	return data
 end
 
---- Set the gid of a process identified by given pid.
--- @param gid	Number containing the Unix group id
--- @return		Boolean indicating successful operation
--- @return		String containing the error message if failed
--- @return		Number containing the error code if failed
 function process.setgroup(gid)
 	return nixio.setgid(gid)
 end
 
---- Set the uid of a process identified by given pid.
--- @param uid	Number containing the Unix user id
--- @return		Boolean indicating successful operation
--- @return		String containing the error message if failed
--- @return		Number containing the error code if failed
 function process.setuser(uid)
 	return nixio.setuid(uid)
 end
 
---- Send a signal to a process identified by given pid.
--- @class function
--- @name  process.signal
--- @param pid	Number containing the process id
--- @param sig	Signal to send (default: 15 [SIGTERM])
--- @return		Boolean indicating successful operation
--- @return		Number containing the error code if failed
 process.signal = nixio.kill
 
 
---- LuCI system utilities / user related functions.
--- @class	module
--- @name	luci.sys.user
 user = {}
 
---- Retrieve user informations for given uid.
--- @class		function
--- @name		getuser
--- @param uid	Number containing the Unix user id
--- @return		Table containing the following fields:
 --				{ "uid", "gid", "name", "passwd", "dir", "shell", "gecos" }
 user.getuser = nixio.getpw
 
---- Retrieve the current user password hash.
--- @param username	String containing the username to retrieve the password for
--- @return			String containing the hash or nil if no password is set.
--- @return			Password database entry
 function user.getpasswd(username)
 	local pwe = nixio.getsp and nixio.getsp(username) or nixio.getpw(username)
 	local pwh = pwe and (pwe.pwdp or pwe.passwd)
@@ -651,10 +551,6 @@ function user.getpasswd(username)
 	end
 end
 
---- Test whether given string matches the password of a given system user.
--- @param username	String containing the Unix user name
--- @param pass		String containing the password to compare
--- @return			Boolean indicating wheather the passwords are equal
 function user.checkpasswd(username, pass)
 	local pwh, pwe = user.getpasswd(username)
 	if pwe then
@@ -663,10 +559,6 @@ function user.checkpasswd(username, pass)
 	return false
 end
 
---- Change the password of given user.
--- @param username	String containing the Unix user name
--- @param password	String containing the password to compare
--- @return			Number containing 0 on success and >= 1 on error
 function user.setpasswd(username, password)
 	if password then
 		password = password:gsub("'", [['"'"']])
@@ -683,14 +575,8 @@ function user.setpasswd(username, password)
 end
 
 
---- LuCI system utilities / wifi related functions.
--- @class	module
--- @name	luci.sys.wifi
 wifi = {}
 
---- Get wireless information for given interface.
--- @param ifname        String containing the interface name
--- @return              A wrapped iwinfo object instance
 function wifi.getiwinfo(ifname)
 	local stat, iwinfo = pcall(require, "iwinfo")
 
@@ -736,14 +622,9 @@ function wifi.getiwinfo(ifname)
 end
 
 
---- LuCI system utilities / init related functions.
--- @class	module
--- @name	luci.sys.init
 init = {}
 init.dir = "/etc/init.d/"
 
---- Get the names of all installed init scripts
--- @return	Table containing the names of all inistalled init scripts
 function init.names()
 	local names = { }
 	for name in fs.glob(init.dir.."*") do
@@ -752,9 +633,6 @@ function init.names()
 	return names
 end
 
---- Get the index of he given init script
--- @param name	Name of the init script
--- @return		Numeric index value
 function init.index(name)
 	if fs.access(init.dir..name) then
 		return call("env -i sh -c 'source %s%s enabled; exit ${START:-255}' >/dev/null"
@@ -768,37 +646,22 @@ local function init_action(action, name)
 	end
 end
 
---- Test whether the given init script is enabled
--- @param name	Name of the init script
--- @return		Boolean indicating whether init is enabled
 function init.enabled(name)
 	return (init_action("enabled", name) == 0)
 end
 
---- Enable the given init script
--- @param name	Name of the init script
--- @return		Boolean indicating success
 function init.enable(name)
 	return (init_action("enable", name) == 1)
 end
 
---- Disable the given init script
--- @param name	Name of the init script
--- @return		Boolean indicating success
 function init.disable(name)
 	return (init_action("disable", name) == 0)
 end
 
---- Start the given init script
--- @param name	Name of the init script
--- @return		Boolean indicating success
 function init.start(name)
 	return (init_action("start", name) == 0)
 end
 
---- Stop the given init script
--- @param name	Name of the init script
--- @return		Boolean indicating success
 function init.stop(name)
 	return (init_action("stop", name) == 0)
 end

modules/luci-base/luasrc/sys.luadoc

@@ -0,0 +1,396 @@
+---[[
+LuCI Linux and POSIX system utilities.
+
+module "luci.sys"
+]]
+
+---[[
+Execute a given shell command and return the error code
+
+@class		function
+@name		call
+@param 		...		Command to call
+@return		Error code of the command
+]]
+
+---[[
+Execute a given shell command and capture its standard output
+
+@class		function
+@name		exec
+@param command	Command to call
+@return			String containg the return the output of the command
+]]
+
+---[[
+Retrieve information about currently mounted file systems.
+
+@class function
+@name mounts
+@return 	Table containing mount information
+]]
+
+---[[
+Retrieve environment variables. If no variable is given then a table
+
+containing the whole environment is returned otherwise this function returns
+the corresponding string value for the given name or nil if no such variable
+exists.
+@class		function
+@name		getenv
+@param var	Name of the environment variable to retrieve (optional)
+@return		String containg the value of the specified variable
+@return		Table containing all variables if no variable name is given
+]]
+
+---[[
+Get or set the current hostname.
+
+@class function
+@name hostname
+@param		String containing a new hostname to set (optional)
+@return		String containing the system hostname
+]]
+
+---[[
+Returns the contents of a documented referred by an URL.
+
+@class function
+@name httpget
+@param url	 The URL to retrieve
+@param stream Return a stream instead of a buffer
+@param target Directly write to target file name
+@return		String containing the contents of given the URL
+]]
+
+---[[
+Initiate a system reboot.
+
+@class function
+@name reboot
+@return	Return value of os.execute()
+]]
+
+---[[
+Retrieves the output of the "logread" command.
+
+@class function
+@name syslog
+@return	String containing the current log buffer
+]]
+
+---[[
+Retrieves the output of the "dmesg" command.
+
+@class function
+@name dmesg
+@return	String containing the current log buffer
+]]
+
+---[[
+Generates a random id with specified length.
+
+@class function
+@name uniqueid
+@param bytes	Number of bytes for the unique id
+@return		String containing hex encoded id
+]]
+
+---[[
+Returns the current system uptime stats.
+
+@class function
+@name uptime
+@return	String containing total uptime in seconds
+]]
+
+---[[
+LuCI system utilities / network related functions.
+
+@class	module
+@name	luci.sys.net
+]]
+
+---[[
+Returns the current arp-table entries as two-dimensional table.
+
+@class function
+@name net.arptable
+@return	Table of table containing the current arp entries.
+--			The following fields are defined for arp entry objects:
+--			{ "IP address", "HW address", "HW type", "Flags", "Mask", "Device" }
+]]
+
+---[[
+Returns a two-dimensional table of mac address hints.
+
+@class function
+@name net.mac_hints
+@return  Table of table containing known hosts from various sources.
+         Each entry contains the values in the following order:
+         [ "mac", "name" ]
+]]
+
+---[[
+Returns a two-dimensional table of IPv4 address hints.
+
+@class function
+@name net.ipv4_hints
+@return  Table of table containing known hosts from various sources.
+         Each entry contains the values in the following order:
+         [ "ip", "name" ]
+]]
+
+---[[
+Returns a two-dimensional table of IPv6 address hints.
+
+@class function
+@name net.ipv6_hints
+@return  Table of table containing known hosts from various sources.
+         Each entry contains the values in the following order:
+         [ "ip", "name" ]
+]]
+
+---[[
+Returns conntrack information
+
+@class function
+@name net.conntrack
+@return	Table with the currently tracked IP connections
+]]
+
+---[[
+Determine the names of available network interfaces.
+
+@class function
+@name net.devices
+@return	Table containing all current interface names
+]]
+
+---[[
+Return information about available network interfaces.
+
+@class function
+@name net.deviceinfo
+@return	Table containing all current interface names and their information
+]]
+
+---[[
+Returns the current kernel routing table entries.
+
+@class function
+@name net.routes
+@return	Table of tables with properties of the corresponding routes.
+--			The following fields are defined for route entry tables:
+--			{ "dest", "gateway", "metric", "refcount", "usecount", "irtt",
+--			  "flags", "device" }
+]]
+
+---[[
+Returns the current ipv6 kernel routing table entries.
+
+@class function
+@name net.routes6
+@return	Table of tables with properties of the corresponding routes.
+--			The following fields are defined for route entry tables:
+--			{ "source", "dest", "nexthop", "metric", "refcount", "usecount",
+--			  "flags", "device" }
+]]
+
+---[[
+Tests whether the given host responds to ping probes.
+
+@class function
+@name net.pingtest
+@param host	String containing a hostname or IPv4 address
+@return		Number containing 0 on success and >= 1 on error
+]]
+
+---[[
+LuCI system utilities / process related functions.
+
+@class	module
+@name	luci.sys.process
+]]
+
+---[[
+Get the current process id.
+
+@class function
+@name  process.info
+@return	Number containing the current pid
+]]
+
+---[[
+Retrieve information about currently running processes.
+
+@class function
+@name process.list
+@return 	Table containing process information
+]]
+
+---[[
+Set the gid of a process identified by given pid.
+
+@class function
+@name process.setgroup
+@param gid	Number containing the Unix group id
+@return		Boolean indicating successful operation
+@return		String containing the error message if failed
+@return		Number containing the error code if failed
+]]
+
+---[[
+Set the uid of a process identified by given pid.
+
+@class function
+@name process.setuser
+@param uid	Number containing the Unix user id
+@return		Boolean indicating successful operation
+@return		String containing the error message if failed
+@return		Number containing the error code if failed
+]]
+
+---[[
+Send a signal to a process identified by given pid.
+
+@class function
+@name  process.signal
+@param pid	Number containing the process id
+@param sig	Signal to send (default: 15 [SIGTERM])
+@return		Boolean indicating successful operation
+@return		Number containing the error code if failed
+]]
+
+---[[
+LuCI system utilities / user related functions.
+
+@class	module
+@name	luci.sys.user
+]]
+
+---[[
+Retrieve user informations for given uid.
+
+@class		function
+@name		getuser
+@param uid	Number containing the Unix user id
+@return		Table containing the following fields:
+--				{ "uid", "gid", "name", "passwd", "dir", "shell", "gecos" }
+]]
+
+---[[
+Retrieve the current user password hash.
+
+@class function
+@name user.getpasswd
+@param username	String containing the username to retrieve the password for
+@return			String containing the hash or nil if no password is set.
+@return			Password database entry
+]]
+
+---[[
+Test whether given string matches the password of a given system user.
+
+@class function
+@name user.checkpasswd
+@param username	String containing the Unix user name
+@param pass		String containing the password to compare
+@return			Boolean indicating wheather the passwords are equal
+]]
+
+---[[
+Change the password of given user.
+
+@class function
+@name user.setpasswd
+@param username	String containing the Unix user name
+@param password	String containing the password to compare
+@return			Number containing 0 on success and >= 1 on error
+]]
+
+---[[
+LuCI system utilities / wifi related functions.
+
+@class	module
+@name	luci.sys.wifi
+]]
+
+---[[
+Get wireless information for given interface.
+
+@class function
+@name wifi.getiwinfo
+@param ifname        String containing the interface name
+@return              A wrapped iwinfo object instance
+]]
+
+---[[
+LuCI system utilities / init related functions.
+
+@class	module
+@name	luci.sys.init
+]]
+
+---[[
+Get the names of all installed init scripts
+
+@class function
+@name init.names
+@return	Table containing the names of all inistalled init scripts
+]]
+
+---[[
+Get the index of he given init script
+
+@class function
+@name init.index
+@param name	Name of the init script
+@return		Numeric index value
+]]
+
+---[[
+Test whether the given init script is enabled
+
+@class function
+@name init.enabled
+@param name	Name of the init script
+@return		Boolean indicating whether init is enabled
+]]
+
+---[[
+Enable the given init script
+
+@class function
+@name init.enable
+@param name	Name of the init script
+@return		Boolean indicating success
+]]
+
+---[[
+Disable the given init script
+
+@class function
+@name init.disable
+@param name	Name of the init script
+@return		Boolean indicating success
+]]
+
+---[[
+Start the given init script
+
+@class function
+@name init.start
+@param name	Name of the init script
+@return		Boolean indicating success
+]]
+
+---[[
+Stop the given init script
+
+@class function
+@name init.stop
+@param name	Name of the init script
+@return		Boolean indicating success
+]]
+

modules/luci-base/luasrc/sys/iptparser.lua

@@ -21,15 +21,8 @@ luci.ip     = require "luci.ip"
 
 local tonumber, ipairs, table = tonumber, ipairs, table
 
---- LuCI iptables parser and query library
--- @cstyle	instance
 module("luci.sys.iptparser")
 
---- Create a new iptables parser object.
--- @class	function
--- @name	IptParser
--- @param	family	Number specifying the address family. 4 for IPv4, 6 for IPv6
--- @return	IptParser instance
 IptParser = luci.util.class()
 
 function IptParser.__init__( self, family )
@@ -50,7 +43,6 @@ function IptParser.__init__( self, family )
 	self:_parse_rules()
 end
 
---- Find all firewall rules that match the given criteria. Expects a table with
 -- search criteria as only argument. If args is nil or an empty table then all
 -- rules will be returned.
 --
@@ -108,8 +100,6 @@ end
 -- This will match all rules with target "-j REJECT",
 -- protocol "-p tcp" (or "-p all")
 -- and the option "--reject-with tcp-reset".
--- @params args		Table containing the search arguments (optional)
--- @return			Table of matching rule tables
 function IptParser.find( self, args )
 
 	local args = args or { }
@@ -205,9 +195,7 @@ function IptParser.find( self, args )
 end
 
 
---- Rebuild the internal lookup table, for example when rules have changed
 -- through external commands.
--- @return	nothing
 function IptParser.resync( self )
 	self._rules = { }
 	self._chain = nil
@@ -215,16 +203,11 @@ function IptParser.resync( self )
 end
 
 
---- Find the names of all tables.
--- @return		Table of table names.
 function IptParser.tables( self )
 	return self._tables
 end
 
 
---- Find the names of all chains within the given table name.
--- @param table	String containing the table name
--- @return		Table of chain names in the order they occur.
 function IptParser.chains( self, table )
 	local lookup = { }
 	local chains = { }
@@ -238,19 +221,12 @@ function IptParser.chains( self, table )
 end
 
 
---- Return the given firewall chain within the given table name.
--- @param table	String containing the table name
--- @param chain	String containing the chain name
--- @return		Table containing the fields "policy", "packets", "bytes"
 --				and "rules". The "rules" field is a table of rule tables.
 function IptParser.chain( self, table, chain )
 	return self._chains[table:lower()] and self._chains[table:lower()][chain]
 end
 
 
---- Test whether the given target points to a custom chain.
--- @param target	String containing the target action
--- @return			Boolean indicating whether target is a custom chain.
 function IptParser.is_custom_target( self, target )
 	for _, r in ipairs(self._rules) do
 		if r.chain == target then

modules/luci-base/luasrc/sys/iptparser.luadoc

@@ -0,0 +1,69 @@
+---[[
+LuCI iptables parser and query library
+
+@cstyle	instance
+]]
+module "luci.sys.iptparser"
+
+---[[
+Create a new iptables parser object.
+
+@class	function
+@name	IptParser
+@param	family	Number specifying the address family. 4 for IPv4, 6 for IPv6
+@return	IptParser instance
+]]
+
+---[[
+Find all firewall rules that match the given criteria. Expects a table with
+
+search criteria as only argument. If args is nil or an empty table then all
+rules will be returned.
+]]
+
+---[[
+Rebuild the internal lookup table, for example when rules have changed
+
+through external commands.
+@class function
+@name IptParser.resync
+@return	nothing
+]]
+
+---[[
+Find the names of all tables.
+
+@class function
+@name IptParser.tables
+@return		Table of table names.
+]]
+
+---[[
+Find the names of all chains within the given table name.
+
+@class function
+@name IptParser.chains
+@param table	String containing the table name
+@return		Table of chain names in the order they occur.
+]]
+
+---[[
+Return the given firewall chain within the given table name.
+
+@class function
+@name IptParser.chain
+@param table	String containing the table name
+@param chain	String containing the chain name
+@return		Table containing the fields "policy", "packets", "bytes"
+--				and "rules". The "rules" field is a table of rule tables.
+]]
+
+---[[
+Test whether the given target points to a custom chain.
+
+@class function
+@name IptParser.is_custom_target
+@param target	String containing the target action
+@return			Boolean indicating whether target is a custom chain.
+]]
+

modules/luci-base/luasrc/util.lua

@@ -20,7 +20,6 @@ local ipairs, pairs, next, loadstring = ipairs, pairs, next, loadstring
 local require, pcall, xpcall = require, pcall, xpcall
 local collectgarbage, get_memory_limit = collectgarbage, get_memory_limit
 
---- LuCI utility functions.
 module "luci.util"
 
 --
@@ -54,7 +53,6 @@ local function _instantiate(class, ...)
 	return inst
 end
 
---- 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
@@ -64,10 +62,6 @@ end
 -- 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.
--- @param base	The base class to inherit from (optional)
--- @return		A class object
--- @see			instanceof
--- @see			clone
 function class(base)
 	return setmetatable({}, {
 		__call  = _instantiate,
@@ -75,12 +69,6 @@ function class(base)
 	})
 end
 
---- Test whether the given object is an instance of the given class.
--- @param object	Object instance
--- @param class		Class object to test against
--- @return			Boolean indicating whether the object is an instance
--- @see				class
--- @see				clone
 function instanceof(object, class)
 	local meta = getmetatable(object)
 	while meta and meta.__index do
@@ -117,10 +105,8 @@ local tl_meta = {
 	end
 }
 
---- 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.
--- @return	Table value representing the corresponding thread local store
 function threadlocal(tbl)
 	return setmetatable(tbl or {}, tl_meta)
 end
@@ -130,17 +116,10 @@ end
 -- Debugging routines
 --
 
---- Write given object to stderr.
--- @param obj	Value to write to stderr
--- @return		Boolean indicating whether the write operation was successful
 function perror(obj)
 	return io.stderr:write(tostring(obj) .. "\n")
 end
 
---- Recursively dumps a table to stdout, useful for testing and debugging.
--- @param t	Table value to dump
--- @param maxdepth	Maximum depth
--- @return	Always nil
 function dumptable(t, maxdepth, i, seen)
 	i = i or 0
 	seen = seen or setmetatable({}, {__mode="k"})
@@ -163,31 +142,19 @@ end
 -- String and data manipulation routines
 --
 
---- Create valid XML PCDATA from given string.
--- @param value	String value containing the data to escape
--- @return		String value containing the escaped data
 function pcdata(value)
 	return value and tparser.pcdata(tostring(value))
 end
 
---- Strip HTML tags from given string.
--- @param value	String containing the HTML text
--- @return	String with HTML tags stripped of
 function striptags(value)
 	return value and tparser.striptags(tostring(value))
 end
 
---- 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.
--- @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
 function split(str, pat, max, regex)
 	pat = pat or "\n"
 	max = max or #str
@@ -221,29 +188,19 @@ function split(str, pat, max, regex)
 	return t
 end
 
---- Remove leading and trailing whitespace from given string value.
--- @param str	String value containing whitespace padded data
--- @return		String value with leading and trailing space removed
 function trim(str)
 	return (str:gsub("^%s*(.-)%s*$", "%1"))
 end
 
---- Count the occurences of given substring in given string.
--- @param str		String to search in
--- @param pattern	String containing pattern to find
--- @return			Number of found occurences
 function cmatch(str, pat)
 	local count = 0
 	for _ in str:gmatch(pat) do count = count + 1 end
 	return count
 end
 
---- 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.
--- @param val		The value to scan (table, string or nil)
--- @return			Iterator which returns one token per call
 function imatch(v)
 	if type(v) == "table" then
 		local k = nil
@@ -268,7 +225,6 @@ function imatch(v)
 	return function() end
 end
 
---- 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)
@@ -283,8 +239,6 @@ end
 --  o "kib" - one si kilobyte (1000)
 --  o "mib"	- one si megabyte (1000*1000)
 --  o "gib"	- one si gigabyte (1000*1000*1000)
--- @param ustr	String containing a numerical value with trailing unit
--- @return		Number containing the canonical value
 function parse_units(ustr)
 
 	local val = 0
@@ -336,10 +290,6 @@ string.cmatch      = cmatch
 string.parse_units = parse_units
 
 
---- Appends numerically indexed tables or single objects to a given table.
--- @param src	Target table
--- @param ...	Objects to insert
--- @return		Target table
 function append(src, ...)
 	for i, a in ipairs({...}) do
 		if type(a) == "table" then
@@ -353,19 +303,10 @@ function append(src, ...)
 	return src
 end
 
---- Combines two or more numerically indexed tables and single objects into one table.
--- @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
 function combine(...)
 	return append({}, ...)
 end
 
---- Checks whether the given table contains the given value.
--- @param table	Table value
--- @param value	Value to search within the given table
--- @return		Boolean indicating whether the given value occurs within table
 function contains(table, value)
 	for k, v in pairs(table) do
 		if value == v then
@@ -375,20 +316,13 @@ function contains(table, value)
 	return false
 end
 
---- Update values in given table with the values from the second given table.
 -- Both table are - in fact - merged together.
--- @param t			Table which should be updated
--- @param updates	Table containing the values to update
--- @return			Always nil
 function update(t, updates)
 	for k, v in pairs(updates) do
 		t[k] = v
 	end
 end
 
---- Retrieve all keys of given associative table.
--- @param t	Table to extract keys from
--- @return	Sorted table containing the keys
 function keys(t)
 	local keys = { }
 	if t then
@@ -399,10 +333,6 @@ function keys(t)
 	return keys
 end
 
---- Clones the given object and return it's copy.
--- @param object	Table value to clone
--- @param deep		Boolean indicating whether to do recursive cloning
--- @return			Cloned table value
 function clone(object, deep)
 	local copy = {}
 
@@ -417,8 +347,6 @@ function clone(object, deep)
 end
 
 
---- Create a dynamic table which automatically creates subtables.
--- @return	Dynamic Table
 function dtable()
         return setmetatable({}, { __index =
                 function(tbl, key)
@@ -457,12 +385,7 @@ function _serialize_table(t, seen)
 	return idata .. ( #data > 0 and #idata > 0 and ", " or "" ) .. data
 end
 
---- Recursively serialize given data to lua code, suitable for restoring
 -- with loadstring().
--- @param val	Value containing the data to serialize
--- @return		String value containing the serialized code
--- @see			restore_data
--- @see			get_bytecode
 function serialize_data(val, seen)
 	seen = seen or setmetatable({}, {__mode="k"})
 
@@ -483,11 +406,6 @@ function serialize_data(val, seen)
 	end
 end
 
---- Restore data previously serialized with serialize_data().
--- @param str	String containing the data to restore
--- @return		Value containing the restored data structure
--- @see			serialize_data
--- @see			get_bytecode
 function restore_data(str)
 	return loadstring("return " .. str)()
 end
@@ -497,10 +415,7 @@ end
 -- Byte code manipulation routines
 --
 
---- Return the current runtime bytecode of the given data. The byte code
 -- will be stripped before it is returned.
--- @param val	Value to return as bytecode
--- @return		String value containing the bytecode of the given data
 function get_bytecode(val)
 	local code
 
@@ -513,11 +428,8 @@ function get_bytecode(val)
 	return code -- and strip_bytecode(code)
 end
 
---- 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)
--- @param code	String value containing the original lua byte code
--- @return		String value containing the stripped lua byte code
 function strip_bytecode(code)
 	local version, format, endian, int, size, ins, num, lnum = code:byte(5, 12)
 	local subint
@@ -607,27 +519,17 @@ function _sortiter( t, f )
 	end
 end
 
---- Return a key, value iterator which returns the values sorted according to
 -- the provided callback function.
--- @param t	The table to iterate
--- @param f A callback function to decide the order of elements
--- @return	Function value containing the corresponding iterator
 function spairs(t,f)
 	return _sortiter( t, f )
 end
 
---- Return a key, value iterator for the given table.
 -- The table pairs are sorted by key.
--- @param t	The table to iterate
--- @return	Function value containing the corresponding iterator
 function kspairs(t)
 	return _sortiter( t )
 end
 
---- Return a key, value iterator for the given table.
 -- The table pairs are sorted by value.
--- @param t	The table to iterate
--- @return	Function value containing the corresponding iterator
 function vspairs(t)
 	return _sortiter( t, function (a,b) return t[a] < t[b] end )
 end
@@ -637,15 +539,10 @@ end
 -- System utility functions
 --
 
---- Test whether the current system is operating in big endian mode.
--- @return	Boolean value indicating whether system is big endian
 function bigendian()
 	return string.byte(string.dump(function() end), 7) == 0
 end
 
---- Execute given commandline and gather stdout.
--- @param command	String containing command to execute
--- @return			String containing the command's stdout
 function exec(command)
 	local pp   = io.popen(command)
 	local data = pp:read("*a")
@@ -654,9 +551,6 @@ function exec(command)
 	return data
 end
 
---- Return a line-buffered iterator over the output of given command.
--- @param command	String containing the command to execute
--- @return			Iterator
 function execi(command)
 	local pp = io.popen(command)
 
@@ -687,11 +581,6 @@ function execl(command)
 	return data
 end
 
---- Issue an ubus call.
--- @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
 function ubus(object, method, data)
 	if not _ubus_connection then
 		_ubus_connection = _ubus.connect()
@@ -710,10 +599,6 @@ function ubus(object, method, data)
 	end
 end
 
---- Convert data structure to 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
 function serialize_json(x, cb)
 	local rv, push = nil, cb
 	if not push then
@@ -768,8 +653,6 @@ function serialize_json(x, cb)
 end
 
 
---- Returns the absolute path to LuCI base directory.
--- @return		String containing the directory path
 function libpath()
 	return require "nixio.fs".dirname(ldebug.__file__)
 end
@@ -809,11 +692,6 @@ local function copcall_id(trace, ...)
   return ...
 end
 
---- This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
--- @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
 function coxpcall(f, err, ...)
 	local res, co = oldpcall(coroutine.create, f)
@@ -828,10 +706,6 @@ function coxpcall(f, err, ...)
 	return performResume(err, co, ...)
 end
 
---- This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
--- @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
 function copcall(f, ...)
 	return coxpcall(f, copcall_id, ...)

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
+]]
+