libs/web: Small improvements, added inline documentation

diff --git a/libs/web/luasrc/config.lua b/libs/web/luasrc/config.lua
index 557303f..72bd5aa 100644 (file)
--- a/libs/web/luasrc/config.lua
+++ b/libs/web/luasrc/config.lua
@@ -27,5 +27,7 @@ limitations under the License.
 
 module("luci.config",
        function(m)
 
 module("luci.config",
        function(m)

-               setmetatable(m, {__index = require("luci.model.uci").get_all("luci")})
+               if pcall(require, "luci.model.uci") then
+                       setmetatable(m, {__index = luci.model.uci.get_all("luci")})
+               end

        end)
\ No newline at end of file
        end)
\ No newline at end of file

diff --git a/libs/web/luasrc/dispatcher.lua b/libs/web/luasrc/dispatcher.lua
index 682511d..628b4e3 100644 (file)
--- a/libs/web/luasrc/dispatcher.lua
+++ b/libs/web/luasrc/dispatcher.lua
@@ -23,6 +23,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 
 ]]--
 limitations under the License.
 
 ]]--

+
+--- LuCI web dispatcher.

 module("luci.dispatcher", package.seeall)
 require("luci.init")
 require("luci.http")
 module("luci.dispatcher", package.seeall)
 require("luci.init")
 require("luci.http")


@@ -38,12 +40,16 @@ local index = nil
 local fi
 
 
 local fi
 
 

--- Builds a URL
+--- Build the URL relative to the server webroot from given virtual path.
+-- @param ...  Virtual path
+-- @return             Relative URL

 function build_url(...)
        return luci.http.getenv("SCRIPT_NAME") .. "/" .. table.concat(arg, "/")
 end
 
 function build_url(...)
        return luci.http.getenv("SCRIPT_NAME") .. "/" .. table.concat(arg, "/")
 end
 

--- Sends a 404 error code and renders the "error404" template if available
+--- Send a 404 error code and render the "error404" template if available.
+-- @param message      Custom error message (optional)
+-- @return                     false

 function error404(message)
        luci.http.status(404, "Not Found")
        message = message or "Not Found"
 function error404(message)
        luci.http.status(404, "Not Found")
        message = message or "Not Found"


@@ -56,7 +62,9 @@ function error404(message)
        return false
 end
 
        return false
 end
 

--- Sends a 500 error code and renders the "error500" template if available
+--- Send a 500 error code and render the "error500" template if available.
+-- @param message      Custom error message (optional)#
+-- @return                     false

 function error500(message)
        luci.http.status(500, "Internal Server Error")
 
 function error500(message)
        luci.http.status(500, "Internal Server Error")
 


@@ -68,7 +76,9 @@ function error500(message)
        return false
 end
 
        return false
 end
 

--- Renders an authorization form
+--- Render and evaluate the system authentication login form.
+-- @param default      Default username
+-- @return                     Authentication status

 function sysauth(default)
        local user = luci.http.formvalue("username")
        local pass = luci.http.formvalue("password")
 function sysauth(default)
        local user = luci.http.formvalue("username")
        local pass = luci.http.formvalue("password")


@@ -87,7 +97,8 @@ function sysauth(default)
        end
 end
 
        end
 end
 

--- Creates a request object for dispatching
+--- Dispatch an HTTP request.
+-- @param request      LuCI HTTP Request object

 function httpdispatch(request)
        luci.http.context.request = request
        context.request = {}
 function httpdispatch(request)
        luci.http.context.request = request
        context.request = {}


@@ -101,7 +112,8 @@ function httpdispatch(request)
        luci.http.close()
 end
 
        luci.http.close()
 end
 

--- Dispatches a request
+--- Dispatches a LuCI virtual path.
+-- @param request      Virtual path

 function dispatch(request)
        context.path = request
        
 function dispatch(request)
        context.path = request
        


@@ -187,7 +199,7 @@ function dispatch(request)
        end
 end
 
        end
 end
 

--- Generates the dispatching tree
+--- Generate the dispatching index using the best possible strategy.

 function createindex()
        local path = luci.sys.libpath() .. "/controller/"
        local suff = ".lua"
 function createindex()
        local path = luci.sys.libpath() .. "/controller/"
        local suff = ".lua"


@@ -199,7 +211,9 @@ function createindex()
        end
 end
 
        end
 end
 

--- Uses fastindex to create the dispatching tree
+--- Generate the dispatching index using the fastindex C-indexer.
+-- @param path         Controller base directory
+-- @param suffix       Controller file suffix

 function createindex_fastindex(path, suffix)
        index = {}
                
 function createindex_fastindex(path, suffix)
        index = {}
                


@@ -215,8 +229,9 @@ function createindex_fastindex(path, suffix)
        end
 end
 
        end
 end
 

