From: Rich Bowen Date: Tue, 20 Apr 2010 12:52:26 +0000 (+0000) Subject: Adding skeleton documentation for mod_lua, and all of the associated X-Git-Tag: 2.3.6~199 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c0237190bfa92952119e2699490e675efbd87fc8;p=apache Adding skeleton documentation for mod_lua, and all of the associated metafiles pertaining thereto. While this is better than nothing, it's not *much* better than nothing, and is very probably inaccurate. But it's a starting point. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@935894 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/allmodules.xml b/docs/manual/mod/allmodules.xml index 4edbb86bdd..a3b0a196d8 100644 --- a/docs/manual/mod/allmodules.xml +++ b/docs/manual/mod/allmodules.xml @@ -61,6 +61,7 @@ mod_log_config.xml mod_log_forensic.xml mod_logio.xml + mod_lua.xml mod_mime.xml mod_mime_magic.xml mod_negotiation.xml diff --git a/docs/manual/mod/allmodules.xml.de b/docs/manual/mod/allmodules.xml.de index 1dacef747d..9db7980189 100644 --- a/docs/manual/mod/allmodules.xml.de +++ b/docs/manual/mod/allmodules.xml.de @@ -61,6 +61,7 @@ mod_log_config.xml mod_log_forensic.xml mod_logio.xml + mod_lua.xml mod_mime.xml mod_mime_magic.xml mod_negotiation.xml diff --git a/docs/manual/mod/allmodules.xml.es b/docs/manual/mod/allmodules.xml.es index 4edbb86bdd..a3b0a196d8 100644 --- a/docs/manual/mod/allmodules.xml.es +++ b/docs/manual/mod/allmodules.xml.es @@ -61,6 +61,7 @@ mod_log_config.xml mod_log_forensic.xml mod_logio.xml + mod_lua.xml mod_mime.xml mod_mime_magic.xml mod_negotiation.xml diff --git a/docs/manual/mod/allmodules.xml.fr b/docs/manual/mod/allmodules.xml.fr index f33c3b6c49..1f98c859f1 100644 --- a/docs/manual/mod/allmodules.xml.fr +++ b/docs/manual/mod/allmodules.xml.fr @@ -61,6 +61,7 @@ mod_log_config.xml mod_log_forensic.xml mod_logio.xml + mod_lua.xml mod_mime.xml mod_mime_magic.xml mod_negotiation.xml.fr diff --git a/docs/manual/mod/allmodules.xml.ja b/docs/manual/mod/allmodules.xml.ja index fb6c8a63c8..b1078bbbd2 100644 --- a/docs/manual/mod/allmodules.xml.ja +++ b/docs/manual/mod/allmodules.xml.ja @@ -61,6 +61,7 @@ mod_log_config.xml.ja mod_log_forensic.xml.ja mod_logio.xml.ja + mod_lua.xml mod_mime.xml.ja mod_mime_magic.xml mod_negotiation.xml.ja diff --git a/docs/manual/mod/allmodules.xml.ko b/docs/manual/mod/allmodules.xml.ko index b232ee52be..ca78c6fdee 100644 --- a/docs/manual/mod/allmodules.xml.ko +++ b/docs/manual/mod/allmodules.xml.ko @@ -61,6 +61,7 @@ mod_log_config.xml.ko mod_log_forensic.xml mod_logio.xml.ko + mod_lua.xml mod_mime.xml mod_mime_magic.xml mod_negotiation.xml diff --git a/docs/manual/mod/allmodules.xml.tr b/docs/manual/mod/allmodules.xml.tr index bc7872d9c0..23d4a10129 100644 --- a/docs/manual/mod/allmodules.xml.tr +++ b/docs/manual/mod/allmodules.xml.tr @@ -61,6 +61,7 @@ mod_log_config.xml.tr mod_log_forensic.xml.tr mod_logio.xml.tr + mod_lua.xml mod_mime.xml mod_mime_magic.xml mod_negotiation.xml diff --git a/docs/manual/mod/directives.html.en b/docs/manual/mod/directives.html.en index b789a00e64..204be60dd1 100644 --- a/docs/manual/mod/directives.html.en +++ b/docs/manual/mod/directives.html.en @@ -296,6 +296,20 @@
  • <LocationMatch>
  • LogFormat
  • LogLevel
    • +
  • LuaCodeCache
    • +
  • LuaHookAccessChecker
    • +
  • LuaHookAuthChecker
    • +
  • LuaHookAuthChecker
    • +
  • LuaHookCheckUserID
    • +
  • LuaHookInsertFilter
    • +
  • LuaHookMapToStorage
    • +
  • LuaHookTranslateName
    • +
  • LuaHookTypeChecker
    • +
  • LuaMapHandler
    • +
  • LuaPackageCPath
    • +
  • LuaPackagePath
    • +
  • LuaRoot
    • +
  • LuaScope
  • MaxClients
  • MaxKeepAliveRequests
  • MaxMemFree
    • diff --git a/docs/manual/mod/index.html.en b/docs/manual/mod/index.html.en index acd5084b2c..9c2e259dba 100644 --- a/docs/manual/mod/index.html.en +++ b/docs/manual/mod/index.html.en @@ -145,6 +145,7 @@ by other LDAP modules
    mod_log_config
    Logging of the requests made to the server
    mod_log_forensic
    Forensic Logging of the requests made to the server
    mod_logio
    Logging of input and output bytes per request
    +
    mod_lua
    Provides Lua hooks to doo cool stuff
    mod_mime
    Associates the requested filename's extensions with the file's behavior (handlers and filters) and content (mime-type, language, character set and diff --git a/docs/manual/mod/mod_lua.html b/docs/manual/mod/mod_lua.html new file mode 100644 index 0000000000..6628ddd47b --- /dev/null +++ b/docs/manual/mod/mod_lua.html @@ -0,0 +1,5 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: mod_lua.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 diff --git a/docs/manual/mod/mod_lua.html.en b/docs/manual/mod/mod_lua.html.en new file mode 100644 index 0000000000..a04d804fc8 --- /dev/null +++ b/docs/manual/mod/mod_lua.html.en @@ -0,0 +1,344 @@ + + + +mod_lua - Apache HTTP Server + + + + + +
    +

    Modules | Directives | FAQ | Glossary | Sitemap

    +

    Apache HTTP Server Version 2.3

    +
    +
    <-
    + +
    +

    Apache Module mod_lua

    +
    +

    Available Languages:

    +
    + + + + +
    Description:Provides Lua hooks to doo cool stuff
    Status:Experimental
    Module Identifier:lua_module
    Source File:mod_lua.c
    Compatibility:2.4 and later
    +

    Summary

    + +

    Someone needs to write this.

    + +

    Example

    +# Examples are always helpful.
    +

    + +
    + +
    top
    +
    +

    Additional Documentation

    + +

    More detailed information about the module in general (as opposed to +the individual directives) can follow in sections containing titles.

    + +

    The id attribute will be translated into a hypertext +anchor target.

    + +

    References to directives should use the directive tag: TemplateDirective. References to +modules should use the module tag +mod_lua.xml.

    + +
    +
    top
    +

    Directive

    + + + + + + +
    Description:
    Syntax:LuaHookFixups /path/to/lua/script.lua hook_function_name
    Context:
    Status:Experimental
    Module:mod_lua
    +
    +
    top
    +

    LuaCodeCache Directive

    + + + + + + +
    Description:
    Syntax:LuaCodeCache stat|forever|never
    Context:
    Status:Experimental
    Module:mod_lua

    + Specify the behavior of the in-memory code cache. The default + is stat, which stats the top level script (not any included + ones) each time that file is needed, and reloads it if the + modified time indicates it is newer than the one it has + already loaded. The other values cause it to keep the file + 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 + for deveopment. + + Examples: + LuaCodeCache stat + LuaCodeCache forever + LuaCodeCache never +

    +
    +
    top
    +

    LuaHookAccessChecker Directive

    + + + + + + +
    Description:
    Syntax:LuaHookAccessChecker /path/to/lua/script.lua hook_function_name
    Context:
    Status:Experimental
    Module:mod_lua

    ...

    +
    +
    top
    +

    LuaHookAuthChecker Directive

    + + + + + + +
    Description:
    Syntax:LuaHookAuthChecker /path/to/lua/script.lua hook_function_name
    Context:
    Status:Experimental
    Module:mod_lua

    ...

    +
    +
    top
    +

    LuaHookAuthChecker Directive

    + + + + + + +
    Description:
    Syntax:LuaHookAuthChecker /path/to/lua/script.lua hook_function_name
    Context:
    Status:Experimental
    Module:mod_lua

    ...

    +
    +
    top
    +

    LuaHookCheckUserID Directive

    + + + + + + +
    Description:
    Syntax:LuaHookCheckUserID /path/to/lua/script.lua hook_function_name
    Context:
    Status:Experimental
    Module:mod_lua

    ...

    +
    +
    top
    +

    LuaHookInsertFilter Directive

    + + + + + + +
    Description:
    Syntax:LuaHookInsertFilter /path/to/lua/script.lua hook_function_name
    Context:
    Status:Experimental
    Module:mod_lua

    Not Yet Implemented

    +
    +
    top
    +

    LuaHookMapToStorage Directive

    + + + + + + +
    Description:
    Syntax:LuaHookMapToStorage /path/to/lua/script.lua hook_function_name
    Context:
    Status:Experimental
    Module:mod_lua

    ...

    +
    +
    top
    +

    LuaHookTranslateName Directive

    + + + + + + +
    Description:
    Syntax:LuaHookTranslateName /path/to/lua/script.lua hook_function_name
    Context:
    Status:Experimental
    Module:mod_lua

    + Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of + request processing. The hook function receives a single + argument, the request_rec, and should return a status code, + which is either an HTTP error code, or the constants defined + in the apache2 module: apache2.OK, apache2.DECLINED, or + apache2.DONE.

    + +

    For those new to hooks, basically each hook will be invoked + until one of them returns apache2.OK. If your hook doesn't + want to do the translation it should just return + apache2.DECLINED. If the request should stop processing, then + return apache2.DONE.

    + +

    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
    +

    + +
    +
    top
    +

    LuaHookTypeChecker Directive

    + + + + + + +
    Description:
    Syntax:LuaHookTypeChecker /path/to/lua/script.lua hook_function_name
    Context:
    Status:Experimental
    Module:mod_lua

    ...

    +
    +
    top
    +

    LuaMapHandler Directive

    + + + + + + +
    Description:
    Syntax:LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]
    Context:
    Status:Experimental
    Module:mod_lua
    +

    This directive matches a uri pattern to invoke a specific + handler function in a specific file. It uses PCRE regular + expressions to match the uri, and supports interpolating + match groups into both the file path and the function name + be careful writing your regular expressions to avoid security + issues.

    +

    + Examples: +

    +

    + LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2 +

    +

    This would match uri's such as /photos/show?id=9 + to the file /scripts/photos.lua and invoke the + handler function handle_show on the lua vm after + loading that file.

    + +

    + LuaMapHandler /bingo /scripts/wombat.lua +

    +

    This would invoke the "handle" function, which + is the default if no specific function name is + provided.

    + +
    +
    top
    +

    LuaPackageCPath Directive

    + + + + + + +
    Description:
    Syntax:LuaPackageCPath /path/to/include/?.soa
    Context:
    Status:Experimental
    Module:mod_lua
    +

    Add a path to lua's shared library search path. Follows the same + conventions as lua. This just munges the package.cpath in the + lua vms. + + Examples: + LuaPackagePath /scripts/lib/?.so +

    +
    +
    top
    +

    LuaPackagePath Directive

    + + + + + + +
    Description:
    Syntax:LuaPackagePath /path/to/include/?.lua
    Context:
    Status:Experimental
    Module:mod_lua

    Add a path to lua's module search path. Follows the same + conventions as lua. This just munges the package.path in the + lua vms. + + Examples: + LuaPackagePath /scripts/lib/?.lua + LuaPackagePath /scripts/lib/?/init.lua +

    +
    +
    top
    +

    LuaRoot Directive

    + + + + + + +
    Description:Specify the base path
    Syntax:LuaRoot /path/to/a/directory
    Context:
    Status:Experimental
    Module:mod_lua
    +

    Specify the base path which will be used to evaluate all + relative paths within mod_wombat. If not specified they + will be resolved relative to the current working directory, + which may not always work well for a server.

    + +
    +
    top
    +

    LuaScope Directive

    + + + + + + +
    Description:
    Syntax:LuaScope once|request|conn|server [max|min max]
    Context:
    Status:Experimental
    Module:mod_lua
    +

    Specify the lifecycle scope of the Lua interpreter which will + be used by handlers in this "Directory." The default is "once" + + once: use the interpreter once and throw it away. + + request: use the interpreter to handle anything based on + the same file within this request, which is also + request scoped. + + conn: Same as request but attached to the connection_rec + + server: This one is different than others because the + server scope is quite long lived, and multiple threads + will have the same server_rec. To accommodate this + server scoped interpreter are stored in an apr + resource list. The min and max arguments are intended + to specify the pool size, but are unused at this time. +

    +
    +
    +
    +

    Available Languages:

    +
    + \ No newline at end of file diff --git a/docs/manual/mod/mod_lua.xml b/docs/manual/mod/mod_lua.xml new file mode 100644 index 0000000000..c65041d42f --- /dev/null +++ b/docs/manual/mod/mod_lua.xml @@ -0,0 +1,249 @@ + + + + + + +mod_lua + +Provides Lua hooks to doo cool stuff +experimental +mod_lua.c +lua_module +2.4 and later + + +

    Someone needs to write this.

    + +Example +# Examples are always helpful.
    +     + +     + + +Useful document +Useful +mod_useful + + +
    Additional Documentation + +

    More detailed information about the module in general (as opposed to +the individual directives) can follow in sections containing titles.

    + +

    The id attribute will be translated into a hypertext +anchor target.

    + +

    References to directives should use the directive tag: TemplateDirective. References to +modules should use the module tag +mod_lua.xml.

    + +
    + + +LuaRoot +Specify the base path +LuaRoot /path/to/a/directory + + +

    Specify the base path which will be used to evaluate all + relative paths within mod_wombat. If not specified they + will be resolved relative to the current working directory, + which may not always work well for a server.

    +     +     + + +LuaScope +LuaScope once|request|conn|server [max|min max] + + +

    Specify the lifecycle scope of the Lua interpreter which will + be used by handlers in this "Directory." The default is "once" + + once: use the interpreter once and throw it away. + + request: use the interpreter to handle anything based on + the same file within this request, which is also + request scoped. + + conn: Same as request but attached to the connection_rec + + server: This one is different than others because the + server scope is quite long lived, and multiple threads + will have the same server_rec. To accommodate this + server scoped interpreter are stored in an apr + resource list. The min and max arguments are intended + to specify the pool size, but are unused at this time. +

     +     + + + +LuaMapHandler +LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name] + +

    This directive matches a uri pattern to invoke a specific + handler function in a specific file. It uses PCRE regular + expressions to match the uri, and supports interpolating + match groups into both the file path and the function name + be careful writing your regular expressions to avoid security + issues.

    +

    + Examples: +

    + + LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2 + +

    This would match uri's such as /photos/show?id=9 + to the file /scripts/photos.lua and invoke the + handler function handle_show on the lua vm after + loading that file.

    + + + LuaMapHandler /bingo /scripts/wombat.lua + +

    This would invoke the "handle" function, which + is the default if no specific function name is + provided.

    +     +     + + +LuaPackagePath +LuaPackagePath /path/to/include/?.lua +

    Add a path to lua's module search path. Follows the same + conventions as lua. This just munges the package.path in the + lua vms. + + Examples: + LuaPackagePath /scripts/lib/?.lua + LuaPackagePath /scripts/lib/?/init.lua +

     +     + + +LuaPackageCPath +LuaPackageCPath /path/to/include/?.soa + + +

    Add a path to lua's shared library search path. Follows the same + conventions as lua. This just munges the package.cpath in the + lua vms. + + Examples: + LuaPackagePath /scripts/lib/?.so +

     +     + + +LuaCodeCache +LuaCodeCache stat|forever|never + +

    + Specify the behavior of the in-memory code cache. The default + is stat, which stats the top level script (not any included + ones) each time that file is needed, and reloads it if the + modified time indicates it is newer than the one it has + already loaded. The other values cause it to keep the file + 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 + for deveopment. + + Examples: + LuaCodeCache stat + LuaCodeCache forever + LuaCodeCache never +

     +     + + +LuaHookTranslateName +LuaHookTranslateName /path/to/lua/script.lua hook_function_name + +

    + Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of + request processing. The hook function receives a single + argument, the request_rec, and should return a status code, + which is either an HTTP error code, or the constants defined + in the apache2 module: apache2.OK, apache2.DECLINED, or + apache2.DONE.

    + +

    For those new to hooks, basically each hook will be invoked + until one of them returns apache2.OK. If your hook doesn't + want to do the translation it should just return + apache2.DECLINED. If the request should stop processing, then + return apache2.DONE.

    + +

    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
    +     +     +     + + +LuaHookFixups /path/to/lua/script.lua hook_function_name + Just like LuaHookTranslateName, but executed at the fixups phase + + + + +LuaHookMapToStorage +LuaHookMapToStorage /path/to/lua/script.lua hook_function_name +

    ...

     +     + + +LuaHookCheckUserID +LuaHookCheckUserID /path/to/lua/script.lua hook_function_name +

    ...

     +     + + +LuaHookTypeChecker +LuaHookTypeChecker /path/to/lua/script.lua hook_function_name +

    ...

     +     + + +LuaHookAuthChecker +LuaHookAuthChecker /path/to/lua/script.lua hook_function_name +

    ...

     +     + + +LuaHookAccessChecker +LuaHookAccessChecker /path/to/lua/script.lua hook_function_name +

    ...

     +     + + +LuaHookAuthChecker +LuaHookAuthChecker /path/to/lua/script.lua hook_function_name +

    ...

     +     + + +LuaHookInsertFilter +LuaHookInsertFilter /path/to/lua/script.lua hook_function_name +

    Not Yet Implemented

     +     + +     + diff --git a/docs/manual/mod/mod_lua.xml.meta b/docs/manual/mod/mod_lua.xml.meta new file mode 100644 index 0000000000..e9e62babed --- /dev/null +++ b/docs/manual/mod/mod_lua.xml.meta @@ -0,0 +1,12 @@ + + + + + mod_lua + /mod/ + .. + + + en + + diff --git a/docs/manual/mod/quickreference.html.en b/docs/manual/mod/quickreference.html.en index 624840ba73..470579ef80 100644 --- a/docs/manual/mod/quickreference.html.en +++ b/docs/manual/mod/quickreference.html.en @@ -493,6 +493,20 @@ matching URLs LogFormat format|nickname [nickname] "%h %l %u %t \"%r\" +svBDescribes a format for use in a log file LogLevel level warn svCControls the verbosity of the ErrorLog +LuaCodeCache stat|forever|neverX- +LuaHookAccessChecker /path/to/lua/script.lua hook_function_nameX- +LuaHookAuthChecker /path/to/lua/script.lua hook_function_nameX- +LuaHookAuthChecker /path/to/lua/script.lua hook_function_nameX- +LuaHookCheckUserID /path/to/lua/script.lua hook_function_nameX- +LuaHookInsertFilter /path/to/lua/script.lua hook_function_nameX- +LuaHookMapToStorage /path/to/lua/script.lua hook_function_nameX- +LuaHookTranslateName /path/to/lua/script.lua hook_function_nameX- +LuaHookTypeChecker /path/to/lua/script.lua hook_function_nameX- +LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]X- +LuaPackageCPath /path/to/include/?.soaX- +LuaPackagePath /path/to/include/?.luaX- +LuaRoot /path/to/a/directoryXSpecify the base path +LuaScope once|request|conn|server [max|min max]X- MaxClients numbersMMaximum number of connections that will be processed simultaneously MaxKeepAliveRequests number 100 svCNumber of requests allowed on a persistent