svn commit: r1479253 - /httpd/httpd/trunk/docs/manual/developer/lua.xml

[hu...@apache.org]

Author: humbedooh
Date: Sun May  5 08:04:21 2013
New Revision: 1479253

URL: http://svn.apache.org/r1479253
Log:
Remove all the stuff that has been ported to mod_lua, and add an example load balancer.

Modified:
    httpd/httpd/trunk/docs/manual/developer/lua.xml

Modified: httpd/httpd/trunk/docs/manual/developer/lua.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/developer/lua.xml?rev=1479253&r1=1479252&r2=1479253&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/developer/lua.xml (original)
+++ httpd/httpd/trunk/docs/manual/developer/lua.xml Sun May  5 08:04:21 2013
@@ -512,1471 +512,73 @@ end
 </highlight>
 </section>
 
-<section id="map_handler"><title>Example 5: Overlays using LuaMapHandler</title>
+
+<section id="loadbalancing"><title>Example 5: A rudimentary load balancer</title>
 <p>
-Coming soon!
+    This is an example of how you can create a load balancing mechanism. 
+    In this example, we will be setting/getting the number of requests served 
+    by each backend using IVM variables, and preferring the backend with least 
+    requests served in total:
 </p>
 <highlight language="config">
-LuaMapHandler ^/portal/([a-z]+)/   /path/to/lua/script.lua handle_$1
+LuaHookTranslateName /path/to/script.lua proxy_handler
 </highlight>
-</section>
-
-<section id="mod_status_lua"><title>Example 6: Basic Lua scripts</title>
-<p>
-Also coming soon
-</p>
-</section>
-
-
-
-
-
-
-
-<section id="String_manipulation">
-<title>HTTPd bindings: String manipulation</title>
-<p>
-<a href="#apache2.base64_encode">apache2.base64_encode</a>
-<br/>
-<a href="#apache2.base64_decode">apache2.base64_decode</a>
-<br/>
-<a href="#apache2.escape">apache2.escape</a>
-<br/>
-<a href="#apache2.unescape">apache2.unescape</a>
-<br/>
-<a href="#apache2.escapehtml">apache2.escapehtml</a>
-<br/>
-<a href="#apache2.md5">apache2.md5</a>
-<br/>
-<a href="#apache2.sha1">apache2.sha1</a>
-<br/>
-<a href="#apache2.os_escape_path">apache2.os_escape_path</a>
-<br/>
-<a href="#apache2.escape_logitem">apache2.escape_logitem</a>
-<br/>
-</p>
-<section id="apache2.base64_decode">
-<title>apache2.base64_decode(
-    request_rec<em> r</em>,  string<em> string</em>
-    )
-    </title>
-<p>
-Decodes a base64-encoded string
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>string</td>
-<td>The string to decode</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The base64-decoded string.
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local str = "This is a test"
-local encoded = apache2.base64_encode(str)
-local decoded = apache2.base64_decode(encoded)
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.base64_encode">
-<title>apache2.base64_encode(
-    request_rec<em> r</em>,  string<em> string</em>
-    )
-    </title>
-<p>
-Encodes a string using the base64 encoding scheme.
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>string</td>
-<td>The string to encode</td>
-</tr>
-</table>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local str = "This is a test"
-local encoded = apache2.base64_encode(str)
-local decoded = apache2.base64_decode(encoded)
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.escape">
-<title>apache2.escape(
-    request_rec<em> r</em>,  string<em> string</em>
-    )
-    </title>
-<p>
-url-escapes a string
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>string</td>
-<td>The string to escape</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The URL-escaped string.
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local str = "This is a test"
-local escaped = apache2.escape(str)
-print(escaped) -- prints "This+is+a+test"
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.escape_logitem">
-<title>apache2.escape_logitem(
-    request_rec<em> r</em>,  string<em> path</em>
-    )
-    </title>
-<p>
-Escape a string for logging
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>path</td>
-<td>The string to escape</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The converted string
-        </p>
-<p> </p>
-</section>
-<section id="apache2.escapehtml">
-<title>apache2.escapehtml(
-    request_rec<em> r</em>,  string<em> html</em>,  boolean<em> toasc</em>
-    )
-    </title>
-<p>
-Escapes HTML entities.
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>html</td>
-<td>The HTML code to escape</td>
-</tr>
-<tr>
-<td>toasc</td>
-<td>Whether to escape all non-ASCI characters as &amp;#nnn;</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The escaped HTML code.
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local html = "&lt;b&gt;Testing!&lt;/b&gt;"
-local escaped = apache2.escapehtml(html)
-r:puts(escaped) -- prints "&amp;lt;b&amp;gt;Testing!&amp;lt;/b&amp;gt;"
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.md5">
-<title>apache2.md5(
-    request_rec<em> r</em>,  string<em> string</em>
-    )
-    </title>
-<p>
-Computes an MD5 digest sum based on a string (binary safe)
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>string</td>
-<td>The (binary) string to digest</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The MD5 digest sum of the data provided
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local text = "The quick brown fox jumps over the lazy dog"
-local md5 = apache2.md51(text)
-r:puts(md5) -- prints out "9e107d9d372bb6826bd81d3542a419d6"
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.os_escape_path">
-<title>apache2.os_escape_path(
-    request_rec<em> r</em>,  string<em> path</em>,  boolean<em> partial</em>
-    )
-    </title>
-<p>
-convert an OS path to a URL in an OS dependent way.
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>path</td>
-<td>The path to convert</td>
-</tr>
-<tr>
-<td>partial</td>
-<td>partial if set, assume that the path will be appended to something with a '/' in it (and thus does not prefix "./")</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The converted URL
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local path = ap_os_escape_path("C:/foo/bar.txt")
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.sha1">
-<title>apache2.sha1(
-    request_rec<em> r</em>,  string<em> string</em>
-    )
-    </title>
-<p>
-Computes an SHA-1 digest sum based on a string (binary safe)
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>string</td>
-<td>The (binary) string to digest</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The SHA-1 digest sum of the data provided
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local text = "The quick brown fox jumps over the lazy dog"
-local sha1 = apache2.sha1(text)
-r:puts(sha1) -- prints out "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.unescape">
-<title>apache2.unescape(
-    request_rec<em> r</em>,  string<em> string</em>
-    )
-    </title>
-<p>
-unescapes an URL-escaped string
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>string</td>
-<td>The string to unescape</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The URL-unescaped string
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local str = "This+is+a+test"
-local unescaped = apache2.unescape(str)
-print(unescaped) -- prints "This is a test"
-        </highlight>
-<p> </p>
-</section>
-</section>
 
