From b02e58516b855aab083ca50b7d18a0469fcacfe5 Mon Sep 17 00:00:00 2001
From: Daniel Earl Poirier
Date: Sun, 2 May 2010 15:11:03 +0000
Subject: [PATCH] Some more updates to the mod_lua doc: - link to the Lua web
site - Lua modules are properly refered to as 'packages' - intro to writing
hooks in Lua - remove unnecessary indentation from examples
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@940246 13f79535-47bb-0310-9956-ffa450edef68
---
docs/manual/mod/mod_lua.xml | 116 ++++++++++++++++++++++++------------
1 file changed, 77 insertions(+), 39 deletions(-)
diff --git a/docs/manual/mod/mod_lua.xml b/docs/manual/mod/mod_lua.xml
index ebeadf2061..976309dc39 100644
--- a/docs/manual/mod/mod_lua.xml
+++ b/docs/manual/mod/mod_lua.xml
@@ -32,7 +32,9 @@ request processing
2.3 and later
-Someone needs to write this.
+Someone needs to write this.
+Include a link to the Lua website.
+
@@ -57,6 +59,10 @@ This will cause mod_lua
to handle requests for files
ending in .lua
by invoking that file's
handle
function.
+
+For more flexibility, see LuaMapHandler.
+
+
Writing Handlers
@@ -66,24 +72,26 @@ just evaluating a script body CGI style. A handler function looks
something like this:
example.lua
- require "string"
-
- function handle_something(r)
- r.content_type = "text/plain"
- r:puts("Hello Lua World!\n")
-
- if r.method == 'GET' then
- for k, v in pairs( r:parseargs() ) do
- r:puts( string.format("%s: %s", k, v) )
- end
- elseif r.method == 'POST' then
- for k, v in pairs( r:parsebody() ) do
- r:puts( string.format("%s: %s", k, v) )
- end
- else
- r:puts("unknown HTTP method " .. r.method)
- end
- end
+-- example handler
+
+require "string"
+
+function handle_something(r)
+ r.content_type = "text/plain"
+ r:puts("Hello Lua World!\n")
+
+ if r.method == 'GET' then
+ for k, v in pairs( r:parseargs() ) do
+ r:puts( string.format("%s: %s", k, v) )
+ end
+ elseif r.method == 'POST' then
+ for k, v in pairs( r:parsebody() ) do
+ r:puts( string.format("%s: %s", k, v) )
+ end
+ else
+ r:puts("unknown HTTP method " .. r.method)
+ end
+end
@@ -98,6 +106,29 @@ handlers (or hooks, or filters) in the same script.
+Writing Hooks
+
+Hook functions are passed the request object as their only argument.
+They can return any value, depending on the hook, but most commonly
+they'll return OK, DONE, or DECLINED, which you can write in lua as
+apache2.OK
, apache2.DONE
, or
+apache2.DECLINED
, or else an HTTP status code.
+
+translate_name.lua
+-- example hook
+
+require 'apache2'
+
+function translate_name(r)
+ if r.uri == "/translate-name" then
+ r.uri = "/find_me.txt"
+ return apache2.DECLINED
+ end
+ return apache2.DECLINED
+end
+
+
+
Data Structures
@@ -107,8 +138,8 @@ handlers (or hooks, or filters) in the same script.
which lets you do useful things with it. For the most part it
has the same fields as the request_rec struct (see httpd.h
until we get better docs here) many of which are writeable as
- well as readable. (Tables' content can be changed, but the
- field itself cannot be set to a different table.)
+ well as readable. (The table fields' content can be changed, but the
+ fields themselves cannot be set to different tables.)
@@ -187,7 +218,7 @@ handlers (or hooks, or filters) in the same script.
notes |
table |
- no |
+ yes |
path_info |
@@ -262,6 +293,7 @@ handlers (or hooks, or filters) in the same script.
Logging Functions
+ -- examples of logging messages
r:debug("This is a debug log message")
r:info("This is an info log message")
r:notice("This is an notice log message")
@@ -274,8 +306,8 @@ handlers (or hooks, or filters) in the same script.
-apache2 Module
-A module named apache2
is available with (at least) the following contents.
+apache2 Package
+A package named apache2
is available with (at least) the following contents.
- apache2.OK
- internal constant OK. Handlers should return this if they've
@@ -290,6 +322,7 @@ handlers (or hooks, or filters) in the same script.
- apache2.HTTP_MOVED_TEMPORARILY
- HTTP status code
+(Other HTTP status codes are not yet implemented.)
@@ -429,7 +462,7 @@ handlers (or hooks, or filters) in the same script.
cached forever (don't stat and replace) or to never cache the
file.
- In general stat or forever is good production and stat or never
+
In general stat or forever is good for production, and stat or never
for deveopment.
Examples:
@@ -466,19 +499,21 @@ handlers (or hooks, or filters) in the same script.
Example:
-
- LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
-
- -- /scripts/conf/hooks.lua --
- function silly_mapper(r)
- if r.uri == "/" then
- r.file = "/var/www/home.lua"
- return apache2.OK
- else
- return apache2.DECLINED
- end
- end
-
+
+# httpd.conf
+LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
+
+-- /scripts/conf/hooks.lua --
+require "apache2"
+function silly_mapper(r)
+ if r.uri == "/" then
+ r.file = "/var/www/home.lua"
+ return apache2.OK
+ else
+ return apache2.DECLINED
+ end
+end
+
@@ -550,7 +585,10 @@ processing
directory.htaccess
All
- ...
+
+Add your hook to the access_checker phase. An access checker
+hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.
+
--
2.40.0