--- Calls the index function of all available controllers
--- Fallback for transition purposes / Leave it in as long as it works otherwise throw it away
+--- Generate the dispatching index using the native file-cache based strategy.
+-- @param path         Controller base directory
+-- @param suffix       Controller file suffix

 function createindex_plain(path, suffix)
        index = {}
 
 function createindex_plain(path, suffix)
        index = {}
 


@@ -265,7 +280,8 @@ function createindex_plain(path, suffix)
        end
 end
 
        end
 end
 

--- Creates the dispatching tree from the index
+--- Create the dispatching tree from the index.
+-- Build the index before if it does not exist yet.

 function createtree()
        if not index then
                createindex()
 function createtree()
        if not index then
                createindex()


@@ -297,7 +313,12 @@ function createtree()
        end
 end
 
        end
 end
 

--- Reassigns a node to another position
+--- 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
 function assign(path, clone, title, order)
        local obj  = node(unpack(path))
        obj.nodes  = nil


@@ -320,7 +341,12 @@ function assign(path, clone, title, order)
        return obj
 end
 
        return obj
 end
 

--- Shortcut for creating a dispatching node
+--- 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))
        
 function entry(path, target, title, order)
        local c = node(unpack(path))
        


@@ -332,7 +358,9 @@ function entry(path, target, title, order)
        return c
 end
 
        return c
 end
 

--- Fetch a dispatching node
+--- Fetch or create a new dispatching node.
+-- @param      ...             Virtual path
+-- @return                     Dispatching tree node

 function node(...)
        local c = context.tree
        arg.n = nil
 function node(...)
        local c = context.tree
        arg.n = nil


@@ -353,6 +381,9 @@ function node(...)
 end
 
 -- Subdispatchers --
 end
 
 -- Subdispatchers --

+
+--- Create a redirect to another dispatching node.
+-- @param      ...             Virtual path destination

 function alias(...)
        local req = arg
        return function()
 function alias(...)
        local req = arg
        return function()


@@ -360,6 +391,9 @@ function alias(...)
        end
 end
 
        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 = arg
        return function()
 function rewrite(n, ...)
        local req = arg
        return function()


@@ -375,16 +409,23 @@ function rewrite(n, ...)
        end
 end
 
        end
 end
 

+--- Create a function-call dispatching target.
+-- @param      nane    Target function of local controller 
+-- @param      ...             Additional parameters passed to the function

 function call(name, ...)
        local argv = {...}
        return function() return getfenv()[name](unpack(argv)) end
 end
 
 function call(name, ...)
        local argv = {...}
        return function() return getfenv()[name](unpack(argv)) end
 end
 

+--- Create a template render dispatching target.
+-- @param      nane    Template to be rendered

 function template(name)
        require("luci.template")
        return function() luci.template.render(name) end
 end
 
 function template(name)
        require("luci.template")
        return function() luci.template.render(name) end
 end
 

+--- Create a CBI model dispatching target.
+-- @param      model   CBI model tpo be rendered

 function cbi(model)
        require("luci.cbi")
        require("luci.template")
 function cbi(model)
        require("luci.cbi")
        require("luci.template")

diff --git a/libs/web/luasrc/i18n.lua b/libs/web/luasrc/i18n.lua
index e301162..5f0ee8a 100644 (file)
--- a/libs/web/luasrc/i18n.lua
+++ b/libs/web/luasrc/i18n.lua
@@ -24,6 +24,7 @@ limitations under the License.
 
 ]]--
 
 
 ]]--
 

+--- LuCI translation library.

 module("luci.i18n", package.seeall)
 require("luci.sys")
 
 module("luci.i18n", package.seeall)
 require("luci.sys")
 


@@ -33,12 +34,16 @@ loaded  = {}
 context = luci.util.threadlocal()
 default = "en"
 
 context = luci.util.threadlocal()
 default = "en"
 

--- Clears the translation table
+--- Clear the translation table.

 function clear()
        table = {}
 end
 
 function clear()
        table = {}
 end
 

--- Loads a translation and copies its data into the global translation table
+--- 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)
        lang = lang or ""
        if force or not loaded[lang] or not loaded[lang][file] then
 function load(file, lang, force)
        lang = lang or ""
        if force or not loaded[lang] or not loaded[lang][file] then


@@ -58,25 +63,36 @@ function load(file, lang, force)
        end
 end
 
        end
 end
 

--- Same as load but autocompletes the filename with .LANG from config.lang
+--- 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)
        load(file, default, force)
        return load(file, context.lang, force)
 end
 
 function loadc(file, force)
        load(file, default, force)
        return load(file, context.lang, force)
 end
 

--- Sets the context language
+--- Set the context default translation language.
+-- @param lang Two-letter language code

 function setlanguage(lang)
        context.lang = lang
 end
 
 function setlanguage(lang)
        context.lang = lang
 end
 