-<section id="Request_handling">
-<title>HTTPd bindings: Request handling</title>
-<p>
-<a href="#apache2.requestbody">apache2.requestbody</a>
-<br/>
-<a href="#apache2.add_input_filter">apache2.add_input_filter</a>
-<br/>
-<a href="#apache2.get_basic_auth_pw">apache2.get_basic_auth_pw</a>
-<br/>
-<a href="#apache2.set_document_root">apache2.set_document_root</a>
-<br/>
-<a href="#apache2.set_context_prefix">apache2.set_context_prefix</a>
-<br/>
-<a href="#apache2.get_server_name_for_url">apache2.get_server_name_for_url</a>
-<br/>
-<a href="#apache2.set_keepalive">apache2.set_keepalive</a>
-<br/>
-<a href="#apache2.make_etag">apache2.make_etag</a>
-<br/>
-<a href="#apache2.send_interim_response">apache2.send_interim_response</a>
-<br/>
-</p>
-<section id="apache2.add_input_filter">
-<title>apache2.add_input_filter(
-    request_rec<em> r</em>,  string<em> filter</em>
-    )
-    </title>
-<p>
-Adds an input filter to the request
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>filter</td>
-<td>The name of the filter handler to add</td>
-</tr>
-</table>
-<p>
-<em>Example:</em>
-</p>
 <highlight language="lua">
