From 2762f911692f8eaaebd4b2566114a42ff5a624f4 Mon Sep 17 00:00:00 2001 From: david Date: Thu, 23 Oct 2008 18:31:00 +0000 Subject: [PATCH] Reformat docs in stdnse.lua. --- nselib/stdnse.lua | 124 ++++++++++++++++++++++++---------------------- 1 file changed, 65 insertions(+), 59 deletions(-) diff --git a/nselib/stdnse.lua b/nselib/stdnse.lua index 14f423d5d..45e8d174d 100644 --- a/nselib/stdnse.lua +++ b/nselib/stdnse.lua @@ -1,7 +1,8 @@ --- Standard Nmap Scripting Engine functions. --- \n\n --- This module contains various handy functions which are too small to justify modules of their own. ---@copyright See nmaps COPYING for licence +-- +-- This module contains various handy functions that are too small to justify +-- modules of their own. +-- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html local assert = assert; local tonumber = tonumber; @@ -18,14 +19,15 @@ module(... or "stdnse"); --- Prints a formatted debug message if the current verbosity level is greater -- than or equal to a given level. --- \n\n --- This is a convenience wrapper around nmap.print_debug_unformatted. The first --- optional numeric argument, verbosity, is used as the necessary debug level --- to print the message (it defaults to 1 if omitted). All remaining arguments --- are processed with Lua's string.format() function. ---@param level Optional verbosity level. ---@param fmt Format string according to string.format specifiers. ---@param ... Arguments to format. +-- +-- This is a convenience wrapper around +-- nmap.print_debug_unformatted(). The first optional numeric +-- argument, verbosity, is used as the verbosity level necessary to print the +-- message (it defaults to 1 if omitted). All remaining arguments are processed +-- with Lua's string.format() function. +-- @param level Optional verbosity level. +-- @param fmt Format string according to string.format specifiers. +-- @param ... Arguments to format. print_debug = function(level, fmt, ...) local verbosity = tonumber(level); if verbosity then @@ -35,32 +37,34 @@ print_debug = function(level, fmt, ...) end end ---- Join a list of string with a separator string. --- \n\n --- Example: strjoin(", ", {"Anna", "Bob", "Charlie", "Dolores"}) +--- Join a list of strings with a separator string. +-- +-- This is Lua's table.concat() function with the parameters +-- swapped for coherence. +-- @usage +-- strjoin(", ", {"Anna", "Bob", "Charlie", "Dolores"}) -- --> "Anna, Bob, Charlie, Dolores" --- \n\n --- Basically this is Lua's table.concat() function with the parameters swapped --- for coherence. ---@param delimiter String to delimit each element of the list. ---@param list Array of strings to concatenate. ---@return Concatenated string. +-- @param delimiter String to delimit each element of the list. +-- @param list Array of strings to concatenate. +-- @return Concatenated string. function strjoin(delimiter, list) return concat(list, delimiter); end --- Split a string at a given delimiter, which may be a pattern. --- Example: strsplit(",%s*", "Anna, Bob, Charlie, Dolores") ---@param delimiter String which delimits the split strings. ---@param text String to split. ---@return List of substrings without the delimiter. -function strsplit(delimiter, text) +-- @usage +-- strsplit(",%s*", "Anna, Bob, Charlie, Dolores") +-- --> { "Anna", "Bob", "Charlie", "Dolores" } +-- @param pattern Pattern that separates the desired strings. +-- @param text String to split. +-- @return Array of substrings without the separating pattern. +function strsplit(pattern, text) local list, pos = {}, 1; - assert(delimiter ~= "", "delimiter matches empty string!"); + assert(pattern ~= "", "delimiter matches empty string!"); while true do - local first, last, match = text:find(delimiter, pos); + local first, last, match = text:find(pattern, pos); if first then -- found? list[#list+1] = text:sub(pos, first-1); pos = last+1; @@ -74,14 +78,15 @@ end --- Return a wrapper closure around a socket that buffers socket reads into -- chunks separated by a pattern. --- \n\n --- This function operates on a socket attempting to read data. It separates --- the data by sep and, for each invocation, returns a piece of the --- separated data. Typically this is used to iterate over the lines of --- data received from a socket (sep = "\r?\n"). The returned string does --- not include the separator. It will return the final data even if it is --- not followed by the separator. Once an error or EOF is reached, it --- returns nil, msg. msg is what is returned by nmap.receive_lines(). +-- +-- This function operates on a socket attempting to read data. It separates the +-- data by sep and, for each invocation, returns a piece of the +-- separated data. Typically this is used to iterate over the lines of data +-- received from a socket (sep = "\r?\n"). The returned string +-- does not include the separator. It will return the final data even if it is +-- not followed by the separator. Once an error or EOF is reached, it returns +-- nil, msg. msg is what is returned by +-- nmap.receive_lines(). -- @param socket Socket for the buffer. -- @param sep Separator for the buffered reads. -- @return Data from socket reads. @@ -143,41 +148,42 @@ do f = "1111" }; ---- Converts the given number, n, to a string in a binary number format (10 --- becomes "1010"). ---@param n Number to convert. ---@return String in binary format. +--- Converts the given number, n, to a string in a binary number format (12 +-- becomes "1100"). +-- @param n Number to convert. +-- @return String in binary format. function tobinary(n) assert(tonumber(n), "number expected"); return (("%x"):format(n):gsub("%w", t):gsub("^0*", "")); end end ---- Converts the given number, n, to a string in an octal number format (10 --- becomes "12"). ---@param n Number to convert. ---@return String in octal format. +--- Converts the given number, n, to a string in an octal number format (12 +-- becomes "14"). +-- @param n Number to convert. +-- @return String in octal format. function tooctal(n) assert(tonumber(n), "number expected"); return ("%o"):format(n) end ---- Encode a string or number in hexadecimal (10 becomes "a", "A" becomes --- "41"). --- \n\n --- The returned string may be chunked into groups of a given size, separated --- by a given string. --- \n\n --- Examples:\n --- stdnse.tohex("abc") => "616263"\n --- stdnse.tohex("abc",{separator=":"}) => "61:62:63"\n --- stdnse.tohex("abc",{separator=":",group=4}) => "61:6263"\n --- stdnse.tohex(123456) => "1e240"\n --- stdnse.tohex(123456,{separator=":"}) => "1:e2:40"\n --- stdnse.tohex(123456,{separator=":",group=4}) => "1:e240"\n ---@param s string or number to be encoded. ---@param options table specifiying formatting options. ---@return hexadecimal encoded string. +--- Encode a string or number in hexadecimal (12 becomes "c", "AB" becomes +-- "4142"). +-- +-- An optional second argument is a table with formatting options. The possible +-- fields in this table are +-- * separator: A string to use to separate groups of digits. +-- * group: The size of each group of digits between separators. Defaults to 2, but has no effect if separator is not also given. +-- @usage +-- stdnse.tohex("abc") --> "616263" +-- stdnse.tohex("abc", {separator = ":"}) --> "61:62:63" +-- stdnse.tohex("abc", {separator = ":", group = 4}) --> "61:6263" +-- stdnse.tohex(123456) --> "1e240" +-- stdnse.tohex(123456, {separator = ":"}) --> "1:e2:40" +-- stdnse.tohex(123456, {separator = ":", group = 4}) --> "1:e240" +-- @param s String or number to be encoded. +-- @param options Table specifiying formatting options. +-- @return String in hexadecimal format. function tohex( s, options ) options = options or EMPTY local separator = options.separator