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 */

100
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,34 +40,36 @@ 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)
* "repository" with a string value of a URL to a repository (optional)
The passed-in Lua table entries need to be keyed/indexed by the following:
Not all of the above key entries need to be in the table. The 'version'
entry is required, however. The others are not currently used for anything, but
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.
* "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)
* "repository" with a string value of a URL to a repository (optional)
Example:
Not all of the above key entries need to be in the table. The 'version'
entry is required, however. The others are not currently used for anything, but
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.
[source,lua]
----
local my_info = {
version = "1.0.1",
author = "Jane Doe",
repository = "https://github.com/octocat/Spoon-Knife"
}
===== Example
set_plugin_info(my_info)
----
[source,lua]
----
local my_info = {
version = "1.0.1",
author = "Jane Doe",
repository = "https://github.com/octocat/Spoon-Knife"
}
@since 1.99.8
*/
set_plugin_info(my_info)
----
@since 1.99.8
*/
#define WSLUA_ARG_set_plugin_info_TABLE 1 /* The Lua table of information. */
if ( lua_istable(L,WSLUA_ARG_set_plugin_info_TABLE) ) {
@ -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;
@ -255,9 +287,9 @@ 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 */
/* Register a function to handle a `-z` option */
#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;