Added Lua section to the user manual

a58bb71c · Sergey Lyubka · fc9a9593 · a58bb71c · a58bb71c
Commit a58bb71c authored 12 years ago by Sergey Lyubka
--- a/UserManual.md
+++ b/UserManual.md
@@ -279,6 +279,50 @@ must be for a file name only, not including directory name. Example:
    mongoose -hide_files_patterns secret.txt|even_more_secret.txt
+# Lua Server Pages
+Pre-built Windows and Mac mongoose binaries have built-in Lua Server Pages
+support. That means it is possible to write PHP-like scripts with mongoose,
+using Lua programming language instead of PHP. Lua is known
+for it's speed and small size. Mongoose uses Lua version 5.2.1, the
+documentation for it can be found at
+[Lua 5.2 reference manual](http://www.lua.org/manual/5.2/).
+To create a Lua Page, make sure a file has `.lp` extension. For example,
+let's say it is going to be `my_page.lp`. The contents of the file, just like
+with PHP, is HTML with embedded Lua code. Lua code must be enclosed in
+`<?  ?>` blocks, and can appear anywhere on the page. For example, to
+print current weekday name, one can write:
+    <p>
+      <span>Today is:</span>
+      <? print(os.date("%A")) ?>
+    </p>
+Note that this example uses function `print()`, which prints data to the
+web page. Using function `print()` is the way to generate web content from
+inside Lua code. In addition to `print()`, all standard library functions
+are accessible from the Lua code (please check reference manual for details),
+and also information about the request is available in `request_info` object,
+like request method, all headers, etcetera. Please refer to
+`struct mg_request_info` definition in
+[mongoose.h](https://github.com/valenok/mongoose/blob/master/mongoose.h)
+to see what kind of information is present in `request_info` object. Also,
+[page.lp](https://github.com/valenok/mongoose/blob/master/test/page.lp)
+contains some example code that uses `request_info`.
+One substantial difference of mongoose's Lua Pages and PHP is that Mongoose
+expects Lua page to output HTTP headers. Therefore, **at the very beginning of
+every Lua Page must be a Lua block that outputs HTTP headers**, like this:
+    <? print('HTTP/1.0 200 OK\r\nContent-Type: text/html\r\n\r\n') ?>
+    <html><body>
+      ... the rest of the web page ...
+It is easy to do things like redirects, for example:
+    <? print('HTTP/1.0 302 Found\r\nLocation: http://google.com\r\n\r\n') ?>
 # Common Problems
 - PHP doesn't work - getting empty page, or 'File not found' error. The
  reason for that is wrong paths to the interpreter. Remember that with PHP,

--- a/test/page.lp
+++ b/test/page.lp
@@ -2,6 +2,7 @@
  -- Lua server pages have full control over the output, including HTTP
  -- headers they send to the client. Send HTTP headers:
  print('HTTP/1.0 200 OK\r\nContent-Type: text/html\r\n\r\n')
 ?><html><body>
 <p>This is an example Lua server page served by
@@ -10,6 +11,14 @@ Mongoose has Lua, Sqlite, and other functionality built in the binary.
 This example page stores the request in the Sqlite database, and shows
 all requests done previously.</p>
+  <p> Today is <? print(os.date("%A")) ?>
+  <p> HTTP headers: <br>
+   <?
+     for name, value in pairs(request_info.http_headers) do
+       print(name, ' : ', value, '<br>')
+     end
+   ?>
 <pre>
 <?
  -- Open database