libs/core, libs/uci, libs/web: Fixed several inline documentation typos
[project/luci.git] / libs / web / luasrc / http.lua
index bb05c68..e26b3b5 100644 (file)
@@ -7,9 +7,6 @@ HTTP-Header manipulator and form variable preprocessor
 FileId:
 $Id$
 
-ToDo:
-- Cookie handling
-
 License:
 Copyright 2008 Steven Barth <steven@midlink.org>
 
@@ -27,14 +24,14 @@ limitations under the License.
 
 ]]--
 
+--- LuCI Web Framework high-level HTTP functions.
 module("luci.http", package.seeall)
-require("ltn12")
+local ltn12 = require("luci.ltn12")
 require("luci.http.protocol")
 require("luci.util")
 
 context = luci.util.threadlocal()
 
-
 Request = luci.util.class()
 function Request.__init__(self, env, sourcein, sinkerr)
        self.input = sourcein
@@ -51,24 +48,16 @@ function Request.__init__(self, env, sourcein, sinkerr)
                params = luci.http.protocol.urldecode_params(env.QUERY_STRING or ""),
        }
        
-       setmetatable(self.message.params, {__index =
-               function(tbl, key)
-                       setmetatable(tbl, nil)
-
-                       luci.http.protocol.parse_message_body(
-                        self.input,
-                        self.message,
-                        self.filehandler
-                       )
-
-                       return rawget(tbl, key)
-               end
-       })
+       self.parsed_input = false
 end
 
-function Request.formvalue(self, name, default)
+function Request.formvalue(self, name, noparse)
+       if not noparse and not self.parsed_input then
+               self:_parse_input()
+       end
+       
        if name then
-               return self.message.params[name] and tostring(self.message.params[name]) or default
+               return self.message.params[name]
        else
                return self.message.params
        end
@@ -78,6 +67,10 @@ function Request.formvaluetable(self, prefix)
        local vals = {}
        prefix = prefix and prefix .. "." or "."
        
+       if not self.parsed_input then
+               self:_parse_input()
+       end
+       
        local void = self.message.params[nil]
        for k, v in pairs(self.message.params) do
                if k:find(prefix, 1, true) == 1 then
@@ -88,6 +81,13 @@ function Request.formvaluetable(self, prefix)
        return vals
 end
 
+function Request.getcookie(self, name)
+  local c = string.gsub(";" .. (self:getenv("HTTP_COOKIE") or "") .. ";", "%s*;%s*", ";")
+  local p = ";" .. name .. "=(.-);"
+  local i, j, value = c:find(p)
+  return value and urldecode(value)
+end
+
 function Request.getenv(self, name)
        if name then
                return self.message.env[name]
@@ -100,7 +100,16 @@ function Request.setfilehandler(self, callback)
        self.filehandler = callback
 end
 
+function Request._parse_input(self)
+       luci.http.protocol.parse_message_body(
+                self.input,
+                self.message,
+                self.filehandler
+       )
+       self.parsed_input = true
+end
 
+--- Close the HTTP-Connection.
 function close()
        if not context.eoh then
                context.eoh = true
@@ -113,34 +122,46 @@ function close()
        end
 end
 
-function formvalue(...)
-       return context.request:formvalue(...)
-end
-
-function formvaluetable(...)
-       return context.request:formvaluetable(...)
+--- 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
 
-function getvalue(...)
-       return context.request:getvalue(...)
+--- 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
 
-function postvalue(...)
-       return context.request:postvalue(...)
+--- 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
 
-function getenv(...)
-       return context.request:getenv(...)
+--- 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
 
-function setfilehandler(...)
-       return context.request:setfilehandler(...)
+--- 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.status then
-               status()
-       end
        if not context.headers then
                context.headers = {}
        end
@@ -148,10 +169,15 @@ 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)
        header("Content-Type", mime)
 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"
@@ -159,42 +185,54 @@ function status(code, message)
        coroutine.yield(1, code, message)
 end
 
-function write(content)
-       if not content or #content == 0 then
-               return
-       end
-       if not context.eoh then
-               if not context.status then
-                       status()
+--- 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
+                       error(src_err)
+               else
+                       close()
                end
-               if not context.headers or not context.headers["content-type"] then
-                       header("Content-Type", "text/html; charset=utf-8")
+               return true
+       elseif #content == 0 then
+               return true
+       else
+               if not context.eoh then
+                       if not context.status then
+                               status()
+                       end
+                       if not context.headers or not context.headers["content-type"] then
+                               header("Content-Type", "text/html; charset=utf-8")
+                       end
+                       if not context.headers["cache-control"] then
+                               header("Cache-Control", "no-cache")
+                       end
+                       
+                       
+                       context.eoh = true
+                       coroutine.yield(3)
                end
-               
-               context.eoh = true
-               coroutine.yield(3)
-       end
-       coroutine.yield(4, content)
-end
-
-
-function basic_auth(realm, errorpage)
-       header("Status", "401 Unauthorized")
-       header("WWW-Authenticate", string.format('Basic realm="%s"', realm or ""))
-       
-       if errorpage then
-               errorpage()
+               coroutine.yield(4, content)
+               return true
        end
-       
-       close()
 end
 
+--- Redirects the client to a new URL and closes the connection.
+-- @param url  Target URL
 function redirect(url)
-       header("Status", "302 Found")
+       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(table)
        local s="?"
        
@@ -205,5 +243,15 @@ function build_querystring(table)
        return 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 = luci.http.protocol.urldecode
+
+--- Return the URL-encoded equivalent of a string.
+-- @param str          Source string
+-- @return                     URL-encoded string
+-- @see urldecode
 urlencode = luci.http.protocol.urlencode