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. - + @@ -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
notes tablenoyes
path_info