Proofread and update documentation of http, ipOps, and listop.

nselib/http.lua

@@ -1,17 +1,18 @@
 --- Client-side HTTP library.
--- \n\n
+--
 -- The return value of each function in this module is a table with the
--- following keys: status, status-line, header, and body. status is a number
--- representing the HTTP status code returned in response to the HTTP
--- request. In case of an unhandled error, status is nil. status-line is
--- the entire status message which includes the HTTP version, status code
--- and reason phrase. The header value is a table containing key-value
--- pairs of HTTP headers received in response to the request. The header
--- names are in lower-case and are the keys to their corresponding header
--- values (e.g. header.location = "http://nmap.org/").
--- Multiple headers of the same name are concatenated and separated by
--- commas. The body value is a string containing the body of the HTTP
--- response.
+-- following keys: <code>status</code>, <code>status-line</code>,
+-- <code>header</code>, and <code>body</code>. <code>status</code> is a number
+-- representing the HTTP status code returned in response to the HTTP request.
+-- In case of an unhandled error, <code>status</code> is <code>nil</code>.
+-- <code>status-line</code> is the entire status message which includes the HTTP
+-- version, status code, and reason phrase. The <code>header</code> value is a
+-- table containing key-value pairs of HTTP headers received in response to the
+-- request. The header names are in lower-case and are the keys to their
+-- corresponding header values (e.g. <code>header.location</code> =
+-- <code>"http://nmap.org/"</code>). Multiple headers of the same name are
+-- concatenated and separated by commas. The <code>body</code> value is a string
+-- containing the body of the HTTP response.
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 
 module(... or "http",package.seeall)
@@ -35,20 +36,19 @@ local stdnse = require 'stdnse'
 
 
 --- Fetches a resource with a GET request.
--- \n\n
--- The first argument is either a
--- string with the hostname or a table like the host table passed by nmap.
--- The second argument is either the port number or a table like the port
--- table passed by nmap. The third argument is the path of the resource.
--- The fourth argument is a table for further options. The table may have
--- 2 keys: timeout and header. timeout is the timeout used for the socket
--- operations. header is a table with additional headers to be used for
--- the request. The function builds the request and calls http.request.
+--
+-- The first argument is either a string with the hostname or a table like the
+-- host table passed to a portrule or hostrule. The second argument is either
+-- the port number or a table like the port table passed to a portrule or
+-- hostrule. The third argument is the path of the resource. The fourth argument
+-- is a table for further options. The function builds the request and calls
+-- <code>http.request()</code>.
 -- @param host The host to query.
 -- @param port The port for the host.
 -- @param path The path of the resource.
--- @param options A table of options. See function description.
--- @return table
+-- @param options A table of options, as with <code>http.request()</code>.
+-- @return Table as described in the function description.
+-- @see http.request
 get = function( host, port, path, options )
   options = options or {}
   local presets = {Host=host,Connection="close",['User-Agent']="Mozilla/5.0 (compatible; Nmap Scripting Engine; http://nmap.org/book/nse.html)"}
@@ -70,14 +70,11 @@ get = function( host, port, path, options )
   return request( host, port, data, options )
 end
 
---- Parses a URL and calls http.get with the result.
--- \n\n
--- The second argument
--- is a table for further options. The table may have 2 keys: timeout
--- and header. timeout is the timeout used for the socket operations.
--- header is a table with additional headers to be used for the request. 
--- @param u The url of the host.
--- @param options Options passed to http.get.
+--- Parses a URL and calls <code>http.get</code> with the result.
+--
+-- The second argument is a table for further options.
+-- @param u The URL of the host.
+-- @param options A table of options, as with <code>http.request()</code>.
 -- @see http.get
 get_url = function( u, options )
   local parsed = url.parse( u )
@@ -103,20 +100,20 @@ get_url = function( u, options )
 end
 
 --- Sends request to host:port and parses the answer.