-apache2.add_input_filter(r, "SPAM_FILTER") -- Check input for spam..?
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.get_basic_auth_pw">
-<title>apache2.get_basic_auth_pw(
-    request_rec<em> r</em>
-    )
-    </title>
-<p>
-Returns the password from a basic authorization request or nil if none was supplied
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The password from a basic authorization request or nil if none was supplied
-        </p>
-<p> </p>
-</section>
-<section id="apache2.get_server_name_for_url">
-<title>apache2.get_server_name_for_url(
-    request_rec<em> r</em>
-    )
-    </title>
-<p>
-Get the current server name from the request for the purposes of using in a URL. 
-If the server name is an IPv6 literal address, it will be returned in URL format (e.g., "[fe80::1]").
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-</table>
-<p> </p>
-</section>
-<section id="apache2.make_etag">
-<title>apache2.make_etag(
-    request_rec<em> r</em>,  boolean<em> force_weak</em>
-    )
-    </title>
-<p>
-Constructs an entity tag from the resource information.  If it's a real file, build in some of the file characteristics.
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>force_weak</td>
-<td>force_weak Force the entity tag to be weak - it could be modified again in as short an interval.</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The entity tag
-        </p>
-<p> </p>
-</section>
-<section id="apache2.requestbody">
-<title>apache2.requestbody(
-    request_rec<em> r</em>,  number<em> size</em>,  string<em> filename</em>
-    )
-    </title>
-<p>
-Reads the request body. If a filename is specified, the request body will be written to that file and the number of bytes written returned, otherwise, the full request body will be returned as a string.
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>size</td>
-<td>The maximum size allowed, or 0/nil for unlimited size</td>
-</tr>
-<tr>
-<td>filename</td>
-<td>The file to save the output to, or nil to return it as a string</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The number of bytes written if a filename was specified, otherwise it returns the entire request body as a string.
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-if tonumber(r.headers_in['Content-Length'] or 0) &lt; 10000 then
-    local smallfile = apache2.requestbody(r, 10000) -- fetch a small file into memory
-    r:puts("I saved the uploaded file in memory")
-else
-    local read = apache2.requestbody(r, 0, "/path/to/tmp")
-    r:puts("I saved the uploaded file in a temp directory. Total bytes written was: ", read)
-end
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.send_interim_response">
-<title>apache2.send_interim_response(
-    request_rec<em> r</em>,  boolean<em> send_headers</em>
-    )
-    </title>
-<p>
-Sends an interim (HTTP 1xx) response immediately.
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>send_headers</td>
-<td>send_headers Whether to send&amp;clear headers in r-&gt;headers_out</td>
-</tr>
-</table>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-apache2.send_interim_response(r, false)
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.set_context_prefix">
-<title>apache2.set_context_prefix(
-    request_rec<em> r</em>,  string<em> prefix</em>,  string<em> document</em>
-    )
-    </title>
-<p>
-Set context_prefix and context_document_root for a request.
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>prefix</td>
-<td>The URI prefix, without trailing slash</td>
-</tr>
-<tr>
-<td>document</td>
-<td>The corresponding directory on disk, without trailing slash</td>
-</tr>
-</table>
-<p> </p>
-</section>
-<section id="apache2.set_document_root">
-<title>apache2.set_document_root(
-    request_rec<em> r</em>,  string<em> root</em>
-    )
-    </title>
-<p>
-Sets the document root of the request.
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>root</td>
-<td>root</td>
-</tr>
-</table>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
--- Suppose our real document root is /var/bar, then...
-if r.hostname == "www.foo.com" then
-    apache2.set_document_root(r, "/www/foo") -- change document root on the fly
+--[[ 
+     This script uses a basic IVM table to determine where to 
+     send the request.
+]]--
+
+local backends = {
+  “http://backend1.foo.com/“,
+  “http://backend2.foo.com/“,
+  “http://backend3.foo.com/“
+}
+
+function pick_backend(r)
+    local chosen_backend = 1 -- default to backend1
+    local lowest_count = nil
+    for i = 1, #backends, 1 do -- Loop through all backends
+        local count = r:ivm_get("proxy_request_count_" .. i)
+        if not count then -- If this backend hasn't been used at all, prefer it
+            chosen_backend = i
+            lowest_count = 0
+            break
+        end
+        if not lowest_count or lowest_count > count then -- If this backend has had less requests, pick it for now
+            chosen_backend = i
+            lowest_count = count
+        end
+    end
+    lowest_count = lowest_count + 1
+    r:ivm_set("proxy_request_count_" .. chosen_backend, lowest_count)
+    return chosen_backend
 end
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.set_keepalive">
-<title>apache2.set_keepalive(
-    request_rec<em> r</em>
-    )
-    </title>
-<p>
-Sets the keepalive status for this request
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-True if keepalive can be set, false otherwise
-        </p>
-<p> </p>
-</section>
-</section>
 