--- Returns the i18n-value defined by "key" or if there is no such: "default"
+--- Return the translated value for a specific translation key.
+-- @param key  Translation key
+-- @param def  Default translation
+-- @return             Translated string

 function translate(key, def)
        return (table[context.lang] and table[context.lang][key])
                or (table[default] and table[default][key])
                or def
 end
 
 function translate(key, def)
        return (table[context.lang] and table[context.lang][key])
                or (table[default] and table[default][key])
                or def
 end
 

--- Translate shourtcut with sprintf/string.format inclusion
+--- Return the translated value for a specific translation key and use it as sprintf pattern.
+-- @param key          Translation key
+-- @param default      Default translation
+-- @param ...          Format parameters
+-- @return                     Translated and formatted string

 function translatef(key, default, ...)
        return translate(key, default):format(...)
 end
\ No newline at end of file
 function translatef(key, default, ...)
        return translate(key, default):format(...)
 end
\ No newline at end of file

diff --git a/libs/web/luasrc/sauth.lua b/libs/web/luasrc/sauth.lua
index fc4942b..d25f287 100644 (file)
--- a/libs/web/luasrc/sauth.lua
+++ b/libs/web/luasrc/sauth.lua
@@ -12,6 +12,8 @@ You may obtain a copy of the License at
 $Id$
 
 ]]--
 $Id$
 
 ]]--

+
+--- LuCI session library.

 module("luci.sauth", package.seeall)
 require("luci.fs")
 require("luci.util")
 module("luci.sauth", package.seeall)
 require("luci.fs")
 require("luci.util")


@@ -22,7 +24,7 @@ luci.config.sauth = luci.config.sauth or {}
 sessionpath = luci.config.sauth.sessionpath
 sessiontime = tonumber(luci.config.sauth.sessiontime)
 
 sessionpath = luci.config.sauth.sessionpath
 sessiontime = tonumber(luci.config.sauth.sessiontime)
 

-
+--- Manually clean up expired sessions.

 function clean()
        local now   = os.time()
        local files = luci.fs.dir(sessionpath)
 function clean()
        local now   = os.time()
        local files = luci.fs.dir(sessionpath)


@@ -40,11 +42,15 @@ function clean()
        end
 end
 
        end
 end
 

+--- Prepare session storage by creating the session directory.

 function prepare()
        luci.fs.mkdir(sessionpath)
        luci.fs.chmod(sessionpath, "a-rwx,u+rwx")
 end
 
 function prepare()
        luci.fs.mkdir(sessionpath)
        luci.fs.chmod(sessionpath, "a-rwx,u+rwx")
 end
 

+--- Read a session and return its content.
+-- @param id   Session identifier
+-- @return             Session data

 function read(id)
        if not id then
                return
 function read(id)
        if not id then
                return


@@ -53,6 +59,10 @@ function read(id)
        return luci.fs.readfile(sessionpath .. "/" .. id)
 end
 
        return luci.fs.readfile(sessionpath .. "/" .. id)
 end
 

+
+--- Write session data to a session file.
+-- @param id   Session identifier
+-- @param data Session data

 function write(id, data)
        if not luci.fs.stat(sessionpath) then
                prepare()
 function write(id, data)
        if not luci.fs.stat(sessionpath) then
                prepare()

diff --git a/libs/web/luasrc/template.lua b/libs/web/luasrc/template.lua
index 12b80be..17e1daa 100644 (file)
--- a/libs/web/luasrc/template.lua
+++ b/libs/web/luasrc/template.lua
@@ -23,6 +23,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 
 ]]--
 limitations under the License.
 
 ]]--

+
+--- LuCI template library.

 module("luci.template", package.seeall)
 
 require("luci.config")
 module("luci.template", package.seeall)
 
 require("luci.config")


@@ -50,9 +52,11 @@ viewns = {
        include    = function(name) Template(name):render(getfenv(2)) end,
 }
 
        include    = function(name) Template(name):render(getfenv(2)) end,
 }
 

--- Compiles a given template into an executable Lua module
+--- Manually  compile a given template into an executable Lua function
+-- @param template     LuCI template
+-- @return                     Lua template function

 function compile(template)     
 function compile(template)     

-       -- Search all <% %> expressions (remember: Lua table indexes begin with #1)
+       -- Search all <% %> expressions

        local function expr_add(ws1, skip1, command, skip2, ws2)
                table.insert(expr, command)
                return ( #skip1 > 0 and "" or ws1 ) .. 
        local function expr_add(ws1, skip1, command, skip2, ws2)
                table.insert(expr, command)
                return ( #skip1 > 0 and "" or ws1 ) .. 


@@ -114,7 +118,9 @@ function compile(template)
        return loadstring(template)
 end
 
        return loadstring(template)
 end
 

--- Oldstyle render shortcut
+--- Render a certain template.
+-- @param name         Template name
+-- @param scope                Scope to assign to template

 function render(name, scope, ...)
        scope = scope or getfenv(2)
        local s, t = luci.util.copcall(Template, name)
 function render(name, scope, ...)
        scope = scope or getfenv(2)
        local s, t = luci.util.copcall(Template, name)