--- \n\n
--- The first argument
--- is either a string with the hostname or a table like the host table
--- passed by nmap. The second argument is either the port number or a
--- table like the port table passed by nmap. SSL is used for the request
--- if either port.service  equals https or port.version.service_tunnel
--- equals ssl. The third argument is the request. The fourth argument is
--- a table for further options. You can specify a timeout for the socket
--- operations with the timeout key. 
+--
+-- The first argument is either a string with the hostname or a table like the
+-- host table passed to a portrule or hostrule. The second argument is either
+-- the port number or a table like the port table passed to a portrule or
+-- hostrule. SSL is used for the request if <code>port.service</code> is
+-- <code>"https"</code> or <code>port.version.service_tunnel</code> is
+-- <code>"ssl"</code>. The third argument is the request. The fourth argument is
+-- a table for further options.
 -- @param host The host to query.
 -- @param port The port on the host.
 -- @param data Data to send initially to the host.
--- @param options Table of options.
--- @see http.get
+-- @param options A table of options. It may have any of these fields:
+-- * <code>timeout</code>: A timeout used for socket operations.
+-- * <code>header</code>: A table containing additional headers to be used for the request.
 request = function( host, port, data, options )
   options = options or {}
 

nselib/ipOps.lua

@@ -16,18 +16,20 @@ module ( "ipOps" )
 ---
 -- Checks to see if the supplied IP address is part of a non-routable
 -- address space.
--- \n\n
--- The non-Internet-routable address spaces known to this function are:
--- IPv4 Loopback (RFC3330),
--- IPv4 Private Use (RFC1918),
--- IPv4 Link Local (RFC3330),
--- IPv6 Unspecified and Loopback (RFC3513),
--- IPv6 Unique Local Unicast (RFC4193),
--- IPv6 Link Local Unicast (RFC4291)
--- @param ip  String representing an IPv4 or IPv6 address.  Shortened notation is permitted.
--- @usage     local is_private = ipOps.isPrivate( "192.168.1.1" )
--- @return    Boolean True or False (or nil in case of an error).
--- @return    Nil (or String error message in case of an error).
+--
+-- The non-Internet-routable address spaces known to this function are
+-- * IPv4 Loopback (RFC3330)
+-- * IPv4 Private Use (RFC1918)
+-- * IPv4 Link Local (RFC3330)
+-- * IPv6 Unspecified and Loopback (RFC3513)
+-- * IPv6 Unique Local Unicast (RFC4193)
+-- * IPv6 Link Local Unicast (RFC4291)
+-- @param ip  String representing an IPv4 or IPv6 address.  Shortened notation
+-- is permitted.
+-- @usage
+-- local is_private = ipOps.isPrivate( "192.168.1.1" )
+-- @return True or false (or <code>nil</code> in case of an error).
+-- @return String error message in case of an error.
 isPrivate = function( ip )
 
   ip, err = expand_ip( ip )
@@ -56,16 +58,19 @@ end
 
 ---
 -- Converts the supplied IPv4 address into a DWORD value.
--- \n\n
+--
 -- For example, the address a.b.c.d becomes (((a*256+b)*256+c)*256+d).
--- \n\n
+--
 -- Note: IPv6 addresses are not supported. Currently, numbers in NSE are
--- limited to 10^14, consequently not all IPv6 addresses can be
--- represented in base 10.
--- @param ip  String representing an IPv4 address.  Shortened notation is permitted.
--- @usage     local dword = ipOps.todword( "73.150.2.210" )
--- @return    Number corresponding to the supplied IP address (or nil in case of an error).
--- @return    Nil (or String error message in case of an error).
+-- limited to 10^14, and consequently not all IPv6 addresses can be
+-- represented.
+-- @param ip  String representing an IPv4 address.  Shortened notation is
+-- permitted.
+-- @usage
+-- local dword = ipOps.todword( "73.150.2.210" )
+-- @return Number corresponding to the supplied IP address (or <code>nil</code>
+-- in case of an error).
+-- @return String error message in case of an error.
 todword = function( ip )
 
   if type( ip ) ~= "string" or ip:match( ":" ) then
@@ -86,15 +91,18 @@ end
 
 ---
 -- Separates the supplied IP address into its constituent parts and