-<section id="Parser_functions">
-<title>HTTPd bindings: Parser functions</title>
-<p>
-<a href="#apache2.expr">apache2.expr</a>
-<br/>
-<a href="#apache2.regex">apache2.regex</a>
-<br/>
-<a href="#apache2.strcmp_match">apache2.strcmp_match</a>
-<br/>
-</p>
-<section id="apache2.expr">
-<title>apache2.expr(
-    request_rec<em> r</em>,  string<em> expression</em>
-    )
-    </title>
-<p>
-Evaluates an ap_expr (think &lt;If ...&gt;) expression and returns true if the expression is true, false otherwise. A second value containing an error string is returned if the expression is invalid.
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>expression</td>
-<td>expression</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-True if the expression evaluates as true, false if the expression doesn't evaluate as true or if an error occurred. If an error occurred during parsing, a second value will be returned, containng the error string.
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-if apache2.expr("%{REQUEST_URI} =~ /force-gzip") then
-    r:addoutputfilter("DEFLATE")
-end
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.regex">
-<title>apache2.regex(
-    request_rec<em> r</em>,  string<em> expression</em>,  string<em> source</em>
-    )
-    </title>
-<p>
-Evaluates a regular expression and, if it matches the source string, captures the variables and returns the matches as a table. On error, it returns nil.
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>expression</td>
-<td>expression to match for</td>
-</tr>
-<tr>
-<td>source</td>
-<td>the source string to capture from</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-True if the expression evaluates as true, false if the expression doesn't evaluate as true or if an error occurred. If an error occurred during parsing, a second value will be returned, containng the error string.
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local matches = apache2.regex(r, [[(\S+) kitty]], "Hello kitty")
-if matches and matches[1] then 
-    r:puts("You said ", matches[1], " to kitty")
-end
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.strcmp_match">
-<title>apache2.strcmp_match(
-    string<em> str</em>,  string<em> expexted</em>,  boolean<em> ignoreCase</em>
-    )
-    </title>
-<p>
-Determines if a string matches a pattern containing the wildcards '?' or '*'
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>str</td>
-<td>The string to check</td>
-</tr>
-<tr>
-<td>expexted</td>
-<td>The pattern to match against</td>
-</tr>
-<tr>
-<td>ignoreCase</td>
-<td>Whether to ignore case when matching</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-True if the two strings match, false otherwise.
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-if apache2.strcmp_match("foo.bar", "foo.*") then
-    r:puts("It matches!")
+function proxy_handler(r)
+    local backend = pick_backend(r) -- Pick a backend based on no. of requests served
+    r.handler  = "proxy-server"
+    r.proxyreq = apache2.PROXYREQ_REVERSE
+    r.filename = "proxy:" .. backends[backend] .. r.uri
+    return apache2.DECLINED -- let the proxy handler do this instead
 end
-        </highlight>
-<p> </p>
-</section>
+</highlight>
 </section>
 
-<section id="Server_settings">
-<title>HTTPd bindings: Server settings</title>
-<p>
-<a href="#apache2.add_version_component">apache2.add_version_component</a>
-<br/>
-<a href="#apache2.mpm_query">apache2.mpm_query</a>
-<br/>
-<a href="#apache2.terminate">apache2.terminate</a>
-<br/>
-<a href="#apache2.scoreboard_process">apache2.scoreboard_process</a>
-<br/>
-<a href="#apache2.scoreboard_worker">apache2.scoreboard_worker</a>
-<br/>
-<a href="#apache2.module_info">apache2.module_info</a>
-<br/>
-<a href="#apache2.loaded_modules">apache2.loaded_modules</a>
-<br/>
-<a href="#apache2.runtime_dir_relative">apache2.runtime_dir_relative</a>
-<br/>
-<a href="#apache2.server_info">apache2.server_info</a>
-<br/>
-<a href="#apache2.state_query">apache2.state_query</a>
-<br/>
-<a href="#apache2.custom_response">apache2.custom_response</a>
-<br/>
-<a href="#apache2.exists_config_define">apache2.exists_config_define</a>
-<br/>
-</p>
-<section id="apache2.add_version_component">
-<title>apache2.add_version_component(
-    request_rec<em> r</em>,  string<em> component</em>
-    )
-    </title>
-<p>
-Adds a component to the server description and banner strings
-        </p>
+<section id="map_handler"><title>Example 6: Overlays using LuaMapHandler</title>
 <p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>component</td>
