From de441241ef16262fa8ba1c5fbd77509a1ee86c67 Mon Sep 17 00:00:00 2001 From: Hadriel Kaplan Date: Sun, 23 Mar 2014 11:01:12 -0400 Subject: Enhance Lua API doc generator and add more API info This enhances the Lua API doc generator Perl script to handle meta-information in description comments, such as bold, italics, raw code, version info, etc. The supported markup and codes are documented in make-wsluarm.pl. It's not beautiful Perl code (I don't know Perl), and I'd rather do it using Lua, but I think keeping it Perl makes more sense in the long run. Change-Id: I477b3ebe770075dcea9ec52708e2d6fb5758d2f4 Reviewed-on: https://code.wireshark.org/review/802 Reviewed-by: Hadriel Kaplan Reviewed-by: Anders Broman --- epan/wslua/wslua_util.c | 159 ++++++++---------------------------------------- 1 file changed, 27 insertions(+), 132 deletions(-) (limited to 'epan/wslua/wslua_util.c') diff --git a/epan/wslua/wslua_util.c b/epan/wslua/wslua_util.c index f66310bf7c..c9098aa980 100644 --- a/epan/wslua/wslua_util.c +++ b/epan/wslua/wslua_util.c @@ -31,13 +31,13 @@ #include -WSLUA_FUNCTION wslua_get_version(lua_State* L) { /* Get Wireshark version */ +WSLUA_FUNCTION wslua_get_version(lua_State* L) { /* Gets a string of the Wireshark version. */ const gchar* str = VERSION; lua_pushstring(L,str); WSLUA_RETURN(1); /* version string */ } -WSLUA_FUNCTION wslua_format_date(lua_State* LS) { /* Formats an absolute timestamp into a human readable date */ +WSLUA_FUNCTION wslua_format_date(lua_State* LS) { /* Formats an absolute timestamp into a human readable date. */ #define WSLUA_ARG_format_date_TIMESTAMP 1 /* A timestamp value to convert. */ lua_Number timestamp = luaL_checknumber(LS,WSLUA_ARG_format_date_TIMESTAMP); nstime_t then; @@ -51,8 +51,8 @@ WSLUA_FUNCTION wslua_format_date(lua_State* LS) { /* Formats an absolute timesta WSLUA_RETURN(1); /* A string with the formated date */ } -WSLUA_FUNCTION wslua_format_time(lua_State* LS) { /* Formats a relative timestamp in a human readable form */ -#define WSLUA_ARG_format_time_TIMESTAMP 1 /* A timestamp value to convert */ +WSLUA_FUNCTION wslua_format_time(lua_State* LS) { /* Formats a relative timestamp in a human readable form. */ +#define WSLUA_ARG_format_time_TIMESTAMP 1 /* A timestamp value to convert. */ lua_Number timestamp = luaL_checknumber(LS,WSLUA_ARG_format_time_TIMESTAMP); nstime_t then; gchar* str; @@ -65,8 +65,8 @@ WSLUA_FUNCTION wslua_format_time(lua_State* LS) { /* Formats a relative timestam WSLUA_RETURN(1); /* A string with the formated time */ } -WSLUA_FUNCTION wslua_report_failure(lua_State* LS) { /* Reports a failure to the user */ -#define WSLUA_ARG_report_failure_TEXT 1 /* Message */ +WSLUA_FUNCTION wslua_report_failure(lua_State* LS) { /* Reports a failure to the user. */ +#define WSLUA_ARG_report_failure_TEXT 1 /* Message text to report. */ const gchar* s = luaL_checkstring(LS,WSLUA_ARG_report_failure_TEXT); report_failure("%s",s); return 0; @@ -99,27 +99,27 @@ static int wslua_log(lua_State* L, GLogLevelFlags log_level) { return 0; } -WSLUA_FUNCTION wslua_critical( lua_State* L ) { /* Will add a log entry with critical severity*/ +WSLUA_FUNCTION wslua_critical( lua_State* L ) { /* Will add a log entry with critical severity. */ /* WSLUA_MOREARGS critical objects to be printed */ wslua_log(L,G_LOG_LEVEL_CRITICAL); return 0; } -WSLUA_FUNCTION wslua_warn( lua_State* L ) { /* Will add a log entry with warn severity */ +WSLUA_FUNCTION wslua_warn( lua_State* L ) { /* Will add a log entry with warn severity. */ /* WSLUA_MOREARGS warn objects to be printed */ wslua_log(L,G_LOG_LEVEL_WARNING); return 0; } -WSLUA_FUNCTION wslua_message( lua_State* L ) { /* Will add a log entry with message severity */ +WSLUA_FUNCTION wslua_message( lua_State* L ) { /* Will add a log entry with message severity. */ /* WSLUA_MOREARGS message objects to be printed */ wslua_log(L,G_LOG_LEVEL_MESSAGE); return 0; } -WSLUA_FUNCTION wslua_info( lua_State* L ) { /* Will add a log entry with info severity */ +WSLUA_FUNCTION wslua_info( lua_State* L ) { /* Will add a log entry with info severity. */ /* WSLUA_MOREARGS info objects to be printed */ wslua_log(L,G_LOG_LEVEL_INFO); return 0; } -WSLUA_FUNCTION wslua_debug( lua_State* L ) { /* Will add a log entry with debug severity */ +WSLUA_FUNCTION wslua_debug( lua_State* L ) { /* Will add a log entry with debug severity. */ /* WSLUA_MOREARGS debug objects to be printed */ wslua_log(L,G_LOG_LEVEL_DEBUG); return 0; @@ -177,8 +177,8 @@ static char* wslua_get_actual_filename(const char* fname) { WSLUA_FUNCTION wslua_loadfile(lua_State* L) { /* Lua's loadfile() has been modified so that if a file does not exist - in the current directory it will look for it in wireshark's user and system directories */ -#define WSLUA_ARG_loadfile_FILENAME 1 /* Name of the file to be loaded */ + in the current directory it will look for it in wireshark's user and system directories. */ +#define WSLUA_ARG_loadfile_FILENAME 1 /* Name of the file to be loaded. */ const char *given_fname = luaL_checkstring(L, WSLUA_ARG_loadfile_FILENAME); char* filename; @@ -202,8 +202,8 @@ WSLUA_FUNCTION wslua_loadfile(lua_State* L) { WSLUA_FUNCTION wslua_dofile(lua_State* L) { /* Lua's dofile() has been modified so that if a file does not exist - in the current directory it will look for it in wireshark's user and system directories */ -#define WSLUA_ARG_dofile_FILENAME 1 /* Name of the file to be run */ + in the current directory it will look for it in wireshark's user and system directories. */ +#define WSLUA_ARG_dofile_FILENAME 1 /* Name of the file to be run. */ const char *given_fname = luaL_checkstring(L, WSLUA_ARG_dofile_FILENAME); char* filename; int n; @@ -229,13 +229,13 @@ WSLUA_FUNCTION wslua_dofile(lua_State* L) { WSLUA_FUNCTION wslua_persconffile_path(lua_State* L) { -#define WSLUA_OPTARG_persconffile_path_FILENAME 1 /* A filename */ +#define WSLUA_OPTARG_persconffile_path_FILENAME 1 /* A filename. */ const char *fname = luaL_optstring(L, WSLUA_OPTARG_persconffile_path_FILENAME,""); char* filename = get_persconffile_path(fname,FALSE); lua_pushstring(L,filename); g_free(filename); - WSLUA_RETURN(1); /* The full pathname for a file in the personal configuration directory */ + WSLUA_RETURN(1); /* The full pathname for a file in the personal configuration directory. */ } WSLUA_FUNCTION wslua_datafile_path(lua_State* L) { @@ -253,16 +253,19 @@ WSLUA_FUNCTION wslua_datafile_path(lua_State* L) { lua_pushstring(L,filename); g_free(filename); - WSLUA_RETURN(1); /* The full pathname for a file in wireshark's configuration directory */ + WSLUA_RETURN(1); /* The full pathname for a file in wireshark's configuration directory. */ } WSLUA_CLASS_DEFINE(Dir,FAIL_ON_NULL("Dir"),NOP); /* A Directory */ WSLUA_CONSTRUCTOR Dir_open(lua_State* L) { - /* Usage: for filename in Dir.open(path) do ... end */ -#define WSLUA_ARG_Dir_open_PATHNAME 1 /* The pathname of the directory */ -#define WSLUA_OPTARG_Dir_open_EXTENSION 2 /* If given, only file with this extension will be returned */ + /* Opens a directory and returns a `Dir` object representing the files in the directory. + + @code for filename in Dir.open(path) do ... end @endcode + */ +#define WSLUA_ARG_Dir_open_PATHNAME 1 /* The pathname of the directory. */ +#define WSLUA_OPTARG_Dir_open_EXTENSION 2 /* If given, only files with this extension will be returned. */ const char* dirname = luaL_checkstring(L,WSLUA_ARG_Dir_open_PATHNAME); const char* extension = luaL_optstring(L,WSLUA_OPTARG_Dir_open_EXTENSION,NULL); @@ -302,11 +305,11 @@ WSLUA_CONSTRUCTOR Dir_open(lua_State* L) { } pushDir(L,dir); - WSLUA_RETURN(1); /* the Dir object */ + WSLUA_RETURN(1); /* the `Dir` object. */ } WSLUA_METAMETHOD Dir__call(lua_State* L) { - /* At every invocation will return one file (nil when done) */ + /* At every invocation will return one file (nil when done). */ Dir dir = checkDir(L,1); const gchar* file; @@ -346,7 +349,7 @@ WSLUA_METAMETHOD Dir__call(lua_State* L) { } WSLUA_METHOD Dir_close(lua_State* L) { - /* Closes the directory */ + /* Closes the directory. */ Dir dir = checkDir(L,1); if (dir->dir) { @@ -446,114 +449,6 @@ WSLUA_FUNCTION wslua_register_stat_cmd_arg(lua_State* L) { return 0; } -/* Pushes a hex string of the binary data argument. */ -int wslua_bin2hex(lua_State* L, const guint8* data, const guint len, const gboolean lowercase, const gchar* sep) { - luaL_Buffer b; - guint i = 0; - static const char byte_to_str_upper[256][3] = { - "00","01","02","03","04","05","06","07","08","09","0A","0B","0C","0D","0E","0F", - "10","11","12","13","14","15","16","17","18","19","1A","1B","1C","1D","1E","1F", - "20","21","22","23","24","25","26","27","28","29","2A","2B","2C","2D","2E","2F", - "30","31","32","33","34","35","36","37","38","39","3A","3B","3C","3D","3E","3F", - "40","41","42","43","44","45","46","47","48","49","4A","4B","4C","4D","4E","4F", - "50","51","52","53","54","55","56","57","58","59","5A","5B","5C","5D","5E","5F", - "60","61","62","63","64","65","66","67","68","69","6A","6B","6C","6D","6E","6F", - "70","71","72","73","74","75","76","77","78","79","7A","7B","7C","7D","7E","7F", - "80","81","82","83","84","85","86","87","88","89","8A","8B","8C","8D","8E","8F", - "90","91","92","93","94","95","96","97","98","99","9A","9B","9C","9D","9E","9F", - "A0","A1","A2","A3","A4","A5","A6","A7","A8","A9","AA","AB","AC","AD","AE","AF", - "B0","B1","B2","B3","B4","B5","B6","B7","B8","B9","BA","BB","BC","BD","BE","BF", - "C0","C1","C2","C3","C4","C5","C6","C7","C8","C9","CA","CB","CC","CD","CE","CF", - "D0","D1","D2","D3","D4","D5","D6","D7","D8","D9","DA","DB","DC","DD","DE","DF", - "E0","E1","E2","E3","E4","E5","E6","E7","E8","E9","EA","EB","EC","ED","EE","EF", - "F0","F1","F2","F3","F4","F5","F6","F7","F8","F9","FA","FB","FC","FD","FE","FF" - }; - static const char byte_to_str_lower[256][3] = { - "00","01","02","03","04","05","06","07","08","09","0a","0b","0c","0d","0e","0f", - "10","11","12","13","14","15","16","17","18","19","1a","1b","1c","1d","1e","1f", - "20","21","22","23","24","25","26","27","28","29","2a","2b","2c","2d","2e","2f", - "30","31","32","33","34","35","36","37","38","39","3a","3b","3c","3d","3e","3f", - "40","41","42","43","44","45","46","47","48","49","4a","4b","4c","4d","4e","4f", - "50","51","52","53","54","55","56","57","58","59","5a","5b","5c","5d","5e","5f", - "60","61","62","63","64","65","66","67","68","69","6a","6b","6c","6d","6e","6f", - "70","71","72","73","74","75","76","77","78","79","7a","7b","7c","7d","7e","7f", - "80","81","82","83","84","85","86","87","88","89","8a","8b","8c","8d","8e","8f", - "90","91","92","93","94","95","96","97","98","99","9a","9b","9c","9d","9e","9f", - "a0","a1","a2","a3","a4","a5","a6","a7","a8","a9","aa","ab","ac","ad","ae","af", - "b0","b1","b2","b3","b4","b5","b6","b7","b8","b9","ba","bb","bc","bd","be","bf", - "c0","c1","c2","c3","c4","c5","c6","c7","c8","c9","ca","cb","cc","cd","ce","cf", - "d0","d1","d2","d3","d4","d5","d6","d7","d8","d9","da","db","dc","dd","de","df", - "e0","e1","e2","e3","e4","e5","e6","e7","e8","e9","ea","eb","ec","ed","ee","ef", - "f0","f1","f2","f3","f4","f5","f6","f7","f8","f9","fa","fb","fc","fd","fe","ff" - }; - const char (*byte_to_str)[3] = byte_to_str_upper; - const guint last = len - 1; - - if (lowercase) byte_to_str = byte_to_str_lower; - - luaL_buffinit(L, &b); - - for (i = 0; i < len; i++) { - luaL_addlstring(&b, &(*byte_to_str[data[i]]), 2); - if (sep && i < last) luaL_addstring(&b, sep); - } - - luaL_pushresult(&b); - - return 1; -} - -/* Pushes a binary string of the hex-ascii data argument. */ -int wslua_hex2bin(lua_State* L, const char* data, const guint len, const gchar* sep) { - luaL_Buffer b; - guint i = 0; - guint seplen = 0; - char c, d; - - static const char str_to_nibble[256] = { - -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, - -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, - -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, - 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,-1,-1,-1,-1,-1,-1, - -1,10,11,12,13,14,15,-1,-1,-1,-1,-1,-1,-1,-1,-1, - -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, - -1,10,11,12,13,14,15,-1,-1,-1,-1,-1,-1,-1,-1,-1, - -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, - -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, - -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, - -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, - -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, - -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, - -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, - -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, - -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1 - }; - - if (sep) seplen = (guint) strlen(sep); - - luaL_buffinit(L, &b); - - for (i = 0; i < len;) { - c = str_to_nibble[(int)data[i]]; - if (c < 0) { - if (seplen && strncmp(&data[i], sep, seplen) == 0) { - i += seplen; - continue; - } else { - break; - } - } - d = str_to_nibble[(int)data[++i]]; - if (d < 0) break; - luaL_addchar(&b, (c * 16) + d); - i++; - } - - luaL_pushresult(&b); - - return 1; -} - /* * Editor modelines - http://www.wireshark.org/tools/modelines.html * -- cgit v1.2.3