--- returns them as a table of decimal numbers.
--- \n\n
+-- returns them as a table of numbers.
+--
 -- For example, the address 139.104.32.123 becomes { 139, 104, 32, 123 }.
--- @usage     local a, b, c, d;\n
---            local t, err = get_parts_as_number( "139.104.32.123" );\n
---            if t then a, b, c, d = unpack( t ) end
--- @param ip  String representing an IPv4 or IPv6 address.  Shortened notation is permitted.
--- @return    Array-style Table containing decimal numbers for each part of the supplied IP address (or nil in case of an error).
--- @return    Nil (or String error message in case of an error).
+-- @usage
+-- local a, b, c, d;
+-- local t, err = get_parts_as_number( "139.104.32.123" )
+-- if t then a, b, c, d = unpack( t ) end
+-- @param ip  String representing an IPv4 or IPv6 address.  Shortened notation
+-- is permitted.
+-- @return   Array of numbers for each part of the supplied IP address (or
+-- <code>nil</code> in case of an error).
+-- @return String error message in case of an error.
 get_parts_as_number = function( ip )
 
   ip, err = expand_ip( ip )
@@ -121,12 +129,19 @@ end
 
 ---
 -- Compares two IP addresses (from the same address family).
--- @param left   String representing an IPv4 or IPv6 address.  Shortened notation is permitted.
--- @param op     A comparison operator which may be one of the following strings: "eq", "ge", "le", "gt" or "lt" (respectively ==, >=, <=, >, <).
--- @param right  String representing an IPv4 or IPv6 address.  Shortened notation is permitted.
--- @usage        if ipOps.compare_ip( "2001::DEAD:0:0:0", "eq", "2001:0:0:0:DEAD::" ) then ...
--- @return       Boolean True or False (or nil in case of an error).
--- @return       Nil (or String error message in case of an error).
+-- @param left   String representing an IPv4 or IPv6 address.  Shortened
+-- notation is permitted.
+-- @param op     A comparison operator which may be one of the following
+-- strings: <code>"eq"</code>, <code>"ge"</code>, <code>"le"</code>,
+-- <code>"gt"</code> or <code>"lt"</code> (respectively ==, >=, <=, >, <).
+-- @param right  String representing an IPv4 or IPv6 address.  Shortened
+-- notation is permitted.
+-- @usage
+-- if ipOps.compare_ip( "2001::DEAD:0:0:0", "eq", "2001:0:0:0:DEAD::" ) then
+--   ...
+-- end
+-- @return True or false (or <code>nil</code> in case of an error).
+-- @return String error message in case of an error.
 compare_ip = function( left, op, right )
 
   if type( left ) ~= "string" or type( right ) ~= "string" then
@@ -179,14 +194,20 @@ end
 
 
 ---
--- Checks whether the supplied IP address is within the supplied range of IP addresses.
--- \n\n
+-- Checks whether the supplied IP address is within the supplied range of IP
+-- addresses.
+--
 -- The address and the range must both belong to the same address family.
--- @param ip     String representing an IPv4 or IPv6 address.  Shortened notation is permitted.
--- @param range  String representing a range of IPv4 or IPv6 addresses in first-last or cidr notation  (e.g. "192.168.1.1 - 192.168.255.255" or "2001:0A00::/23").
--- @usage        if ipOps.ip_in_range( "192.168.1.1", "192/8" ) then ...
--- @return       Boolean True or False (or nil in case of an error).
--- @return       Nil (or String error message in case of an error).
+-- @param ip     String representing an IPv4 or IPv6 address.  Shortened
+-- notation is permitted.
+-- @param range  String representing a range of IPv4 or IPv6 addresses in
+-- first-last or CIDR notation (e.g.
+-- <code>"192.168.1.1 - 192.168.255.255"</code> or
+-- <code>"2001:0A00::/23"</code>).
+-- @usage
+-- if ipOps.ip_in_range( "192.168.1.1", "192/8" ) then ... end
+-- @return True or false (or <code>nil</code> in case of an error).
+-- @return String error message in case of an error.
 ip_in_range = function( ip, range )
 
   local first, last, err = get_ips_from_range( range )