-<td>The component to add</td>
-</tr>
-</table>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-if not apache2.banner():match("FooModule") then -- Make sure we haven't added it already
-    apache2.add_version_component(r, "FooModule/1.0")
-end
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.custom_response">
-<title>apache2.custom_response(
-    request_rec<em> r</em>,  number<em> status</em>,  string<em> string</em>
-    )
-    </title>
-<p>
-Install a custom response handler for a given status
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>status</td>
-<td>The status for which the custom response should be used</td>
-</tr>
-<tr>
-<td>string</td>
-<td>The custom response.  This can be a static string, a file or a URL</td>
-</tr>
-</table>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-apache2.custom_response(r, 404, "Not found!!")
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.exists_config_define">
-<title>apache2.exists_config_define(
-    string<em> name</em>
-    )
-    </title>
-<p>
-Checks for a definition from the server command line
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>name</td>
-<td>The define to check for</td>
-</tr>
-</table>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-if apache2.exists_config_define("FOO") then
-    r:puts("This server was started with -DFOO")
-end
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.loaded_modules">
-<title>apache2.loaded_modules(
-    
-    )
-    </title>
-<p>
-Returns a table containing the name (c filename) of all loaded modules
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<p>None</p>
-<p>
-<em>Return value(s):</em>
-<br/>
-A table containing the name (c filename) of all loaded modules
-        </p>
-<p> </p>
-</section>
-<section id="apache2.module_info">
-<title>apache2.module_info(
-    string<em> c</em>,  string<em> file</em>
-    )
-    </title>
-<p>
-Returns information about a specific module (if loaded)
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>c</td>
-<td>c</td>
-</tr>
-<tr>
-<td>file</td>
-<td>file</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The various commands available to this module as a table, or nil if the module wasn't found.
-        </p>
-<p> </p>
-</section>
-<section id="apache2.mpm_query">
-<title>apache2.mpm_query(
-    number<em> i</em>
-    )
-    </title>
-<p>
-Queries the MPM for a specific value
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>i</td>
-<td>i</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The queried value
-        </p>
-<p> </p>
-</section>
-<section id="apache2.runtime_dir_relative">
-<title>apache2.runtime_dir_relative(
-    request_rec<em> r</em>,  string<em> file</em>
-    )
-    </title>
-<p>
-Returns the path of a file relative to the default runtime directory
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>file</td>
-<td>file</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The path of a file relative to the default runtime directory
-        </p>
-<p> </p>
-</section>
-<section id="apache2.scoreboard_process">
-<title>apache2.scoreboard_process(
-    request_rec<em> r</em>,  number<em> child</em>
-    )
-    </title>
-<p>
-Returns the scoreboard for a server daemon as a table
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>child</td>
-<td>The server child to query</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The scoreboard for a server daemon as a table
-        </p>
-<p> </p>
-</section>
-<section id="apache2.scoreboard_worker">
-<title>apache2.scoreboard_worker(
-    request_rec<em> r</em>,  number<em> child</em>,  number<em> thread</em>
-    )
-    </title>
-<p>
-Returns the scoreboard for a single thread as a table
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>child</td>
-<td>The server child to query</td>
-</tr>
-<tr>
-<td>thread</td>
-<td>The thread to query</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The scoreboard for a single thread as a table
-        </p>
-<p> </p>
-</section>
-<section id="apache2.server_info">
-<title>apache2.server_info(
-    
-    )
-    </title>
-<p>
-Returns a table with information about the server program
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<p>None</p>
-<p>
-<em>Return value(s):</em>
-<br/>
-A table with information about the server program
-        </p>
-<p> </p>
-</section>
-<section id="apache2.state_query">
-<title>apache2.state_query(
-    number<em> field</em>
-    )
-    </title>
-<p>
-Query the server for some state information
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>field</td>
-<td>Which information is requested</td>
-</tr>
-</table>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local gen = apache2.state_query(2)
-r:puts("This is generation no. " .. gen .. " of the top-level parent")
-        </highlight>
-<p> </p>
-</section>
-<section id="apache2.terminate">
-<title>apache2.terminate(
-    
-    )
-    </title>
-<p>
-Kills off a server process. This has no other use than to show how dangerous mod_lua can be ;)
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<p>None</p>
-<p> </p>
-</section>
-</section>
-<section id="Database_connectivity">
-<title>HTTPd bindings: Database connectivity</title>
-<p>
-<a href="#apache2.dbopen">apache2.dbopen</a>
-<br/>
-<a href="#db:query">db:query</a>
-<br/>
-<a href="#db:do">db:do</a>
-<br/>
-<a href="#db:close">db:close</a>
-<br/>
-</p>
-<section id="apache2.dbopen">
-<title>apache2.dbopen(
-    request_rec<em> r</em>,  string<em> dbtype</em>,  string<em> conn_string</em>
-    )
-    </title>
-<p>
-Opens up a new database connection. See the DB functions for mod_pLua for more info on this.
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>dbtype</td>
-<td>dbtype</td>
-</tr>
-<tr>
-<td>conn_string</td>
-<td>connection string</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-The database connection as a table with functions, or nil if the connection failed. If a connection failed, a second argument (string) with the error code is returned.
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local db, error = apache2.dbopen(r, "mod_dbd")
-if error then
-    r:puts("DB error: ", error)
-else
-    -- DB stuff here
-end
-        </highlight>
-<p> </p>
-</section>
-<section id="db:close">
-<title>db:close(
-    request_rec<em> r</em>
-    )
-    </title>
-<p>
-Closes a database connection
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-</table>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local db = apache2.dbopen(r, "mod_dbd") -- open a db connection
-db:close() -- close it down
-        </highlight>
-<p> </p>
-</section>
-<section id="db:do">
-<title>db:do(
-    request_rec<em> r</em>,  string<em> query</em>
-    )
-    </title>
-<p>
-Executes a statement that doesn't return a result set
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>query</td>
-<td>The SQL statement to execute</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-If the statement is valid, a table of results are returned. If an error occurred, the first return value is false and the second return value is a string containing an error message.
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local db = apache2.dbopen(r, "mod_dbd")
-local affected = db:do("DELETE FROM `table` WHERE 1")
-if affected then
-    r:puts("Affected ", affected, " rows")
-end
-        </highlight>
-<p> </p>
-</section>
-<section id="db:query">
-<title>db:query(
-    request_rec<em> r</em>,  string<em> query</em>
-    )
-    </title>
-<p>
-Queries the database for information using the specified statement.
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>r</td>
-<td>The mod_lua request handle</td>
-</tr>
-<tr>
-<td>query</td>
-<td>The SQL statement to execute</td>
-</tr>
-</table>
-<p>
-<em>Return value(s):</em>
-<br/>
-If the statement is valid, a table of results are returned. If an error occurred, the first return value is false and the second return value is a string containing an error message.
-        </p>
-<p>
-<em>Example:</em>
-</p>
-<highlight language="lua">
-local db = apache2.dbopen(r, "mod_dbd")
-local result, error = db:query("SELECT * FROM `table` WHERE 1")
-if result then
-    for key, value in pairs(result)
-        r:puts( ("row %s: %s\n"):format(key, table.concat(value, ", ")) )
-    end
-end
-        </highlight>
-<p> </p>
-</section>
-</section>
-<section id="Miscellaneous">
-<title>HTTPd bindings: Miscellaneous</title>
-<p>
-<a href="#apache2.clock">apache2.clock</a>
-<br/>
-<a href="#apache2.sleep">apache2.sleep</a>
-<br/>
-</p>
-<section id="apache2.clock">
-<title>apache2.clock(
-    
-    )
-    </title>
-<p>
-Returns the current time in microseconds.
-        </p>
-<p>
-<em>Arguments:</em>
+Coming soon!
 </p>
-<p>None</p>
-<p>
-<em>Return value(s):</em>
-<br/>
-The current time in microseconds.
-        </p>
-<p> </p>
+<highlight language="config">
+LuaMapHandler ^/portal/([a-z]+)/   /path/to/lua/script.lua handle_$1
+</highlight>
 </section>
-<section id="apache2.sleep">
-<title>apache2.sleep(
-    number<em> seconds</em>
-    )
-    </title>
-<p>
-Sleeps for a while. Floating point values can be used to sleep for less than a second.
-        </p>
-<p>
-<em>Arguments:</em>
-</p>
-<table border="1">
-<tr>
-<th>Argument</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>seconds</td>
-<td>The number of seconds to sleep.</td>
-</tr>
-</table>
+
+<section id="mod_status_lua"><title>Example 6: Basic Lua scripts</title>
 <p>
-<em>Example:</em>
+Also coming soon
 </p>
-<highlight language="lua">
-r:puts("this is ")
-apache2.flush(r)
-apache2.sleep(0.25) -- sleep for a quarter second.
-r:puts("delayed")
-        </highlight>
-<p> </p>
-</section>
 </section>