wslua: fix errors in documentation, add notational conventions

Improve example with better formatting, clarification comments and more
common variable names.

Extend make-wsluarm.pl to support arguments containing underscores.
Fixes the description of dissect_tcp_pdus.

Change TvbRange.tvb(tvb) into tvbrange:tvb() and ByteArray.tvb(name)
into bytearray:tvb(name), these are really instance methods.

Change-Id: I1e20ef46195dc6c06f9ac790d3432db283d21a5e
Reviewed-on: https://code.wireshark.org/review/18226
Reviewed-by: Anders Broman <a.broman58@gmail.com>

5 files changed, 54 insertions, 36 deletions

diff --git a/docbook/make-wsluarm.pl b/docbook/make-wsluarm.pl
index 16bc9135c0..ec297e276e 100755
--- a/docbook/make-wsluarm.pl
+++ b/docbook/make-wsluarm.pl
@@ -357,6 +357,9 @@ my $out_extension = "asciidoc";
 # XXX: support \" within ""
 my $QUOTED_RE = "\042\050\133^\042\135*\051\042";
 
+# group 1: whole trailing comment (possibly empty), e.g. " /* foo */"
+# group 2: any leading whitespace. XXX why is this not removed using (?:...)
+# group 3: actual comment text, e.g. " foo ".
 my $TRAILING_COMMENT_RE = '((\s*|[\n\r]*)/\*(.*?)\*/)?';
 my $IN_COMMENT_RE       = '[\s\r\n]*((.*?)\*/)?';
 
@@ -460,30 +463,26 @@ sub {
 	push @{${$class}{methods}}, $function;
 } ],
 
