osmocom
/
wireshark
11
0
Fork 1
Code Issues Pull Requests Projects Releases Wiki Activity

wslua: Update the Dir and Utils docs. 

Add content from https://wiki.wireshark.org/LuaAPI/Utils. Update as
needed.

Change-Id: I2bf04d053a1edd5e05779c5a41e5ae0fbcb71b54
Reviewed-on: https://code.wireshark.org/review/36638
Reviewed-by: Gerald Combs <gerald@wireshark.org>
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Anders Broman <a.broman58@gmail.com>
This commit is contained in:
Gerald Combs 2020-03-30 15:04:44 -07:00 committed by Anders Broman
parent 3069129fe5
commit 99798d2c1c
2 changed files with 97 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
epan/wslua/wslua_dir.c
View File

@ -23,9 +23,9 @@ WSLUA_CONSTRUCTOR Dir_make(lua_State* L) {
/* Creates a directory.
The created directory is set for permission mode 0755 (octal), meaning it is
read+write+execute by owner, but only read+execute by group and others.
read+write+execute by owner, but only read+execute by group members and others.
IF the directory was created successfully, a boolean `true` is returned.
If the directory was created successfully, a boolean `true` is returned.
If the directory cannot be made because it already exists, `false` is returned.
If the directory cannot be made because an error occurred, `nil` is returned.
@ -48,7 +48,7 @@ WSLUA_CONSTRUCTOR Dir_make(lua_State* L) {
lua_pushboolean(L, 0);
}
WSLUA_RETURN(1); /* Boolean `true` on success, `false` if already exists, `nil` on error. */
WSLUA_RETURN(1); /* Boolean `true` on success, `false` if the directory already exists, `nil` on error. */
}
WSLUA_CONSTRUCTOR Dir_exists(lua_State* L) {
@ -75,7 +75,7 @@ WSLUA_CONSTRUCTOR Dir_exists(lua_State* L) {
}
}
WSLUA_RETURN(1); /* Boolean `true` if the directory exists, `false` if it's a file, `nil` on error/not-exist. */
WSLUA_RETURN(1); /* Boolean `true` if the directory exists, `false` if it's a file, `nil` on error or not-exist. */
}
WSLUA_CONSTRUCTOR Dir_remove(lua_State* L) {
@ -170,11 +170,16 @@ WSLUA_CONSTRUCTOR Dir_remove_all(lua_State* L) {
}
WSLUA_CONSTRUCTOR Dir_open(lua_State* L) {
/* Opens a directory and returns a `Dir` object representing the files in the directory.
/* Opens a directory and returns a <<lua_class_Dir,`Dir`>> object representing the files in the directory.
==== Example
[source,lua]
----
for filename in Dir.open(path) do ... end
-- Print the contents of a directory
for filename in Dir.open('/path/to/dir') do
print(filename)
end
----
*/
#define WSLUA_ARG_Dir_open_PATHNAME 1 /* The pathname of the directory. */
@ -211,11 +216,23 @@ WSLUA_CONSTRUCTOR Dir_open(lua_State* L) {
dir->ext = g_strdup(extension);
pushDir(L,dir);
WSLUA_RETURN(1); /* the `Dir` object. */
WSLUA_RETURN(1); /* The <<lua_class_Dir,`Dir`>> object. */
}
WSLUA_METAMETHOD Dir__call(lua_State* L) {
/* At every invocation will return one file (nil when done). */
/*
Gets the next file or subdirectory within the directory, or `nil` when done.
==== Example
[source,lua]
----
-- Open a directory and print the name of the first file or subdirectory
local dir = Dir.open('/path/to/dir')
local first = dir()
print(tostring(file))
----
*/
Dir dir = checkDir(L,1);
const gchar* file;
@ -255,7 +272,7 @@ WSLUA_METAMETHOD Dir__call(lua_State* L) {
}
WSLUA_METHOD Dir_close(lua_State* L) {
/* Closes the directory. */
/* Closes the directory. Called automatically during garbage collection of a <<lua_class_Dir,`Dir`>> object. */
Dir dir = checkDir(L,1);
if (dir->dir) {
@ -267,7 +284,7 @@ WSLUA_METHOD Dir_close(lua_State* L) {
}
WSLUA_CONSTRUCTOR Dir_personal_config_path(lua_State* L) {
/* Gets the personal configuration directory path, with filename if supplied.
/* Gets the https://www.wireshark.org/docs/wsug_html_chunked/ChAppFilesConfigurationSection.html[personal configuration] directory path, with filename if supplied.
@since 1.11.3
*/
@ -281,7 +298,7 @@ WSLUA_CONSTRUCTOR Dir_personal_config_path(lua_State* L) {
}
WSLUA_CONSTRUCTOR Dir_global_config_path(lua_State* L) {
/* Gets the global configuration directory path, with filename if supplied.
/* Gets the https://www.wireshark.org/docs/wsug_html_chunked/ChAppFilesConfigurationSection.html[global configuration] directory path, with filename if supplied.
@since 1.11.3
*/
@ -292,7 +309,7 @@ WSLUA_CONSTRUCTOR Dir_global_config_path(lua_State* L) {
filename = get_datafile_path(fname);
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_CONSTRUCTOR Dir_personal_plugins_path(lua_State* L) {
@ -301,7 +318,7 @@ WSLUA_CONSTRUCTOR Dir_personal_plugins_path(lua_State* L) {
@since 1.11.3
*/
lua_pushstring(L, get_plugins_pers_dir());
WSLUA_RETURN(1); /* The pathname for the personal plugins directory. */
WSLUA_RETURN(1); /* The pathname of the https://www.wireshark.org/docs/wsug_html_chunked/ChPluginFolders.html[personal plugins] directory. */
}
WSLUA_CONSTRUCTOR Dir_global_plugins_path(lua_State* L) {
@ -310,7 +327,7 @@ WSLUA_CONSTRUCTOR Dir_global_plugins_path(lua_State* L) {
@since 1.11.3
*/
lua_pushstring(L, get_plugins_dir());
WSLUA_RETURN(1); /* The pathname for the global plugins directory. */
WSLUA_RETURN(1); /* The pathname of the https://www.wireshark.org/docs/wsug_html_chunked/ChPluginFolders.html[global plugins] directory. */
}
/* Gets registered as metamethod automatically by WSLUA_REGISTER_CLASS/META */

58
epan/wslua/wslua_util.c
View File

@ -19,10 +19,10 @@
#include <epan/stat_tap_ui.h>
WSLUA_FUNCTION wslua_get_version(lua_State* L) { /* Gets a string of the Wireshark version. */
WSLUA_FUNCTION wslua_get_version(lua_State* L) { /* Gets the Wireshark version as a string. */
const gchar* str = VERSION;
lua_pushstring(L,str);
WSLUA_RETURN(1); /* version string */
WSLUA_RETURN(1); /* The version string, e.g. "3.2.5". */
}
@ -40,9 +40,11 @@ void clear_current_plugin_version(void) {
}
WSLUA_FUNCTION wslua_set_plugin_info(lua_State* L) {
/* Set a Lua table with meta-data about the plugin, such as version.
/*
Set a Lua table with meta-data about the plugin, such as version.
The passed-in Lua table entries need to be keyed/indexed by the following:
* "version" with a string value identifying the plugin version (required)
* "description" with a string value describing the plugin (optional)
* "author" with a string value of the author's name(s) (optional)
@ -53,7 +55,7 @@ WSLUA_FUNCTION wslua_set_plugin_info(lua_State* L) {
might be in the future and thus using them might be useful. Table entries keyed
by other strings are ignored, and do not cause an error.
Example:
===== Example
[source,lua]
----
@ -106,7 +108,7 @@ 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. */
WSLUA_FUNCTION wslua_format_time(lua_State* LS) { /* Formats a relative timestamp in a human readable time. */
#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;
@ -174,9 +176,31 @@ 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. */
/*
Loads a Lua file and compiles it into a Lua chunk, similar to the standard
https://www.lua.org/manual/5.1/manual.html#pdf-loadfile[loadfile]
but searches additional directories.
The search order is the current directory, followed by the user's
https://www.wireshark.org/docs/wsug_html_chunked/ChAppFilesConfigurationSection.html[personal configuration]
directory, and finally the
https://www.wireshark.org/docs/wsug_html_chunked/ChAppFilesConfigurationSection.html[global configuration]
directory.
===== Example
[source,lua]
----
-- Assume foo.lua contains definition for foo(a,b). Load the chunk
-- from the file and execute it to add foo(a,b) to the global table.
-- These two lines are effectively the same as dofile('foo.lua').
local loaded_chunk = assert(loadfile('foo.lua'))
loaded_chunk()
-- ok to call foo at this point
foo(1,2)
----
*/
#define WSLUA_ARG_loadfile_FILENAME 1 /* Name of the file to be loaded. If the file does not exist in the current directory, the user and system directories are searched. */
const char *given_fname = luaL_checkstring(L, WSLUA_ARG_loadfile_FILENAME);
char* filename;
@ -199,9 +223,17 @@ 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. */
/*
Loads a Lua file and executes it as a Lua chunk, similar to the standard
https://www.lua.org/manual/5.1/manual.html#pdf-dofile[dofile]
but searches additional directories.
The search order is the current directory, followed by the user's
https://www.wireshark.org/docs/wsug_html_chunked/ChAppFilesConfigurationSection.html[personal configuration]
directory, and finally the
https://www.wireshark.org/docs/wsug_html_chunked/ChAppFilesConfigurationSection.html[global configuration]
directory.
*/
#define WSLUA_ARG_dofile_FILENAME 1 /* Name of the file to be run. If the file does not exist in the current directory, the user and system directories are searched. */
const char *given_fname = luaL_checkstring(L, WSLUA_ARG_dofile_FILENAME);
char* filename = wslua_get_actual_filename(given_fname);
int n;
@ -256,8 +288,8 @@ static void statcmd_init(const char *opt_arg, void* userdata) {
WSLUA_FUNCTION wslua_register_stat_cmd_arg(lua_State* L) {
/* Register a function to handle a `-z` option */
#define WSLUA_ARG_register_stat_cmd_arg_ARGUMENT 1 /* Argument */
#define WSLUA_OPTARG_register_stat_cmd_arg_ACTION 2 /* Action */
#define WSLUA_ARG_register_stat_cmd_arg_ARGUMENT 1 /* The name of the option argument. */
#define WSLUA_OPTARG_register_stat_cmd_arg_ACTION 2 /* The function to be called when the command is invoked. */
const char* arg = luaL_checkstring(L,WSLUA_ARG_register_stat_cmd_arg_ARGUMENT);
statcmd_t* sc = (statcmd_t *)g_malloc0(sizeof(statcmd_t)); /* XXX leaked */
stat_tap_ui ui_info;