From 99c30b1d1b45c477e68f2a57ebbe377c99a9196b Mon Sep 17 00:00:00 2001 From: david Date: Thu, 16 Oct 2008 03:18:03 +0000 Subject: [PATCH] Merge documetation for unpwdb, url, bit, tab, base64, and bin. --- docs/scripting.xml | 387 --------------------------------------------- nselib/base64.lua | 24 +-- nselib/bin.luadoc | 97 +++++++----- nselib/bit.luadoc | 31 +++- nselib/tab.lua | 60 ++++--- nselib/unpwdb.lua | 26 +-- nselib/url.lua | 145 ++++++++--------- 7 files changed, 215 insertions(+), 555 deletions(-) diff --git a/docs/scripting.xml b/docs/scripting.xml index 584c7d82a..0db85cd06 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -777,209 +777,6 @@ action refer to . The default modules are described in the following sections. - - Bitwise Logical Operations - bit NSE module - - Lua does not provide - bitwise logical operations.bitwise operations in NSE - Since they - are often useful for low-level network communication, - Reuben Thomas'Thomas, Reuben - bitwise operation library - for Lua has been - integrated into NSE. The arguments to the bitwise operation - functions should be integers. The number of bits available - for logical operations depends on the data type used to - represent Lua numbers—this is typically 8-byte IEEE - floats (double), which give 53 bits (the size of the mantissa). - - This implies that the bitwise operations won't work (as expected) - for numbers larger than 1014. You - can use them with 32-bit wide numbers without any problems. Operations - involving 64-bit wide numbers, however, may not return the expected - result. - The logical operations start with b (for bit) to avoid - clashing with reserved words; although xor isn't a - reserved word, it seemed better to use bxor for - consistency. In NSE the bitwise functions are in the bit - namespace. - - - - - - - - Returns the one's complement of a. - - - - - - - - - - Returns the bitwise and of the - w variables. - - - - - - - - - - Returns the bitwise or of the w variables. - - - - - - - - - - - Returns the bitwise xor of the w variables. - - - - - - - - - - Returns a shifted left b places—padded with zeros. - - - - - - - - - - Returns a shifted logically right b places. - - - - - - - - - - Returns a shifted arithmetically right b places. - - - - - - - - - - Returns the integer remainder of a divided by b. - - - - - - - - - Binary Data Handling - bin NSE module - - A problem script authors often face is the necessity of encoding values - into binary data. For example after analyzing a protocol the starting - point to write a script could be a hex dump, which serves as a preamble - to every sent packet. Although it is possible work with the - functionality Lua provides, it's not very convenient. Therefore the - Binlib has been added to NSE, based on - lpack - by Luiz Henrique de Figueiredo.Henrique de Figueiredo, Luiz - - The Binlib functions take a format string to encode and decode binary - data. The operators of the format string are shown in . - - - Binlib format string operators - - - - - Operator - Description - - - Hhex string - Bbit string - xnull byte - zzero-terminated string - pstring preceded by 1-byte integer length - Pstring preceded by 2-byte integer length - astring preceded by 4-byte integer length - Astring - ffloat - ddouble - nLua number - cchar (1-byte integer) - Cbyte = unsigned char (1-byte unsigned integer) - sshort (2-byte integer) - Sunsigned short (2-byte unsigned integer) - iint (4-byte integer) - Iunsigned int (4-byte unsigned integer) - llong (8-byte integer) - Lunsigned long (8-byte unsigned integer) - <little endian modifier - >big endian modifier - =native endian modifier -
- - Note that the endian operators work as modifiers to all the characters following them in the format string. - - - - - - - - Returns a binary packed string. The format string describes how - the parameters (p1, ...) will be interpreted. Numerical values following - operators stand for operator repetitions and need an according amount of - parameters. Operators expect appropriate parameter types. - - - - - - - - - - - Returns values read from the binary data string. - First result is the position, at which unpack stopped. This can - be used as init value for subsequent calls. The following results - are the values according to the format string. Numerical values in - the format string are interpreted as repetitions like in pack, - except if used with A, B or H, in which cases the number tells unpack - how many bytes to read. - - Unpack stops if either the format string or the binary data string - are exhausted. - - - - - - - pcre NSE module Perl Compatible Regular Expressions (PCRE)in NSE @@ -1428,190 +1225,6 @@ if(s) code_to_be_done_on_match end - - String Buffer Operations - strbuf NSE module - - Lua's string operations are very flexible and offer an easy-to-use way - to manipulate strings. Concatenation using the .. - operator is such an operation. The drawback of the built-in API however is the way it handles - concatenation of many string values. Since strings in Lua are - immutable values, each time you concatenate two strings both get copied - into the result string. The strbuf module offers a - workaround for this problem, while maintaining the nice syntax. This - is accomplished by overloading the concatenation operator (..) the equality operator (==) and the - tostring operator. By overloading - these operators, we reduce the overhead of using a string buffer instead - of a plain string to wrap the first literal string assigned to a - variable inside a strbuf.new() call. Afterwards you can append to the string buffer, or compare - two string buffers for equality just as you would do with normal strings. - When looking at the details there are some more restrictions/oddities: - The concatenation operator requires its left-hand value to be a - string buffer. Therefore, if you want to prepend a string to a given - string buffer you have to create a new string buffer out of the string - you want to prepend. - The string buffer's tostring operator concatenates the - strings inside the buffer using newlines by default, since this appears to - be the separator used most often. - - - - - - - - Creates a new string buffer. The optional arguments are added - to the string buffer. Attempting to add non-strings will - result in undefined behavior. - - - - - - - - - Concatenates the value (which has to be either - a string or a string buffer) to strbuf1. This - is also the function serving as the string buffer's concatenation operator. - The above function call can thus also be expressed as: - buffer = strbuf1 .. value - - - - - - - - - Compares strbuf1 and strbuf2 - for equality. For the function to return true, both values must be - string buffers containing exactly the same strings. The eqbuf function is called to compare two strings for equality. - - - - - - - - - Deletes all strings in strbuf. - - - - - - - - - Dumps strbuf's contents as string. The second - parameter is used as a delimiter between the strings stored inside - strbuf. dump(strbuf, "\n") is - used as the tostring function of string buffers. - - - - - - - URL Manipulation Functions - url NSE module - - URL manipulation functions have obvious uses. Fortunately - there is already an implementation of URL generation functions - inside the Lua socket package, which is fairly complete and - well - documented. For NSE, the url module was - extended with two functions: - - - - - - - - This function takes a query-string of the form name1=value1&name2=value2... and returns a table - containing the name-value pairs, with the name - as the key and the value as its associated value. - The table corresponding to the above query-string would have two - entries: table["name1"]="value1" and - table["name2"]="value2". - - - - - - - - This is the inverse function to parse_query(). - - - - - - - - Username/Password Database Functions - unpwdb NSE module - - The unpwdb module provides functions for easily obtaining - usernames and/or passwords from a "database" (list). The most obvious use - for this library is brute-force attack. The first two functions' return values - are setup for use with exception handling via nmap.new_try(). - exceptions in NSE - - - - - - - - This function returns a closure which returns a new username - with every call, or nil when the list is - exhausted. This closure takes an optional argument of - "reset" to rewind the list to the beginning. - You can specify your own username list with the script argument - userdb. - - - - - - - - - This function returns a closure which returns a new password - with every call, or nil when the list is - exhausted. This closure takes an optional argument of - "reset" to rewind the list to the beginning. - You can specify your own password list with the script argument - passdb. - - - - - - - - - This function returns the suggested number of seconds to - attempt a brute force attack, based on Nmap's timing values - (, etc) and whether or not a user-defined - list is used. You can use the script argument - notimelimit to make this function return - nil, which means the brute-force should - run until the list is empty. If notimelimit - is not used, be sure to still check for nil - return values on the above two functions in case you finish - before the time limit is up. - - - - - - - diff --git a/nselib/base64.lua b/nselib/base64.lua index 69efa74f8..2ce1e2f79 100644 --- a/nselib/base64.lua +++ b/nselib/base64.lua @@ -95,9 +95,9 @@ local bunpack = bin.unpack local concat = table.concat --- --- Encode six bits to a base64 encoded character ---@param bits String of six bits to be encoded ---@return Encoded character +-- Encode six bits to a base64 encoded character. +--@param bits String of six bits to be encoded. +--@return Encoded character. local function b64enc6bit(bits) -- local byte -- local _, byte = bunpack("C", bpack("B", "00" .. bits)) @@ -110,9 +110,9 @@ end --- --- Decodes a base64 encoded character into binary digits ---@param b64byte Single base64 encoded character ---@return String of six decoded bits +-- Decodes a base64 encoded character into binary digits. +--@param b64byte Single base64 encoded character. +--@return String of six decoded bits. local function b64dec6bit(b64byte) local bits = b64dctable[b64byte] if bits then return bits end @@ -121,9 +121,9 @@ end --- --- Encodes a string to base64 ---@param bdata Data to be encoded ---@return Base64 encoded string +-- Encodes a string to base64. +--@param bdata Data to be encoded. +--@return Base64 encoded string. function enc(bdata) local pos = 1 local byte @@ -152,9 +152,9 @@ end --- --- Decodes base64 encoded data ---@param b64data Base64 encoded data ---@return Decoded data +-- Decodes base64 encoded data. +--@param b64data Base64 encoded data. +--@return Decoded data. function dec(b64data) local bdataBuf = {} local pos = 1 diff --git a/nselib/bin.luadoc b/nselib/bin.luadoc index 56719604d..55b48fa38 100644 --- a/nselib/bin.luadoc +++ b/nselib/bin.luadoc @@ -1,49 +1,74 @@ ---- The Binary Data Library allows to pack and unpack to and from --- binary data. Encoding and decoding works by using a format --- string containing certain operator characters: --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
OperatorDescription
Hhex string
Bbit string
xnull byte
zzero-terminated string
pstring preceded by 1-byte integer length
Pstring preceded by 2-byte integer length
astring preceded by 4-byte integer length
Astring
ffloat
ddouble
nLua number
cchar (1-byte integer)
Cbyte = unsigned char (1-byte unsigned integer)
sshort (2-byte integer)
Sunsigned short (2-byte unsigned integer)
iint (4-byte integer)
Iunsigned int (4-byte unsigned integer)
llong (8-byte integer)
Lunsigned long (8-byte unsigned integer)
<little endian modifier
>big endian modifier
=native endian modifier
+--- Pack and unpack binary data. +-- \n\n +-- A problem script authors often face is the necessity of encoding values +-- into binary data. For example after analyzing a protocol the starting +-- point to write a script could be a hex dump, which serves as a preamble +-- to every sent packet. Although it is possible work with the +-- functionality Lua provides, it's not very convenient. Therefore NSE includes +-- Binlib, based on lpack (http://www.tecgraf.puc-rio.br/~lhf/ftp/lua/) +-- by Luiz Henrique de Figueiredo. +-- \n\n +-- The Binlib functions take a format string to encode and decode binary +-- data. Packing and unpacking are controlled by the following operator +-- characters:\n +-- H: hex string\n +-- B: bit string\n +-- x: null byte\n +-- z: zero-terminated string\n +-- p: string preceded by 1-byte integer length\n +-- P: string preceded by 2-byte integer length\n +-- a: string preceded by 4-byte integer length\n +-- A: string\n +-- f: float\n +-- d: double\n +-- n: Lua number\n +-- c: char (1-byte integer)\n +-- C: byte = unsigned char (1-byte unsigned integer)\n +-- s: short (2-byte integer)\n +-- S: unsigned short (2-byte unsigned integer)\n +-- i: int (4-byte integer)\n +-- I: unsigned int (4-byte unsigned integer)\n +-- l: long (8-byte integer)\n +-- L: unsigned long (8-byte unsigned integer)\n +-- <: little endian modifier\n +-- >: big endian modifier\n +-- =: native endian modifier +-- \n\n -- Note that the endian operators work as modifiers to all the -- characters following them in the format string. module "bin" ---- Packs values according to format string. --- Note: on Windows packing of 64 bit values > 2^63 currently +--- Returns a binary packed string. +-- \n\n +-- The format string describes how the parameters (p1, ...) will be interpreted. +-- Numerical values following operators stand for operator repetitions and need +-- an according amount of parameters. Operators expect appropriate parameter +-- types. +-- \n\n +-- Note: on Windows packing of 64 bit values > 2^63 currently -- results in packing exactly 2^63. ---@param format Format string, used to pack following arguments ---@return String containing packed data +--@param format Format string, used to pack following arguments. +--@param ... The values to pack. +--@return String containing packed data. function bin.pack(format, ...) ---- Unpacks values according to format string. ---@param format Format string, used to unpack values out of data string ---@param data String containing packed data ---@param init Optional starting position within the string ---@return First returned value is the position in the data string where unpacking stopped, following returned values are the unpacked values. +--- Returns values read from the binary packed data string. +-- \n\n +-- The first return value of this function is the position at which unpacking +-- stopped. This can be used as init value for subsequent calls. The following +-- results are the values according to the format string. Numerical values in +-- the format string are interpreted as repetitions like in pack, except if used +-- with A, B or H, in which cases the number tells unpack how many bytes to +-- read. Unpack stops if either the format string or the binary data string are +-- exhausted. +--@param format Format string, used to unpack values out of data string. +--@param data String containing packed data. +--@param init Optional starting position within the string. +--@return Position in the data string where unpacking stopped. +--@return All unpacked values. function bin.unpack(format, data, init) diff --git a/nselib/bit.luadoc b/nselib/bit.luadoc index 0855420d1..c3f6432fd 100644 --- a/nselib/bit.luadoc +++ b/nselib/bit.luadoc @@ -1,10 +1,28 @@ -module "bit" - ---- BitLib is a library by Reuben Thomas that provides facilities for --- bitwise operations on Integer values. +--- Bitwise operations on integers. +-- \n\n +-- Lua does not provide bitwise logical operations. Since they are often useful +-- for low-level network communication, Reuben Thomas' BitLib +-- (http://luaforge.net/projects/bitlib) for Lua has been integrated into NSE. +-- The arguments to the bitwise operation functions should be integers. The +-- number of bits available for logical operations depends on the data type used +-- to represent Lua numbers--this is typically 8-byte IEEE floats (double), +-- which give 53 bits (the size of the mantissa). +-- \n\n +-- This implies that the bitwise operations won't work (as expected) for numbers +-- larger than 10^14. You can use them with 32-bit wide numbers without any +-- problems. Operations involving 64-bit wide numbers, however, may not return +-- the expected result. +-- \n\n +-- The logical operations start with "b" to avoid +-- clashing with reserved words; although xor isn't a +-- reserved word, it seemed better to use bxor for +-- consistency. +-- -- @author Reuben Thomas -- @copyright BSD License +module "bit" + --- Cast a to an internally-used integer type. -- @param a Number. function bit.cast(a) @@ -43,3 +61,8 @@ function bit.rshift(a, b) -- @param a Number to perform the shift on. -- @param b Number of shifts. function bit.arshift(a, b) + +--- Returns the integer remainder of a divided by b. +-- @param a Dividend. +-- @param b Divisor. +function bit.mod(a, b) diff --git a/nselib/tab.lua b/nselib/tab.lua index d3b2d6565..24ac58ce3 100644 --- a/nselib/tab.lua +++ b/nselib/tab.lua @@ -1,13 +1,25 @@ ---- Provide NSE scripts with a way to output structured tables similar to --- NmapOutputTable.cc. +--- Arrange output into tables. +-- \n\n +-- This module provides NSE scripts with a way to output structured tables +-- similar to NmapOutputTable.cc. +-- \n\n +-- Example usage:\n +-- local t = tab.new(2)\n +-- tab.add(t, 1, 'A1')\n +-- tab.add(t, 2, 'A2')\n +-- tab.nextrow(t)\n +-- tab.add(t, 1, 'BBBBBBBBB1')\n +-- tab.add(t, 2, 'BBB2')\n +-- tab.dump(t) --@copyright See nmaps COPYING for license module(... or "tab",package.seeall) require('strbuf') ---- Create and return a new table with a number of columns equal to col and +--- Create and return a new table with a number of columns equal to cols and -- the row counter set to 1. +-- @param cols the number of columns the table will hold. function new(cols) assert(cols > 0) local table ={} @@ -18,9 +30,14 @@ function new(cols) return table end ---- Add a new string item (v) in a previously initialised table (t) --- at column position 'c'. The data will be added to the current --- row, if nextrow() hasn't been called yet that will be row 1. +--- Add a new string item to a table at a given column position. +-- \n\n +-- The item will be added to the current row. If nextrow hasn't been called yet +-- that will be row 1. +-- +-- @param t the table. +-- @param v the string to add. +-- @param c the column position at which to add the item. function add(t, c, v) assert(t) assert(v) @@ -42,9 +59,12 @@ function add(t, c, v) end --- Add a complete row to the table and move on to the next row. --- Calls add() for each argument starting with the second argument --- and after that calls nextrow(). -function addrow(t,...) +-- \n\n +-- Calls add for each argument starting with the second argument +-- and after that calls nextrow. +-- @param t the table. +-- @param ... the elements to add to the row. +function addrow(t, ...) for i=1, arg['n'] do add( t, i, tostring(arg[i]) ) end @@ -54,16 +74,18 @@ end --- Move on to the next row in the table. If this is not called -- then previous column values will be over-written by subsequent -- values. +-- @param t the table. function nextrow(t) assert(t) assert(t['rows']) t['rows'] = t['rows'] + 1 end ---- Once items have been added to a table, call this to return a --- string which contains an equally spaced table. Number of spaces --- is based on the largest element of a column with an additional --- two spaces for padding. +--- Return a formatted string representation of the table. +-- \n\n +-- The number of spaces in a column is based on the largest element in the +-- column with an additional two spaces for padding. +-- @param t the table. function dump(t) assert(t) assert(t['rows']) @@ -99,15 +121,3 @@ function dump(t) return strbuf.dump(table) end - ---[[ Example Usage - -local t = tab.new(2) -tab.add(t, 1, 'A1') -tab.add(t, 2, 'A2') -tab.nextrow(t) -tab.add(t, 1, 'BBBBBBBBB1') -tab.add(t, 2, 'BBB2') -tab.dump(t) - ---]] diff --git a/nselib/unpwdb.lua b/nselib/unpwdb.lua index 796cf50af..a4d8ff93e 100644 --- a/nselib/unpwdb.lua +++ b/nselib/unpwdb.lua @@ -1,12 +1,13 @@ ---- Username/Password Database Library. +--- Username/password database library. +-- \n\n -- The usernames and passwords functions return multiple values for use -- with exception handling via nmap.new_try(). -- The first value is the boolean success indicator, the second value is -- the closure. --- +-- \n\n -- The closures can take a parameter of "reset" to rewind the list to the -- beginning. --- +-- \n\n -- You can select your own username and/or password database to read from with -- the script arguments userdb and passdb, respectively. Comments are allowed -- in these files, prefixed with "#!comment:". Comments cannot be on the same @@ -89,11 +90,12 @@ end --- Returns the suggested number of seconds to attempt a brute -- force attack, based on Nmap's timing values (-T4, etc) and whether or not a --- user-defined list is used. You can use the script argument "notimelimit" to --- make this function return nil, which means the brute-force should run until --- the list is empty. If "notimelimit" is not used, be sure to still check for --- nil return values on the above two functions in case you finish before the --- time limit is up. +-- user-defined list is used. +-- \n\n +-- You can use the script argument "notimelimit" to make this function return +-- nil, which means the brute-force should run until the list is empty. If +-- "notimelimit" is not used, be sure to still check for nil return values on +-- the above two functions in case you finish before the time limit is up. timelimit = function() -- If we're reading from a user-defined username or password list, -- we'll give them a timeout 1.5x the default. If the "notimelimit" @@ -116,8 +118,8 @@ end --- Returns a function closure which returns a new username with every call -- until the username list is exhausted (in which case it returns nil). --- @return boolean Status --- @return function The usernames iterator +-- @return boolean Status. +-- @return function The usernames iterator. usernames = function() local path = userfile() @@ -134,8 +136,8 @@ end --- Returns a function closure which returns a new password with every call -- until the password list is exhausted (in which case it returns nil). --- @return boolean Status --- @return function The passwords iterator +-- @return boolean Status. +-- @return function The passwords iterator. passwords = function() local path = passfile() diff --git a/nselib/url.lua b/nselib/url.lua index a3dfb1aab..7aa486df2 100644 --- a/nselib/url.lua +++ b/nselib/url.lua @@ -1,14 +1,14 @@ ---- URI parsing, composition and relative URL resolution. +--- URI parsing, composition, and relative URL resolution. +-- @author Diego Nehab +-- @author Eddie Bell --[[ - URI parsing, composition and relative URL resolution LuaSocket toolkit. Author: Diego Nehab RCS ID: $Id: url.lua,v 1.37 2005/11/22 08:33:29 diego Exp $ parse_query() and build_query() added For nmap (Eddie Bell ) - --]] ----------------------------------------------------------------------------- @@ -23,14 +23,11 @@ _VERSION = "URL 1.0" --[[ Internal functions --]] ------------------------------------------------------------------------------ +--- -- Protects a path segment, to prevent it from interfering with the -- url parsing. --- Input --- s: binary string to be encoded --- Returns --- escaped representation of string binary ------------------------------------------------------------------------------ +-- @param s binary string to be encoded. +-- @return escaped representation of string binary. local function make_set(t) local s = {} for i,v in base.ipairs(t) do @@ -53,13 +50,11 @@ local function protect_segment(s) end) end ------------------------------------------------------------------------------ +--- -- Builds a path from a base path and a relative path --- Input --- base_path --- relative_path --- Returns --- corresponding absolute path +-- @param base_path a base path. +-- @param relative_path a relative path. +-- @return corresponding absolute path. ----------------------------------------------------------------------------- local function absolute_path(base_path, relative_path) if string.sub(relative_path, 1, 1) == "/" then return relative_path end @@ -85,12 +80,10 @@ end --[[ External functions --]] ------------------------------------------------------------------------------ --- Encodes a string into its escaped hexadecimal representation --- Input --- s: binary string to be encoded --- Returns --- escaped representation of string binary +--- +-- Encodes a string into its escaped hexadecimal representation. +-- @param s binary string to be encoded. +-- @return escaped representation of string binary. ----------------------------------------------------------------------------- function escape(s) return string.gsub(s, "([^A-Za-z0-9_])", function(c) @@ -99,12 +92,10 @@ function escape(s) end ------------------------------------------------------------------------------ --- Encodes a string into its escaped hexadecimal representation --- Input --- s: binary string to be encoded --- Returns --- escaped representation of string binary +--- +-- Encodes a string into its escaped hexadecimal representation. +-- @param s binary string to be encoded. +-- @return escaped representation of string binary. ----------------------------------------------------------------------------- function unescape(s) return string.gsub(s, "%%(%x%x)", function(hex) @@ -113,23 +104,22 @@ function unescape(s) end ------------------------------------------------------------------------------ --- Parses a url and returns a table with all its parts according to RFC 2396 --- The following grammar describes the names given to the URL parts --- ::= :///;?# --- ::= @: --- ::= [:] --- :: = {/} --- Input --- url: uniform resource locator of request --- default: table with default values for each field --- Returns --- table with the following fields, where RFC naming conventions have +--- +-- Parses a URL and returns a table with all its parts according to RFC 2396. +-- \n\n +-- The following grammar describes the names given to the URL parts.\n +-- ::= :///;?#\n +-- ::= @:\n +-- ::= [:]\n +-- :: = {/}\n +-- \n\n +-- Obs: the leading '/' in {/} is considered part of . +-- @param url uniform resource locator of request +-- @param default table with default values for each field +-- @return a table with the following fields, where RFC naming conventions have -- been preserved: -- scheme, authority, userinfo, user, password, host, port, --- path, params, query, fragment --- Obs: --- the leading '/' in {/} is considered part of +-- path, params, query, fragment. ----------------------------------------------------------------------------- function parse(url, default) -- initialize default parameters @@ -179,13 +169,12 @@ function parse(url, default) return parsed end ------------------------------------------------------------------------------ +--- -- Rebuilds a parsed URL from its components. --- Components are protected if any reserved or unallowed characters are found --- Input --- parsed: parsed URL, as returned by parse --- Returns --- a stringing with the corresponding URL +-- \n\n +-- Components are protected if any reserved or unallowed characters are found. +-- @param parsed parsed URL, as returned by parse. +-- @return a string with the corresponding URL. ----------------------------------------------------------------------------- function build(parsed) local ppath = parse_path(parsed.path or "") @@ -212,13 +201,11 @@ function build(parsed) return url end ------------------------------------------------------------------------------ --- Builds a absolute URL from a base and a relative URL according to RFC 2396 --- Input --- base_url --- relative_url --- Returns --- corresponding absolute url +--- +-- Builds a absolute URL from a base and a relative URL according to RFC 2396. +-- @param base_url a base URL. +-- @param relative_url a relative URL. +-- @param corresponding absolute URL. ----------------------------------------------------------------------------- function absolute(base_url, relative_url) if type(base_url) == "table" then @@ -252,12 +239,10 @@ function absolute(base_url, relative_url) end end ------------------------------------------------------------------------------ --- Breaks a path into its segments, unescaping the segments --- Input --- path --- Returns --- segment: a table with one entry per segment +--- +-- Breaks a path into its segments, unescaping the segments. +-- @param path a path to break. +-- @return a table with one entry per segment. ----------------------------------------------------------------------------- function parse_path(path) local parsed = {} @@ -272,13 +257,11 @@ function parse_path(path) return parsed end ------------------------------------------------------------------------------ +--- -- Builds a path component from its segments, escaping protected characters. --- Input --- parsed: path segments --- unsafe: if true, segments are not protected before path is built --- Returns --- path: corresponding path stringing +-- @param parsed path segments. +-- @param unsafe if true, segments are not protected before path is built. +-- @return corresponding path string ----------------------------------------------------------------------------- function build_path(parsed, unsafe) local path = "" @@ -306,12 +289,16 @@ function build_path(parsed, unsafe) return path end ------------------------------------------------------------------------------ --- Breaks a query string into name/value pairs --- Input --- query string (name=value&name=value ...) --- Returns --- table where name=value is table['name'] = value +--- +-- Breaks a query string into name/value pairs. +-- \n\n +-- This function takes a of the form name1=value1&name2=value2... +-- and returns a table containing the name-value pairs, with the name as the key +-- and the value as its associated value. The table corresponding to the above +-- would have two entries: table["name1"]="value1" and +-- table["name2"]="value2". +-- @param query string (name=value&name=value ...). +-- @return table where name=value is table['name'] = value. ----------------------------------------------------------------------------- function parse_query(query) local parsed = {} @@ -341,12 +328,12 @@ function parse_query(query) return parsed end ------------------------------------------------------------------------------ --- Builds a query string from dictionary based table --- Input --- dictionary table where table['name'] = value --- Returns --- query string (name=value&name=value ...) +--- +-- Builds a query string from dictionary based table. +-- \n\n +-- This is the inverse of parse_query. +-- @param dictionary table where table['name'] = value. +-- @return query string (name=value&name=value ...) ----------------------------------------------------------------------------- function build_query(query) local qstr = ""