diff options
Diffstat (limited to 'docs/manual/mod/mod_lua.html.en')
| -rw-r--r-- | docs/manual/mod/mod_lua.html.en | 213 |
1 files changed, 117 insertions, 96 deletions
diff --git a/docs/manual/mod/mod_lua.html.en b/docs/manual/mod/mod_lua.html.en index 4069641c..048404d3 100644 --- a/docs/manual/mod/mod_lua.html.en +++ b/docs/manual/mod/mod_lua.html.en @@ -8,11 +8,14 @@ <title>mod_lua - Apache HTTP Server</title> <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> -<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /> +<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" /> +<script src="../style/scripts/prettify.js" type="text/javascript"> +</script> + <link href="../images/favicon.ico" rel="shortcut icon" /></head> <body> <div id="page-header"> -<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p> +<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p> <p class="apache">Apache HTTP Server Version 2.4</p> <img alt="" src="../images/feather.gif" /></div> <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div> @@ -50,7 +53,6 @@ Be sure to check the CHANGES file before upgrading.</div> </div> <div id="quickview"><h3 class="directives">Directives</h3> <ul id="toc"> -<li><img alt="" src="../images/down.gif" /> <a href="#luacodecache">LuaCodeCache</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#luahookaccesschecker">LuaHookAccessChecker</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#luahookauthchecker">LuaHookAuthChecker</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#luahookcheckuserid">LuaHookCheckUserID</a></li> @@ -75,24 +77,26 @@ Be sure to check the CHANGES file before upgrading.</div> <li><img alt="" src="../images/down.gif" /> <a href="#datastructures">Data Structures</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging Functions</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#apache2">apache2 Package</a></li> -</ul></div> +</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="section"> <h2><a name="basicconf" id="basicconf">Basic Configuration</a></h2> <p>The basic module loading directive is</p> -<div class="example"><p><code> +<pre class="prettyprint lang-config"> LoadModule lua_module modules/mod_lua.so -</code></p></div> +</pre> + <p> <code>mod_lua</code> provides a handler named <code>lua-script</code>, which can be used with an <code>AddHandler</code> directive:</p> -<div class="example"><p><code> +<pre class="prettyprint lang-config"> AddHandler lua-script .lua -</code></p></div> +</pre> + <p> This will cause <code>mod_lua</code> to handle requests for files @@ -115,7 +119,9 @@ and <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>. just evaluating a script body CGI style. A handler function looks something like this:</p> -<div class="example"><h3>example.lua</h3><pre> + +<pre class="prettyprint lang-lua"> +<strong>example.lua</strong> -- example handler require "string" @@ -131,17 +137,14 @@ function handle(r) 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) ) + r:puts( string.format("%s: %s\n", k, v) ) end else - r:puts("unknown HTTP method " .. r.method) + r:puts("Unsupported HTTP method " .. r.method) end end -</pre></div> +</pre> + <p> This handler function just prints out the uri or form encoded @@ -159,7 +162,7 @@ handlers (or hooks, or filters) in the same script. <p>Hook functions are how modules (and Lua scripts) participate in the processing of requests. Each type of hook exposed by the server exists for -a specific purposes such as mapping requests to the filesystem, +a specific purpose, such as mapping requests to the filesystem, performing access control, or setting mimetypes. General purpose hooks that simply run at handy times in the request lifecycle exist as well.</p> @@ -169,7 +172,8 @@ they'll return OK, DONE, or DECLINED, which you can write in lua as <code>apache2.OK</code>, <code>apache2.DONE</code>, or <code>apache2.DECLINED</code>, or else an HTTP status code.</p> -<div class="example"><h3>translate_name.lua</h3><pre> +<pre class="prettyprint lang-lua"> +<strong>translate_name.lua</strong> -- example hook that rewrites the URI to a filesystem path. require 'apache2' @@ -182,9 +186,11 @@ function translate_name(r) -- we don't care about this URL, give another module a chance return apache2.DECLINED end -</pre></div> +</pre> -<div class="example"><h3>translate_name2.lua</h3><pre> + +<pre class="prettyprint lang-lua"> +<strong>translate_name2.lua</strong> --[[ example hook that rewrites one URI to another URI. It returns a apache2.DECLINED to give other URL mappers a chance to work on the substitution, including the core translate_name hook which maps based @@ -203,7 +209,8 @@ function translate_name(r) end return apache2.DECLINED end -</pre></div> +</pre> + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="section"> <h2><a name="datastructures" id="datastructures">Data Structures</a></h2> @@ -256,6 +263,16 @@ end <td>string</td> <td>yes</td> </tr> + <tr> + <td><code>context_prefix</code></td> + <td>string</td> + <td>no</td> + </tr> + <tr> + <td><code>context_document_root</code></td> + <td>string</td> + <td>no</td> + </tr> <tr> <td><code>document_root</code></td> @@ -294,6 +311,11 @@ end <td>no</td> </tr> <tr> + <td><code>log_id</code></td> + <td>string</td> + <td>no</td> + </tr> + <tr> <td><code>method</code></td> <td>string</td> <td>no</td> @@ -353,31 +375,34 @@ end <td>string</td> <td>yes</td> </tr> + <tr> + <td><code>useragent_ip</code></td> + <td>string</td> + <td>no</td> + </tr> </table> <p>The request_rec has (at least) the following methods:</p> - <div class="example"><p><code> + <pre class="prettyprint lang-lua"> r:addoutputfilter(name|function) -- add an output filter - </code></p></div> + </pre> - <div class="example"><p><code> - r:parseargs() -- returns a lua table containing the request's - query string arguments - </code></p></div> - <div class="example"><p><code> - r:parsebody() -- parse the request body as a POST and return - a lua table - </code></p></div> + <pre class="prettyprint lang-lua"> + r:parseargs() -- returns a lua table containing the request's query string arguments + </pre> - <div class="example"><p><code> + + <pre class="prettyprint lang-lua"> r:puts("hello", " world", "!") -- print to response body - </code></p></div> + </pre> + - <div class="example"><p><code> + <pre class="prettyprint lang-lua"> r:write("a single string") -- print to response body - </code></p></div> + </pre> + </dd> </dl> @@ -385,18 +410,19 @@ end <div class="section"> <h2><a name="logging" id="logging">Logging Functions</a></h2> -<div class="example"><p><code> +<pre class="prettyprint lang-lua"> -- examples of logging messages<br /> r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br /> r:debug("This is a debug log message")<br /> r:info("This is an info log message")<br /> - r:notice("This is an notice log message")<br /> - r:warn("This is an warn log message")<br /> + r:notice("This is a notice log message")<br /> + r:warn("This is a warn log message")<br /> r:err("This is an err log message")<br /> r:alert("This is an alert log message")<br /> - r:crit("This is an crit log message")<br /> + r:crit("This is a crit log message")<br /> r:emerg("This is an emerg log message")<br /> -</code></p></div> +</pre> + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="section"> @@ -421,36 +447,6 @@ end <p>(Other HTTP status codes are not yet implemented.)</p> </div> <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> -<div class="directive-section"><h2><a name="LuaCodeCache" id="LuaCodeCache">LuaCodeCache</a> <a name="luacodecache" id="luacodecache">Directive</a></h2> -<table class="directive"> -<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the compiled code cache.</td></tr> -<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaCodeCache stat|forever|never</code></td></tr> -<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaCodeCache stat</code></td></tr> -<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> -<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> -<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr> -<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> -</table><p> - 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.</p> - - <p>In general stat or forever is good for production, and stat or never - for development.</p> - - <div class="example"><h3>Examples:</h3><p><code> - LuaCodeCache stat<br /> - LuaCodeCache forever<br /> - LuaCodeCache never<br /> - </code></p></div> - - -</div> -<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="directive-section"><h2><a name="LuaHookAccessChecker" id="LuaHookAccessChecker">LuaHookAccessChecker</a> <a name="luahookaccesschecker" id="luahookaccesschecker">Directive</a></h2> <table class="directive"> <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the access_checker phase of request processing</td></tr> @@ -482,7 +478,7 @@ hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p> a request. This can be used to implement arbitrary authentication and authorization checking. A very simple example: </p> -<div class="example"><pre> +<pre class="prettyprint lang-lua"> require 'apache2' -- fake authcheck hook @@ -513,7 +509,8 @@ function authcheck_hook(r) end return apache2.OK end -</pre></div> +</pre> + <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late" control when this script runs relative to other modules.</p></div> @@ -576,7 +573,7 @@ processing</td></tr> <table class="directive"> <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the translate name phase of request processing</td></tr> <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr> -<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr> <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> @@ -597,10 +594,13 @@ processing</td></tr> <p>Example:</p> -<div class="example"><pre> +<pre class="prettyprint lang-config"> # httpd.conf LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper +</pre> + +<pre class="prettyprint lang-lua"> -- /scripts/conf/hooks.lua -- require "apache2" function silly_mapper(r) @@ -611,7 +611,8 @@ function silly_mapper(r) return apache2.DECLINED end end -</pre></div> +</pre> + <div class="note"><h3>Context</h3><p>This directive is not valid in <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>, <code class="directive"><a href="../mod/core.html#files"><Files></a></code>, or htaccess context.</p></div> @@ -668,17 +669,19 @@ end match groups into both the file path and the function name be careful writing your regular expressions to avoid security issues.</p> - <div class="example"><h3>Examples:</h3><p><code> - LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2 - </code></p></div> + <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config"> + LuaMapHandler /(\w+)/(\w+) /scripts/$1.lua handle_$2 + </pre> +</div> <p>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.</p> -<div class="example"><p><code> +<pre class="prettyprint lang-config"> LuaMapHandler /bingo /scripts/wombat.lua -</code></p></div> +</pre> + <p>This would invoke the "handle" function, which is the default if no specific function name is provided.</p> @@ -713,18 +716,19 @@ end conventions as lua. This just munges the package.path in the lua vms.</p> - <div class="example"><h3>Examples:</h3><p><code> - LuaPackagePath /scripts/lib/?.lua<br /> - LuaPackagePath /scripts/lib/?/init.lua - </code></p></div> + <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config"> +LuaPackagePath /scripts/lib/?.lua +LuaPackagePath /scripts/lib/?/init.lua + </pre> +</div> </div> <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="directive-section"><h2><a name="LuaQuickHandler" id="LuaQuickHandler">LuaQuickHandler</a> <a name="luaquickhandler" id="luaquickhandler">Directive</a></h2> <table class="directive"> <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the quick handler of request processing</td></tr> -<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code /></td></tr> -<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaQuickHandler /path/to/script.lua hook_function_name</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr> <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> @@ -752,8 +756,8 @@ end <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="directive-section"><h2><a name="LuaScope" id="LuaScope">LuaScope</a> <a name="luascope" id="luascope">Directive</a></h2> <table class="directive"> -<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>One of once, request, conn, server -- default is once</td></tr> -<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaScope once|request|conn|server [max|min max]</code></td></tr> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>One of once, request, conn, thread -- default is once</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaScope once|request|conn|thread</code></td></tr> <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaScope once</code></td></tr> <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr> @@ -771,13 +775,9 @@ end request scoped.</dd> <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd> + <dt>thread:</dt> <dd>Use the interpreter for the lifetime of the thread + handling the request (only available with threaded MPMs).</dd> - <dt>server:</dt> <dd>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.</dd> </dl> </div> @@ -785,7 +785,28 @@ end <div class="bottomlang"> <p><span>Available Languages: </span><a href="../en/mod/mod_lua.html" title="English"> en </a> | <a href="../fr/mod/mod_lua.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p> -</div><div id="footer"> +</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> +<script type="text/javascript"><!--//--><![CDATA[//><!-- +var comments_shortname = 'httpd'; +var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_lua.html'; +(function(w, d) { + if (w.location.hostname.toLowerCase() == "httpd.apache.org") { + d.write('<div id="comments_thread"><\/div>'); + var s = d.createElement('script'); + s.type = 'text/javascript'; + s.async = true; + s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; + (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); + } + else { + d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); + } +})(window, document); +//--><!]]></script></div><div id="footer"> <p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> -<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div> +<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- +if (typeof(prettyPrint) !== 'undefined') { + prettyPrint(); +} +//--><!]]></script> </body></html>
\ No newline at end of file |