-[ '#define WSLUA_(OPT)?ARG_([A-Za-z0-9_]+)_([A-Z0-9]+)\s+\d+' . $TRAILING_COMMENT_RE,
+# Splits "WSLUA_OPTARG_ProtoField_int8_NAME /* food */" into
+# "OPT" (1), "ProtoField_int8" (2), "NAME" (3), ..., ..., " food " (6)
+# Handles functions like "loadfile(filename)" too.
+[ '#define WSLUA_(OPT)?ARG_((?:[A-Za-z0-9]+_)?[a-z0-9_]+)_([A-Z0-9_]+)\s+\d+' . $TRAILING_COMMENT_RE,
 sub {
-	deb ">a=$1=$2=$3=$4=$5=$6=$7=\n";
+	deb ">a=$1=$2=$3=$4=$5=$6=\n";
 	my $name = $1 eq 'OPT' ? "[$3]" : $3;
 	push @{${$function}{arglist}} , $name;
 	${${$function}{args}}{$name} = {descr=>parse_function_arg_desc($6),}
 } ],
 
-[ '\057\052\s*WSLUA_(OPT)?ARG_([A-Za-z0-9_]+)_([A-Z0-9]+)\s*(.*?)\052\057',
+# same as above, except that there is no macro but a (multi-line) comment.
+[ '\057\052\s*WSLUA_(OPT)?ARG_((?:[A-Za-z0-9]+_)?[a-z0-9_]+)_([A-Z0-9_]+)\s*(.*?)\052\057',
 sub {
-	deb ">a=$1=$2=$3=$4=$5=$6=$7=\n";
+	deb ">a=$1=$2=$3=$4\n";
 	my $name = $1 eq 'OPT' ? "[$3]" : $3;
 	push @{${$function}{arglist}} , $name;
 	${${$function}{args}}{$name} = {descr=>parse_function_arg_desc($4),}
 } ],
 
-[ '#define WSLUA_(OPT)?ARG_([A-Za-z0-9]+)_([a-z_]+)_([A-Z0-9]+)\s+\d+' . $TRAILING_COMMENT_RE,
-sub {
-	deb ">ca=$1=$2=$3=$4=$5=$6=$7=\n";
-	my $name = $1 eq 'OPT' ? "[$4]" : $4;
-	push @{${$function}{arglist}} , $name;
-	${${$function}{args}}{$name} = {descr=>parse_function_arg_desc($7),optional => $1 eq '' ? 1 : 0 }
-} ],
-
 [ '/\052\s+WSLUA_ATTRIBUTE\s+([A-Za-z0-9]+)_([a-z_]+)\s+([A-Z]*)\s*(.*?)\052/',
 sub {
 	deb ">at=$1=$2=$3=$4=$5=$6=$7=\n";
diff --git a/docbook/wsluarm.asciidoc b/docbook/wsluarm.asciidoc
index 2142092c55..af8708b5d4 100644
--- a/docbook/wsluarm.asciidoc
+++ b/docbook/wsluarm.asciidoc
@@ -43,7 +43,7 @@ initialized and before reading any file.
 
 [source,lua]
 ----
-local p_multi = Proto("multi","MultiProto");
+local p_multi = Proto("multi", "MultiProto");
 
 local vs_protos = {
         [2] = "mtp2",
@@ -55,9 +55,9 @@ local vs_protos = {
         [8] = "nbap"
 }
 
-local f_proto = ProtoField.uint8("multi.protocol","Protocol",base.DEC,vs_protos)
-local f_dir = ProtoField.uint8("multi.direction","Direction",base.DEC,{ [1] = "incoming", [0] = "outgoing"})
-local f_text = ProtoField.string("multi.text","Text")
+local f_proto = ProtoField.uint8("multi.protocol", "Protocol", base.DEC, vs_protos)
+local f_dir = ProtoField.uint8("multi.direction", "Direction", base.DEC, { [1] = "incoming", [0] = "outgoing"})
+local f_text = ProtoField.string("multi.text", "Text")
 
 p_multi.fields = { f_proto, f_dir, f_text }
 
@@ -76,23 +76,26 @@ local protos = {
         [11] = DissectorTable.get("ip.proto"):get_dissector(132), -- sctp
 }
 
-function p_multi.dissector(buf,pkt,root)
+function p_multi.dissector(buf, pkt, tree)
 
-        local t = root:add(p_multi,buf(0,2))
-        t:add(f_proto,buf(0,1))
-        t:add(f_dir,buf(1,1))
+        local subtree = tree:add(p_multi, buf(0,2))
+        subtree:add(f_proto, buf(0,1))
+        subtree:add(f_dir, buf(1,1))
 
         local proto_id = buf(0,1):uint()
 
         local dissector = protos[proto_id]
 
         if dissector ~= nil then
-                dissector:call(buf(2):tvb(),pkt,root)
+                -- Dissector was found, invoke subdissector with a new Tvb,
+                -- created from the current buffer (skipping first two bytes).
+                dissector:call(buf(2):tvb(), pkt, tree)
         elseif proto_id < 2 then
-                t:add(f_text,buf(2))
-                -- pkt.cols.info:set(buf(2,buf:len() - 3):string())
+                subtree:add(f_text, buf(2))
+                -- pkt.cols.info:set(buf(2, buf:len() - 3):string())
         else
-                data_dis:call(buf(2):tvb(),pkt,root)
+                -- fallback dissector that just shows the raw data.
+                data_dis:call(buf(2):tvb(), pkt, tree)
         end
 
 end
@@ -100,9 +103,9 @@ end
 local wtap_encap_table = DissectorTable.get("wtap_encap")
 local udp_encap_table = DissectorTable.get("udp.port")
 
-wtap_encap_table:add(wtap.USER15,p_multi)
-wtap_encap_table:add(wtap.USER12,p_multi)
-udp_encap_table:add(7555,p_multi)
+wtap_encap_table:add(wtap.USER15, p_multi)
+wtap_encap_table:add(wtap.USER12, p_multi)
+udp_encap_table:add(7555, p_multi)
 ----
 
 [[wslua_tap_example]]
@@ -168,6 +171,27 @@ register_menu("Test/Packets", menuable_tap, MENU_TOOLS_UNSORTED)
 
 This Part of the User Guide describes the Wireshark specific functions in the embedded Lua.
 
+Classes group certain functionality, the following notational conventions are
+used:
+
+* 'Class.function()' represents a class method (named 'function') on class
+  'Class', taking no arguments.
+
+* 'Class.function(a)' represents a class method taking one argument.
+
+* 'Class.function(...)' represents a class method taking a variable number of
+  arguments.
+
+* 'class:method()' represents an instance method (named 'method') on an instance
+  of class 'Class', taking no arguments. Note the lowercase notation in the
+  documentation to clarify an instance.
+
+* 'class.prop' represents a property 'prop' on the instance of class 'Class'.
+
+Trying to access a non-existing property, function or method currently gives an
+error, but do not rely on it as the behavior may change in the future.
+
+
 include::{build_dir}/wsluarm_src/wslua_dumper.asciidoc[]
 include::{build_dir}/wsluarm_src/wslua_field.asciidoc[]
 include::{build_dir}/wsluarm_src/wslua_gui.asciidoc[]
diff --git a/epan/wslua/wslua_byte_array.c b/epan/wslua/wslua_byte_array.c
index 59c932ffa6..e375afa954 100644
--- a/epan/wslua/wslua_byte_array.c
+++ b/epan/wslua/wslua_byte_array.c
@@ -336,10 +336,7 @@ WSLUA_METAMETHOD ByteArray__tostring(lua_State* L) {
     WSLUA_RETURN(1); /* A hex-ascii string representation of the `ByteArray`. */
 }
 
-/*
- * ByteArray_tvb(name)
- */
-WSLUA_CONSTRUCTOR ByteArray_tvb (lua_State *L) {
+WSLUA_METHOD ByteArray_tvb (lua_State *L) {
     /* Creates a new `Tvb` from a `ByteArray` (it gets added to the current frame too). */
 #define WSLUA_ARG_ByteArray_tvb_NAME 2 /* The name to be given to the new data-source. */
     ByteArray ba = checkByteArray(L,1);
diff --git a/epan/wslua/wslua_field.c b/epan/wslua/wslua_field.c
index d64513c5a2..29335ba541 100644
--- a/epan/wslua/wslua_field.c
+++ b/epan/wslua/wslua_field.c
@@ -308,9 +308,8 @@ static int FieldInfo_get_source(lua_State* L) {
     return 1;
 }
 
-/* WSLUA_ATTRIBUTE FieldInfo_range RO The `TvbRange` covering this field. */
+/* WSLUA_ATTRIBUTE FieldInfo_range RO The `TvbRange` covering the bytes of this field in a Tvb. */
 static int FieldInfo_get_range(lua_State* L) {
-    /* The `TvbRange` covering this field. */
     FieldInfo fi = checkFieldInfo(L,1);
 
     if (push_TvbRange (L, fi->ws_fi->ds_tvb, fi->ws_fi->start, fi->ws_fi->length)) {
diff --git a/epan/wslua/wslua_tvb.c b/epan/wslua/wslua_tvb.c
index 1f06dd1160..e10ff394d8 100644
--- a/epan/wslua/wslua_tvb.c
+++ b/epan/wslua/wslua_tvb.c
@@ -391,11 +391,10 @@ gboolean push_TvbRange(lua_State* L, tvbuff_t* ws_tvb, int offset, int len) {
 }
 
 
-WSLUA_CONSTRUCTOR TvbRange_tvb (lua_State *L) {
+WSLUA_METHOD TvbRange_tvb(lua_State *L) {
     /* Creates a (sub)`Tvb` from a `TvbRange`. */
-#define WSLUA_ARG_Tvb_new_subset_RANGE 1 /* The `TvbRange` from which to create the new `Tvb`. */
 
-    TvbRange tvbr = checkTvbRange(L,WSLUA_ARG_Tvb_new_subset_RANGE);
+    TvbRange tvbr = checkTvbRange(L,1);
     Tvb tvb;
 
     if (! (tvbr && tvbr->tvb)) return 0;