@@ -218,13 +239,16 @@ end
 ---
 -- Expands an IP address supplied in shortened notation.
 -- Serves also to check the well-formedness of an IP address.
--- \n\n
--- Note: IPv4in6 notated addresses will be returned in pure IPv6 notation unless the IPv4 portion
--- is shortened and does not contain a dot - in which case the address will be treated as IPv6.
+--
+-- Note: IPv4in6 notated addresses will be returned in pure IPv6 notation unless
+-- the IPv4 portion is shortened and does not contain a dot, in which case the
+-- address will be treated as IPv6.
 -- @param ip  String representing an IPv4 or IPv6 address in shortened or full notation.
--- @usage     local ip = ipOps.expand_ip( "2001::" )
--- @return    String representing a fully expanded IPv4 or IPv6 address (or nil in case of an error).
--- @return    Nil (or String error message in case of an error).
+-- @usage
+-- local ip = ipOps.expand_ip( "2001::" )
+-- @return    String representing a fully expanded IPv4 or IPv6 address (or
+-- <code>nil</code> in case of an error).
+-- @return String error message in case of an error.
 expand_ip = function( ip )
 
   if type( ip ) ~= "string" or ip == "" then
@@ -312,11 +336,15 @@ end
 
 ---
 -- Returns the first and last IP addresses in the supplied range of addresses.
--- @param range  String representing a range of IPv4 or IPv6 addresses in either cidr or first-last notation.
--- @usage        first, last = ipOps.get_ips_from_range( "192.168.0.0/16" )
--- @return       String representing the first address in the supplied range (or nil in case of an error).
--- @return       String representing the last address in the supplied range (or nil in case of an error).
--- @return       Nil (or String error message in case of an error).
+-- @param range  String representing a range of IPv4 or IPv6 addresses in either
+-- CIDR or first-last notation.
+-- @usage
+-- first, last = ipOps.get_ips_from_range( "192.168.0.0/16" )
+-- @return       String representing the first address in the supplied range (or
+-- <code>nil</code> in case of an error).
+-- @return       String representing the last address in the supplied range (or
+-- <code>nil</code> in case of an error).
+-- @return       String error message in case of an error.
 get_ips_from_range = function( range )
 
   if type( range ) ~= "string" then
@@ -356,12 +384,17 @@ end
 
 
 ---
--- Calculates the last IP address of a range of addresses given an IP address in the range and prefix length for that range.
--- @param ip      String representing an IPv4 or IPv6 address.  Shortened notation is permitted.
--- @param prefix  Decimal number or a string representing a decimal number corresponding to a Prefix length.
--- @usage         last = ipOps.get_last_ip( "192.0.0.0", 26 )
--- @return        String representing the last IP address of the range denoted by the supplied parameters (or nil in case of an error).
--- @return        Nil (or String error message in case of an error).
+-- Calculates the last IP address of a range of addresses given an IP address in
+-- the range and prefix length for that range.
+-- @param ip      String representing an IPv4 or IPv6 address.  Shortened
+-- notation is permitted.
+-- @param prefix  Number or a string representing a decimal number corresponding
+-- to a prefix length.
+-- @usage
+-- last = ipOps.get_last_ip( "192.0.0.0", 26 )
+-- @return        String representing the last IP address of the range denoted
+-- by the supplied parameters (or <code>nil</code> in case of an error).
+-- @return String error message in case of an error.
 get_last_ip = function( ip, prefix )
 
   local first, err = ip_to_bin( ip )
@@ -384,11 +417,15 @@ end
 
 
 ---
--- Converts an IP address into a string representing the address as binary digits.
--- @param ip  String representing an IPv4 or IPv6 address.  Shortened notation is permitted.
--- @usage     bit_string = ipOps.ip_to_bin( "2001::" )
--- @return    String representing the supplied IP address as 32 or 128 binary digits (or nil in case of an error).
--- @return    Nil (or String error message in case of an error).
+-- Converts an IP address into a string representing the address as binary
+-- digits.
+-- @param ip  String representing an IPv4 or IPv6 address.  Shortened notation
+-- is permitted.
+-- @usage
+-- bit_string = ipOps.ip_to_bin( "2001::" )
+-- @return    String representing the supplied IP address as 32 or 128 binary
+-- digits (or <code>nil</code> in case of an error).
+-- @return    String error message in case of an error.
 ip_to_bin = function( ip )
 
   ip, err = expand_ip( ip )
