From: Daniel Gruno Date: Tue, 9 Apr 2013 09:29:47 +0000 (+0000) Subject: Updating lua docs with examples of how to use the built-in functions X-Git-Tag: 2.5.0-alpha~5609 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=01f4c82b21f016d4b45969e870fd23706e478fe8;p=apache Updating lua docs with examples of how to use the built-in functions git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1465942 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_lua.xml b/docs/manual/mod/mod_lua.xml index c0e2f11acf..a0da00734d 100644 --- a/docs/manual/mod/mod_lua.xml +++ b/docs/manual/mod/mod_lua.xml @@ -616,194 +616,277 @@ end
Built in functions -

The request_rec object has (at least) the following methods:

+

The request_rec object has (at least) the following methods:

- - r:flush() -- flushes the output buffer - + +r:flush() -- flushes the output buffer: - - r:addoutputfilter(name|function) -- add an output filter - +while we_have_stuff_to_send do + r:puts("Bla bla bla\n") -- print something to client + r:flush() -- flush the buffer (send to client) + r:sleep(0.5) -- fake processing time and repeat +end + - - r:sendfile(filename) -- sends an entire file to the client, using sendfile if supported by the current platform - + +r:addoutputfilter(name|function) -- add an output filter: - - r:parseargs() -- returns a Lua table containing the request's query string arguments - +r:addoutputfilter("fooFilter") -- add the fooFilter to the output stream + - - r:parsebody([sizeLimit]) -- parse the request body as a POST and return a lua table. - -- An optional number may be passed to specify the maximum number - -- of bytes to parse. Default is 8192 bytes. - + +r:sendfile(filename) -- sends an entire file to the client, using sendfile if supported by the current platform: - - r:puts("hello", " world", "!") -- print to response body - +if use_sendfile_thing then + r:sendfile("/var/www/large_file.img") +end + - - r:write("a single string") -- print to response body - + +r:parseargs() -- returns a Lua table containing the request's query string arguments: + +local GET = r:parseargs() +r:puts("Your name is: " .. GET['name'] or "Unknown") + - - r:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result - + +r:parsebody([sizeLimit]) -- parse the request body as a POST and return a lua table. + -- An optional number may be passed to specify the maximum number + -- of bytes to parse. Default is 8192 bytes: + +local POST = r:parsebody(1024*1024) +r:puts("Your name is: " .. POST['name'] or "Unknown") + + + +r:puts("hello", " world", "!") -- print to response body, self explanatory + - - r:base64_encode(string) -- Encodes a string using the Base64 encoding standard - + +r:write("a single string") -- print to response body, self explanatory + - - r:base64_decode(string) -- Decodes a Base64-encoded string - + +r:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result + - - r:md5(string) -- Calculates and returns the MD5 digest of a string (binary safe) - + +r:base64_encode(string) -- Encodes a string using the Base64 encoding standard: - - r:sha1(string) -- Calculates and returns the SHA1 digest of a string (binary safe) - +local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q= + - - r:escape(string) -- URL-Escapes a string - + +r:base64_decode(string) -- Decodes a Base64-encoded string: - - r:unescape(string) -- Unescapes an URL-escaped string - +local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test' + - - r:banner() -- Returns the current server banner - + +r:md5(string) -- Calculates and returns the MD5 digest of a string (binary safe): - - r:port() -- Returns the current server port used for the request - +local hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339 + - - r:mpm_query(number) -- Queries the server for MPM information using ap_mpm_query - + +r:sha1(string) -- Calculates and returns the SHA1 digest of a string (binary safe): - - r:expr(string) -- Evaluates an expr string. - +local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19 + - - r:scoreboard_process(a) -- Queries the server for information about the process at position a - + +r:escape(string) -- URL-Escapes a string: - - r:scoreboard_worker(a, b) -- Queries for information about the worker thread, b, in process a - +local url = "http://foo.bar/1 2 3 & 4 + 5" +local escaped = r:escape(url) -- returns 'http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5' + - - r:started() -- Returns the time of the last server (re)start - + +r:unescape(string) -- Unescapes an URL-escaped string: + +local url = "http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5" +local unescaped = r:escape(url) -- returns 'http://foo.bar/1 2 3 & 4 + 5' + + + +r:banner() -- Returns the current server banner, self explanatory + + + +r:port() -- Returns the current server port used for the request, self explanatory + + + +r:mpm_query(number) -- Queries the server for MPM information using ap_mpm_query: + +local mpm = r.mpm_query(14) +if mpm == 1 then + r:puts("This server uses the Event MPM") +end + + + +r:expr(string) -- Evaluates an expr string. + +if r:expr("%{HTTP_HOST} =~ /^www/") then + r:puts("This host name starts with www") +end + + + +r:scoreboard_process(a) -- Queries the server for information about the process at position a: + +local process = r:scoreboard_process(1) +r:puts("Server 1 has PID " .. process.pid) + + + +r:scoreboard_worker(a, b) -- Queries for information about the worker thread, b, in process a: + +local thread = r:scoreboard_worker(1, 1) +r:puts("Server 1's thread 1 has thread ID " .. thread.tid .. " and is in " .. thread.status .. " status") + + + +r:started() -- Returns the time of the last server (re)start + - - r:clock() -- Returns the current time with microsecond precision - + +r:clock() -- Returns the current time with microsecond precision + - + r:requestbody(filename) -- Reads and returns the request body of a request. - -- If 'filename' is specified, it instead saves the - -- contents to that file. - + -- If 'filename' is specified, it instead saves the + -- contents to that file: + +local input = r:requestbody() +r:puts("You sent the following request body to me:\n") +r:puts(input) + - - r:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter - + +r:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter + - - r:module_info(module_name) -- Queries the server for information about a module - + +r.module_info(module_name) -- Queries the server for information about a module - - r:loaded_modules() -- Returns a list of modules loaded by httpd - +local mod = r.module_info("mod_lua.c") +if mod then + for k, v in pairs(mod.commands) do + r:puts( ("%s: %s\n"):format(k,v)) -- print out all directives accepted by this module + end +end + + + +r:loaded_modules() -- Returns a list of modules loaded by httpd: + +for k, module in pairs(r:loaded_modules()) do + r:puts("I have loaded module " .. module .. "\n") +end + - + r:runtime_dir_relative(filename) -- Compute the name of a run-time file (e.g., shared memory "file") - -- relative to the appropriate run-time directory. - + -- relative to the appropriate run-time directory. + - - r:server_info() -- Returns a table containing server information, such as - -- the name of the httpd executable file, mpm used etc. - + +r:server_info() -- Returns a table containing server information, such as + -- the name of the httpd executable file, mpm used etc. + - - r:set_document_root(file_path) -- Sets the document root for the request to file_path - + +r:set_document_root(file_path) -- Sets the document root for the request to file_path + - - r:add_version_component(component_string) -- Adds a component to the server banner. - + +r:add_version_component(component_string) -- Adds a component to the server banner. + - - r:set_context_info(prefix, docroot) -- Sets the context prefix and context document root for a request - + +r:set_context_info(prefix, docroot) -- Sets the context prefix and context document root for a request + - - r:os_escape_path(file_path) -- Converts an OS path to a URL in an OS dependant way - + +r:os_escape_path(file_path) -- Converts an OS path to a URL in an OS dependant way + - - r:escape_logitem(string) -- Escapes a string for logging - + +r:escape_logitem(string) -- Escapes a string for logging + - -r:strcmp_match(string, pattern) -- Checks if 'string' matches 'pattern' using strcmp_match (GLOBs). - -- fx. whether 'www.example.com' matches '*.example.com' - + +r:strcmp_match(string, pattern) -- Checks if 'string' matches 'pattern' using strcmp_match (globs). + -- fx. whether 'www.example.com' matches '*.example.com': + +local match = r:strcmp_match("foobar.com", "foo*.com") +if match then + r:puts("foobar.com matches foo*.com") +end + - - r:set_keepalive() -- Sets the keepalive status for a request. Returns true if possible, false otherwise. - + +r:set_keepalive() -- Sets the keepalive status for a request. Returns true if possible, false otherwise. + - - r:make_etag() -- Constructs and returns the etag for the current request. - + +r:make_etag() -- Constructs and returns the etag for the current request. + - + r:send_interim_response(clear) -- Sends an interim (1xx) response to the client. - -- if 'clear' is true, available headers will be sent and cleared. - + -- if 'clear' is true, available headers will be sent and cleared. + - + r:custom_response(status_code, string) -- Construct and set a custom response for a given status code. - -- This works much like the ErrorDocument directive. - + -- This works much like the ErrorDocument directive: + +r:custom_response(404, "Baleted!") + - - r:exists_config_define(string) -- Checks whether a configuration definition exists or not. - + +r:exists_config_define(string) -- Checks whether a configuration definition exists or not: - - r:state_query(string) -- Queries the server for state information - +if r:exists_config_define("FOO") then + r:puts("httpd was probably run with -DFOO, or it was defined in the configuration") +end + - - r:stat(filename) -- Runs stat() on a file, and returns a table with file information - + +r:state_query(string) -- Queries the server for state information + + + +r:stat(filename) -- Runs stat() on a file, and returns a table with file information: + +local info = r:stat("/var/www/foo.txt") +if info then + r:puts("This file exists and was last modified at: " .. info.modified) +end + + + +r:regex(string, pattern) -- Runs a regular expression match on a string, returning captures if matched: - - r:regex(string, pattern) -- Runs a regular expression match on a string, returning captures if matched. - +local matches = r:regex("foo bar baz", "foo (%w+) (%S*)") +if matches then + r:puts("The regex matched, and the last word captured ($2) was: " .. matches[2]) +end + - + r:sleep(number_of_seconds) -- Puts the script to sleep for a given number of seconds. - -- This can be a floating point number like 1.25 for extra accuracy. - + -- This can be a floating point number like 1.25 for extra accuracy. + - + r:dbacquire(dbType[, dbParams]) -- Acquires a connection to a database and returns a database class. - -- See 'Database connectivity' for details. - + -- See 'Database connectivity' for details. +