updated docs to reflect recent changes.

Author: agentzh

README

@@ -8,9 +8,9 @@ Status
     This module is under active development and is production ready.
 
 Version
-    This document describes ngx_lua v0.8.2
-    (<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 23
-    May 2013.
+    This document describes ngx_lua v0.8.3
+    (<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 20
+    June 2013.
 
 Synopsis
         # set search paths for pure Lua external libraries (';;' is the default path):
@@ -257,6 +257,12 @@ Directives
     to to reload the config file are to send a "HUP" signal or to restart
     Nginx.
 
+    Also, Lua files which are loaded by "dofile" or "loadfile" in
+    *_by_lua_file will never be cached. To ensure code caching, you can
+    either use the init_by_lua or init_by_lua_file directives to load all
+    such files or just make these Lua files true Lua modules and load them
+    via "require".
+
     The ngx_lua module does not currently support the "stat" mode available
     with the Apache "mod_lua" module but this is planned for implementation
     in the future.
@@ -2741,7 +2747,7 @@ Nginx API for Lua
     to the same size value in client_max_body_size.
 
     Note that calling this function instead of using "ngx.var.request_body"
-    or "ngx.var.echo_request-body" is more efficient because it can save one
+    or "ngx.var.echo_request_body" is more efficient because it can save one
     dynamic memory allocation and one data copy.
 
     This function was first introduced in the "v0.3.1rc17" release.
@@ -3036,12 +3042,15 @@ Nginx API for Lua
     call, i.e., "return ngx.redirect(...)", so as to be more explicit.
 
   ngx.send_headers
-    syntax: *ngx.send_headers()*
+    syntax: *ok, err = ngx.send_headers()*
 
     context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
 
     Explicitly send out the response headers.
 
+    Since "v0.8.3" this function returns 1 on success, or returns "nil" and
+    a string describing the error otherwise.
+
     Note that there is normally no need to manually send out response
     headers as ngx_lua will automatically send headers out before content is
     output with ngx.say or ngx.print or when content_by_lua exits normally.
@@ -3057,14 +3066,17 @@ Nginx API for Lua
     This API was first introduced in ngx_lua v0.3.1rc6.
 
   ngx.print
-    syntax: *ngx.print(...)*
+    syntax: *ok, err = ngx.print(...)*
 
     context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
 
     Emits arguments concatenated to the HTTP client (as response body). If
     response headers have not been sent, this function will send headers out
     first and then output body data.
 
+    Since "v0.8.3" this function returns 1 on success, or returns "nil" and
+    a string describing the error otherwise.
+
     Lua "nil" values will output "nil" strings and Lua boolean values will
     output "true" and "false" literal strings respectively.
 
@@ -3098,7 +3110,7 @@ Nginx API for Lua
     the data yourself in Lua and save the calls.
 
   ngx.say
-    syntax: *ngx.say(...)*
+    syntax: *ok, err = ngx.say(...)*
 
     context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
 
@@ -3128,7 +3140,7 @@ Nginx API for Lua
     file in the Nginx source tree.
 
   ngx.flush
-    syntax: *ngx.flush(wait?)*
+    syntax: *ok, err = ngx.flush(wait?)*
 
     context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
 
@@ -3154,6 +3166,9 @@ Nginx API for Lua
     Note that "ngx.flush" is non functional when in the HTTP 1.0 output
     buffering mode. See HTTP 1.0 support.
 
+    Since "v0.8.3" this function returns 1 on success, or returns "nil" and
+    a string describing the error otherwise.
+
   ngx.exit
     syntax: *ngx.exit(status)*
 
@@ -3202,7 +3217,7 @@ Nginx API for Lua
     hint to others reading the code.
 
   ngx.eof
-    syntax: *ngx.eof()*
+    syntax: *ok, err = ngx.eof()*
 
     context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
 
@@ -3235,6 +3250,9 @@ Nginx API for Lua
 
         proxy_ignore_client_abort on;
 
+    Since "v0.8.3" this function returns 1 on success, or returns "nil" and
+    a string describing the error otherwise.
+
   ngx.sleep
     syntax: *ngx.sleep(seconds)*
 
@@ -5854,6 +5872,8 @@ Typical Uses
 Nginx Compatibility
     The latest module is compatible with the following versions of Nginx:
 
+    *   1.4.x (last tested: 1.4.1)
+
     *   1.3.x (last tested: 1.3.11)
 
     *   1.2.x (last tested: 1.2.9)
@@ -5897,9 +5917,9 @@ Installation
 
     Build the source with this module:
 
-        wget 'http://nginx.org/download/nginx-1.2.9.tar.gz'
-        tar -xzvf nginx-1.2.9.tar.gz
-        cd nginx-1.2.9/
+        wget 'http://nginx.org/download/nginx-1.4.1.tar.gz'
+        tar -xzvf nginx-1.4.1.tar.gz
+        cd nginx-1.4.1/
 
         # tell nginx's build system where to find LuaJIT:
         export LUAJIT_LIB=/path/to/luajit/lib

README.markdown

@@ -18,7 +18,7 @@ This module is under active development and is production ready.
 Version
 =======
 
-This document describes ngx_lua [v0.8.2](https://github.com/chaoslawful/lua-nginx-module/tags) released on 23 May 2013.
+This document describes ngx_lua [v0.8.3](https://github.com/chaoslawful/lua-nginx-module/tags) released on 20 June 2013.
 
 Synopsis
 ========
@@ -247,6 +247,10 @@ cached because only the Nginx config file parser can correctly parse the `nginx.
 file and the only ways to to reload the config file
 are to send a `HUP` signal or to restart Nginx.
 
+Also, Lua files which are loaded by `dofile` or `loadfile` 
+in *_by_lua_file will never be cached. To ensure code caching, you can either use the [init_by_lua](http://wiki.nginx.org/HttpLuaModule#init_by_lua) 
+or [init_by_lua_file](http://wiki.nginx.org/HttpLuaModule#init-by_lua_file) directives to load all such files or just make these Lua files true Lua modules and load them via `require`.
+
 The ngx_lua module does not currently support the `stat` mode available with the
 Apache `mod_lua` module but this is planned for implementation in the future.
 
@@ -2559,7 +2563,7 @@ If the request body has been read into disk files, try calling the [ngx.req.get_
 
 To force in-memory request bodies, try setting [client_body_buffer_size](http://wiki.nginx.org/HttpCoreModule#client_body_buffer_size) to the same size value in [client_max_body_size](http://wiki.nginx.org/HttpCoreModule#client_max_body_size).
 
-Note that calling this function instead of using `ngx.var.request_body` or `ngx.var.echo_request-body` is more efficient because it can save one dynamic memory allocation and one data copy.
+Note that calling this function instead of using `ngx.var.request_body` or `ngx.var.echo_request_body` is more efficient because it can save one dynamic memory allocation and one data copy.
 
 This function was first introduced in the `v0.3.1rc17` release.
 
@@ -2819,12 +2823,14 @@ This method call terminates the current request's processing and never returns.
 
 ngx.send_headers
 ----------------
-**syntax:** *ngx.send_headers()*
+**syntax:** *ok, err = ngx.send_headers()*
 
 **context:** *rewrite_by_lua*, access_by_lua*, content_by_lua**
 
 Explicitly send out the response headers.
 
+Since `v0.8.3` this function returns `1` on success, or returns `nil` and a string describing the error otherwise.
+
 Note that there is normally no need to manually send out response headers as ngx_lua will automatically send headers out
 before content is output with [ngx.say](http://wiki.nginx.org/HttpLuaModule#ngx.say) or [ngx.print](http://wiki.nginx.org/HttpLuaModule#ngx.print) or when [content_by_lua](http://wiki.nginx.org/HttpLuaModule#content_by_lua) exits normally.
 
@@ -2840,12 +2846,14 @@ This API was first introduced in ngx_lua v0.3.1rc6.
 
 ngx.print
 ---------
-**syntax:** *ngx.print(...)*
+**syntax:** *ok, err = ngx.print(...)*
 
 **context:** *rewrite_by_lua*, access_by_lua*, content_by_lua**
 
 Emits arguments concatenated to the HTTP client (as response body). If response headers have not been sent, this function will send headers out first and then output body data.
 
+Since `v0.8.3` this function returns `1` on success, or returns `nil` and a string describing the error otherwise.
+
 Lua `nil` values will output `"nil"` strings and Lua boolean values will output `"true"` and `"false"` literal strings respectively.
 
 Nested arrays of strings are permitted and the elements in the arrays will be sent one by one:
@@ -2875,7 +2883,7 @@ Please note that both `ngx.print` and [ngx.say](http://wiki.nginx.org/HttpLuaMod
 
 ngx.say
 -------
-**syntax:** *ngx.say(...)*
+**syntax:** *ok, err = ngx.say(...)*
 
 **context:** *rewrite_by_lua*, access_by_lua*, content_by_lua**
 
@@ -2897,7 +2905,7 @@ There is a hard coded `2048` byte limitation on error message lengths in the Ngi
 
 ngx.flush
 ---------
-**syntax:** *ngx.flush(wait?)*
+**syntax:** *ok, err = ngx.flush(wait?)*
 
 **context:** *rewrite_by_lua*, access_by_lua*, content_by_lua**
 
@@ -2911,6 +2919,8 @@ When `ngx.flush(true)` is called immediately after [ngx.print](http://wiki.nginx
 
 Note that `ngx.flush` is non functional when in the HTTP 1.0 output buffering mode. See [HTTP 1.0 support](http://wiki.nginx.org/HttpLuaModule#HTTP_1.0_support).
 
+Since `v0.8.3` this function returns `1` on success, or returns `nil` and a string describing the error otherwise.
+
 ngx.exit
 --------
 **syntax:** *ngx.exit(status)*
@@ -2959,7 +2969,7 @@ It is recommended, though not necessary, to combine the `return` statement with
 
 ngx.eof
 -------
-**syntax:** *ngx.eof()*
+**syntax:** *ok, err = ngx.eof()*
 
 **context:** *rewrite_by_lua*, access_by_lua*, content_by_lua**
 
@@ -2984,6 +2994,8 @@ But if you create subrequests to access other locations configured by Nginx upst
     proxy_ignore_client_abort on;
 
 
+Since `v0.8.3` this function returns `1` on success, or returns `nil` and a string describing the error otherwise.
+
 ngx.sleep
 ---------
 **syntax:** *ngx.sleep(seconds)*
@@ -5207,6 +5219,7 @@ Nginx Compatibility
 ===================
 The latest module is compatible with the following versions of Nginx:
 
+* 1.4.x (last tested: 1.4.1)
 * 1.3.x (last tested: 1.3.11)
 * 1.2.x (last tested: 1.2.9)
 * 1.1.x (last tested: 1.1.5)
@@ -5234,9 +5247,9 @@ Alternatively, ngx_lua can be manually compiled into Nginx:
 Build the source with this module:
 
 
-    wget 'http://nginx.org/download/nginx-1.2.9.tar.gz'
-    tar -xzvf nginx-1.2.9.tar.gz
-    cd nginx-1.2.9/
+    wget 'http://nginx.org/download/nginx-1.4.1.tar.gz'
+    tar -xzvf nginx-1.4.1.tar.gz
+    cd nginx-1.4.1/
 
     # tell nginx's build system where to find LuaJIT:
     export LUAJIT_LIB=/path/to/luajit/lib

doc/HttpLuaModule.wiki

@@ -10,7 +10,7 @@ This module is under active development and is production ready.
 
 = Version =
 
-This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.8.2] released on 23 May 2013.
+This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.8.3] released on 20 June 2013.
 
 = Synopsis =
 <geshi lang="nginx">
@@ -235,6 +235,11 @@ cached because only the Nginx config file parser can correctly parse the <code>n
 file and the only ways to to reload the config file
 are to send a <code>HUP</code> signal or to restart Nginx.
 
+Also, Lua files which are loaded by <code>dofile</code> or <code>loadfile</code>
+in *_by_lua_file will never be cached. To ensure code caching, you can either use the [[#init_by_lua|init_by_lua]]
+or [[#init-by_lua_file|init_by_lua_file]] directives to load all such files or just make these Lua files true Lua modules
+and load them via <code>require</code>.
+
 The ngx_lua module does not currently support the <code>stat</code> mode available with the
 Apache <code>mod_lua</code> module but this is planned for implementation in the future.
 
@@ -2483,7 +2488,7 @@ If the request body has been read into disk files, try calling the [[#ngx.req.ge
 
 To force in-memory request bodies, try setting [[HttpCoreModule#client_body_buffer_size|client_body_buffer_size]] to the same size value in [[HttpCoreModule#client_max_body_size|client_max_body_size]].
 
-Note that calling this function instead of using <code>ngx.var.request_body</code> or <code>ngx.var.echo_request-body</code> is more efficient because it can save one dynamic memory allocation and one data copy.
+Note that calling this function instead of using <code>ngx.var.request_body</code> or <code>ngx.var.echo_request_body</code> is more efficient because it can save one dynamic memory allocation and one data copy.
 
 This function was first introduced in the <code>v0.3.1rc17</code> release.
 
@@ -2733,12 +2738,14 @@ URI arguments can be specified as well, for example:
 This method call terminates the current request's processing and never returns. It is recommended to combine the <code>return</code> statement with this call, i.e., <code>return ngx.redirect(...)</code>, so as to be more explicit.
 
 == ngx.send_headers ==
-'''syntax:''' ''ngx.send_headers()''
+'''syntax:''' ''ok, err = ngx.send_headers()''
 
 '''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
 
 Explicitly send out the response headers.
 
+Since <code>v0.8.3</code> this function returns <code>1</code> on success, or returns <code>nil</code> and a string describing the error otherwise.
+
 Note that there is normally no need to manually send out response headers as ngx_lua will automatically send headers out
 before content is output with [[#ngx.say|ngx.say]] or [[#ngx.print|ngx.print]] or when [[#content_by_lua|content_by_lua]] exits normally.
 
@@ -2752,12 +2759,14 @@ Returns <code>true</code> if the response headers have been sent (by ngx_lua), a
 This API was first introduced in ngx_lua v0.3.1rc6.
 
 == ngx.print ==
-'''syntax:''' ''ngx.print(...)''
+'''syntax:''' ''ok, err = ngx.print(...)''
 
 '''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
 
 Emits arguments concatenated to the HTTP client (as response body). If response headers have not been sent, this function will send headers out first and then output body data.
 
+Since <code>v0.8.3</code> this function returns <code>1</code> on success, or returns <code>nil</code> and a string describing the error otherwise.
+
 Lua <code>nil</code> values will output <code>"nil"</code> strings and Lua boolean values will output <code>"true"</code> and <code>"false"</code> literal strings respectively.
 
 Nested arrays of strings are permitted and the elements in the arrays will be sent one by one:
@@ -2786,7 +2795,7 @@ This is an asynchronous call and will return immediately without waiting for all
 Please note that both <code>ngx.print</code> and [[#ngx.say|ngx.say]] will always invoke the whole Nginx output body filter chain, which is an expensive operation. So be careful when calling either of these two in a tight loop; buffer the data yourself in Lua and save the calls.
 
 == ngx.say ==
-'''syntax:''' ''ngx.say(...)''
+'''syntax:''' ''ok, err = ngx.say(...)''
 
 '''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
 
@@ -2806,7 +2815,7 @@ The <code>log_level</code> argument can take constants like <code>ngx.ERR</code>
 There is a hard coded <code>2048</code> byte limitation on error message lengths in the Nginx core. This limit includes trailing newlines and leading time stamps. If the message size exceeds this limit, Nginx will truncate the message text accordingly. This limit can be manually modified by editing the <code>NGX_MAX_ERROR_STR</code> macro definition in the <code>src/core/ngx_log.h</code> file in the Nginx source tree.
 
 == ngx.flush ==
-'''syntax:''' ''ngx.flush(wait?)''
+'''syntax:''' ''ok, err = ngx.flush(wait?)''
 
 '''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
 
@@ -2820,6 +2829,8 @@ When <code>ngx.flush(true)</code> is called immediately after [[#ngx.print|ngx.p
 
 Note that <code>ngx.flush</code> is non functional when in the HTTP 1.0 output buffering mode. See [[#HTTP 1.0 support|HTTP 1.0 support]].
 
+Since <code>v0.8.3</code> this function returns <code>1</code> on success, or returns <code>nil</code> and a string describing the error otherwise.
+
 == ngx.exit ==
 '''syntax:''' ''ngx.exit(status)''
 
@@ -2866,7 +2877,7 @@ Note that while this method accepts all [[#HTTP status constants|HTTP status con
 It is recommended, though not necessary, to combine the <code>return</code> statement with this call, i.e., <code>return ngx.exit(...)</code>, to give a visual hint to others reading the code.
 
 == ngx.eof ==
-'''syntax:''' ''ngx.eof()''
+'''syntax:''' ''ok, err = ngx.eof()''
 
 '''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
 
@@ -2891,6 +2902,8 @@ But if you create subrequests to access other locations configured by Nginx upst
     proxy_ignore_client_abort on;
 </geshi>
 
+Since <code>v0.8.3</code> this function returns <code>1</code> on success, or returns <code>nil</code> and a string describing the error otherwise.
+
 == ngx.sleep ==
 '''syntax:''' ''ngx.sleep(seconds)''
 
@@ -5034,6 +5047,7 @@ On a ThinkPad T400 2.80 GHz laptop, the Hello World example readily achieves 28k
 = Nginx Compatibility =
 The latest module is compatible with the following versions of Nginx:
 
+* 1.4.x (last tested: 1.4.1)
 * 1.3.x (last tested: 1.3.11)
 * 1.2.x (last tested: 1.2.9)
 * 1.1.x (last tested: 1.1.5)
@@ -5059,9 +5073,9 @@ Alternatively, ngx_lua can be manually compiled into Nginx:
 Build the source with this module:
 
 <geshi lang="bash">
-    wget 'http://nginx.org/download/nginx-1.2.9.tar.gz'
-    tar -xzvf nginx-1.2.9.tar.gz
-    cd nginx-1.2.9/
+    wget 'http://nginx.org/download/nginx-1.4.1.tar.gz'
+    tar -xzvf nginx-1.4.1.tar.gz
+    cd nginx-1.4.1/
 
     # tell nginx's build system where to find LuaJIT:
     export LUAJIT_LIB=/path/to/luajit/lib