@@ -422,11 +459,14 @@ end
 
 
 ---
--- Converts a string representing binary digits into an IP address.
--- @param binstring  String representing an IP address as 32 or 128 binary digits.
--- @usage            ip = ipOps.bin_to_ip( "01111111000000000000000000000001" )
--- @return           String representing an IP address (or nil in case of an error).
--- @return           Nil (or String error message in case of an error).
+-- Converts a string of binary digits into an IP address.
+-- @param binstring  String representing an IP address as 32 or 128 binary
+-- digits.
+-- @usage
+-- ip = ipOps.bin_to_ip( "01111111000000000000000000000001" )
+-- @return           String representing an IP address (or <code>nil</code> in
+-- case of an error).
+-- @return           String error message in case of an error.
 bin_to_ip = function( binstring )
 
   if type( binstring ) ~= "string" or binstring:match( "[^01]+" ) then
@@ -463,12 +503,17 @@ end
 
 
 ---
--- Converts a string representing a hexadecimal number into a string representing that number as binary digits.
--- Each hex digit results in four bits - this function is really just a wrapper around stdnse.tobinary().
+-- Converts a string of hexadecimal digits into the corresponding string of
+-- binary digits.
+--
+-- Each hex digit results in four bits. This function is really just a wrapper
+-- around <code>stdnse.tobinary()</code>.
 -- @param hex  String representing a hexadecimal number.
--- @usage      bin_string = ipOps.hex_to_bin( "F00D" )
--- @return     String representing the supplied number in binary digits (or nil in case of an error).
--- @return     Nil (or String error message in case of an error).
+-- @usage
+-- bin_string = ipOps.hex_to_bin( "F00D" )
+-- @return     String representing the supplied number in binary digits (or
+-- <code>nil</code> in case of an error).
+-- @return     String error message in case of an error.
 hex_to_bin = function( hex )
 
   if type( hex ) ~= "string" or hex == "" or hex:match( "[^%x]+" ) then

nselib/listop.lua

@@ -1,11 +1,11 @@
 --- Functional-style list operations.
--- \n\n
+--
 -- People used to programming in functional languages, such as Lisp
--- or Haskell, appreciate their handling of lists very much. The listop
--- module tries to bring much of the functionality from functional languages
--- to Lua using Lua's central data structure, the table, as a base for its
--- list operations. Highlights include a map function applying a given
--- function to each element of a list. 
+-- or Haskell, appreciate their handling of lists very much. The
+-- <code>listop</code> module tries to bring much of the functionality from
+-- functional languages to Lua using Lua's central data structure, the table, as
+-- a base for its list operations. Highlights include a <code>map()</code>
+-- function applying a given function to each element of a list. 
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 
 module(... or "listop", package.seeall)
@@ -36,26 +36,25 @@ Functional programming style 'list' operations
 
 --- Returns true if the given list is empty.
 -- @param l A list.
--- @return boolean
+-- @return True or false.
 function is_empty(l)
   return #l == 0 and true or false;
 end
 
 --- Returns true if the given value is a list (or rather a table).
 -- @param l Any value.
--- @return boolean
+-- @return True or false.
 function is_list(l)
   return type(l) == 'table' and true or false;
 end
 
---- Calls f for each element in the list. The returned list contains
--- the results of each function call.
--- \n\n
--- For example, listop.map(tostring,{1,2,true})  returns
--- {"1","2","true"}. 
+--- Calls <code>f</code> for each element in the list. The returned list
+--contains the results of each function call.
+-- @usage
+-- listop.map(tostring,{1,2,true}) --> {"1","2","true"}
 -- @param f The function to call.
 -- @param l A list.
--- @return List
+-- @return List of function results.
 function map(f, l) 
     local results = {}
     for _, v in ipairs(l) do
@@ -65,26 +64,26 @@ function map(f, l)
 end
 
 --- Calls the function with all the elements in the list as the parameters.
--- \n\n
--- For example, listop.apply(math.max,{1,5,6,7,50000}) yields 50000. 
+-- @usage
+-- listop.apply(math.max,{1,5,6,7,50000}) --> 50000
 -- @param f The function to call.
 -- @param l A list.
--- @return Results from f.
+-- @return Results from <code>f</code>.
 function apply(f, l)
   return f(unpack(l))
 end
 
 --- Returns a list containing only those elements for which a predicate
 -- function returns true.
--- \n\n
+--
 -- The predicate has to be a function taking one argument and returning
--- a Boolean. If it returns true (or rather anything besides false and
--- nil) the argument is appended to the return value of filter. For
--- example, listop.filter(isnumber,{1,2,3,"foo",4,"bar"}) returns
--- {1,2,3,4}. 
+-- a Boolean. If it returns true, the argument is appended to the return value
+-- of filter.
+-- @usage
+-- listop.filter(isnumber,{1,2,3,"foo",4,"bar"}) --> {1,2,3,4}
 -- @param f The function.
 -- @param l The list.
--- @return List
+-- @return Filtered list.
 function filter(f, l) 
   local results = {}
   for i, v in ipairs(l) do
@@ -96,47 +95,49 @@ function filter(f, l)
 end
 
 --- Fetch the first element of a list.
--- @param l The List.
+-- @param l The list.
 -- @return The first element.
 function car(l)
   return l[1]
 end
 
---- Fetch all elements following the first in a new List.
--- @param l The List.
--- @return List
+--- Fetch all elements following the first in a new list.
+-- @param l The list.
+-- @return Elements after the first.
 function cdr(l)
   return {unpack(l, 2)}
 end
 
---- Fetch element at index x from l.
--- @param l The List.
+--- Fetch element at index <code>x</code> from <code>l</code>.
+-- @param l The list.
 -- @param x Element index.
--- @return Element x or 1.
+-- @return Element at index <code>x</code> or at index <code>1</code> if
+-- <code>x</code> is not given.
 function ncar(l, x)
   return l[x or 1];
 end
 
---- Fetch all elements following the element at index x or the first.
--- @param l The List.
+--- Fetch all elements following the element at index <code>x</code>.
+-- @param l The list.
 -- @param x Element index.
--- @return List
+-- @return Elements after index <code>x</code> or after index <code>1</code> if
+-- <code>x</code> is not given.
 function ncdr(l, x) 
   return {unpack(l, x or 2)};
 end
 
 --- Prepend a value or list to another value or list.
--- @param v1 value or list
--- @param v2 value or list
--- @return List
+-- @param v1 value or list.
+-- @param v2 value or list.
+-- @return New list.
 function cons(v1, v2)
     return{ is_list(v1) and {unpack(v1)} or v1, is_list(v2) and {unpack(v2)} or v2}
 end
 
 --- Concatenate two lists and return the result.
--- @param l1 List
--- @param l2 List
--- @return List
+-- @param l1 List.
+-- @param l2 List.
+-- @return List.
 function append(l1, l2)
     local results = {unpack(l1)}
 
@@ -146,9 +147,9 @@ function append(l1, l2)
     return results
 end
 
---- Return l in reverse order.
+--- Return a list in reverse order.
 -- @param l List.
--- @return List
+-- @return Reversed list.
 function reverse(l)
     local results = {}
     for i=#l, 1, -1 do
@@ -159,11 +160,10 @@ end
 
 --- Return a flattened version of a list. The flattened list contains
 -- only non-list values.
--- \n\n
--- For example, listop.flatten({1,2,3,"foo",{4,5,{"bar"}}}) returns
--- {1,2,3,"foo",4,5,"bar"}.
+-- @usage
+-- listop.flatten({1,2,3,"foo",{4,5,{"bar"}}}) --> {1,2,3,"foo",4,5,"bar"}
 -- @param l The list to flatten.
--- @return List
+-- @return Flattened list.
 function flatten(l)
     local function flat(r, t)
     	for i, v in ipairs(t) do