From 04aad36c0e9179ceb36b9459d52aad0059b7d1f2 Mon Sep 17 00:00:00 2001 From: Gerald Combs Date: Sun, 2 Nov 2014 13:20:08 -0800 Subject: [PATCH] Convert the Lua reference to AsciiDoc. Move it to the Developer's Guide while we're here. Nudge the markup in epan/wslua where needed. Note that we should probably convert it to AsciiDoc (if we're going to keep it in the DG) or Doxygen. Change-Id: Ie175111043f98b7a37eeeb8d185a833d8e866f8b Reviewed-on: https://code.wireshark.org/review/5203 Reviewed-by: Gerald Combs --- docbook/CMakeLists.txt | 5 +- docbook/GPL_appendix.asciidoc | 4 +- docbook/Makefile.am | 22 +- docbook/Makefile.common | 2 +- docbook/Makefile.nmake | 24 +- docbook/developer-guide-docinfo.xml | 7 + docbook/developer-guide.asciidoc | 2 + docbook/make-wsluarm.pl | 218 +++---- docbook/user-guide.xml | 21 - docbook/wsluarm.asciidoc | 689 ++++++++++++++++++++ docbook/wsluarm.xml | 713 --------------------- docbook/wsug_src/WSUG_chapter_use.asciidoc | 2 +- epan/wslua/wslua_int64.c | 2 +- epan/wslua/wslua_struct.c | 50 +- epan/wslua/wslua_tree.c | 4 +- epan/wslua/wslua_tvb.c | 2 +- 16 files changed, 838 insertions(+), 929 deletions(-) create mode 100644 docbook/wsluarm.asciidoc delete mode 100644 docbook/wsluarm.xml diff --git a/docbook/CMakeLists.txt b/docbook/CMakeLists.txt index 8af975a1db..9c4ee7ac11 100644 --- a/docbook/CMakeLists.txt +++ b/docbook/CMakeLists.txt @@ -50,7 +50,6 @@ set(WSUG_FILES WSUG_chapter_work.xml wsug_src/WSUG_meta_info.xml WSUG_preface.xml - wsluarm.xml ws.css ) @@ -66,6 +65,7 @@ set(WSDG_ASCIIDOC_FILES wsug_src/WSUG_chapter_use.asciidoc wsug_src/WSUG_chapter_work.asciidoc wsug_src/WSUG_preface.asciidoc + wsluarm.asciidoc ) set(WSUG_GRAPHICS @@ -253,6 +253,7 @@ MACRO( ASCIIDOC2DOCBOOK _asciidocsource _conf_files ) WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} COMMAND ${A2X_EXECUTABLE} --verbose + --attribute=build_dir=${CMAKE_CURRENT_BINARY_DIR} --attribute=docinfo --destination-dir=${CMAKE_CURRENT_BINARY_DIR} --asciidoc-opts=${_conf_opts} @@ -299,6 +300,7 @@ MACRO( ASCIIDOC2CHAPTER _asciidocsource _conf_files ) WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} COMMAND ${A2X_EXECUTABLE} --verbose + --attribute=build_dir=${CMAKE_CURRENT_BINARY_DIR} --destination-dir=${CMAKE_CURRENT_BINARY_DIR} --asciidoc-opts=${_conf_opts} --no-xmllint @@ -366,7 +368,6 @@ ADD_CUSTOM_COMMAND( add_custom_target( user_guides ALL DEPENDS - wsluarm wsug_html_chunked/index.html wsug_html/index.html user-guide-a4.pdf diff --git a/docbook/GPL_appendix.asciidoc b/docbook/GPL_appendix.asciidoc index bbdddf1a6a..61ab50e7aa 100644 --- a/docbook/GPL_appendix.asciidoc +++ b/docbook/GPL_appendix.asciidoc @@ -3,7 +3,7 @@ ++++++++++++++++++++++++++++++++++++++ [[AppGPL]] -=== This Document's License (GPL) +== This Document's License (GPL) As with the original license and documentation distributed with Wireshark, this document is covered by the GNU General Public @@ -354,4 +354,4 @@ proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License. ----- \ No newline at end of file +---- diff --git a/docbook/Makefile.am b/docbook/Makefile.am index 68d586ca34..cab1f9504f 100644 --- a/docbook/Makefile.am +++ b/docbook/Makefile.am @@ -96,10 +96,10 @@ endif wsug: $(WSUG_TARGETS) # validate the content -wsug.validated: $(WSUG_SOURCE) wsluarm +wsug.validated: $(WSUG_SOURCE) if HAVE_XMLLINT @ echo --- WSUG - VALIDATING XML --- - $(XMLLINT) --path .:wsluarm_src:$(srcdir) --valid --noout $< + $(XMLLINT) --path .:$(srcdir) --valid --noout $< touch $@ else @ echo --- WSUG - SKIP VALIDATION --- @@ -116,7 +116,6 @@ wsug_html/index.html: $(WSUG_SOURCE) wsluarm cp $(srcdir)/wsug_graphics/toolbar/* wsug_html/wsug_graphics/toolbar cp $(srcdir)/ws.css wsug_html $(XSLTPROC) --stringparam base.dir wsug_html/ $(COMMON_XSLTPROC_ARGS) \ - --path .:wsluarm_src \ $(WSUG_XSLTPROC_ARGS) $(SINGLE_XSLTPROC_ARGS) $< > $@ -chmod -R og+rX wsug_html @@ -131,7 +130,6 @@ wsug_html_chunked/index.html: $(WSUG_SOURCE) wsluarm cp $(srcdir)/wsug_graphics/toolbar/* wsug_html_chunked/wsug_graphics/toolbar cp $(srcdir)/ws.css wsug_html_chunked $(XSLTPROC) --stringparam base.dir wsug_html_chunked/ $(COMMON_XSLTPROC_ARGS) \ - --path .:wsluarm_src \ $(WSUG_XSLTPROC_ARGS) $(CHUNKED_XSLTPROC_ARGS) $< -chmod -R og+rX wsug_html_chunked @@ -140,16 +138,14 @@ wsug_html_chunked/index.html: $(WSUG_SOURCE) wsluarm user-guide-us.fo: $(WSUG_SOURCE) custom_layer_pdf.xsl wsluarm @ echo --- WSUG - PDF US PAPER --- $(XSLTPROC) --stringparam paper.type letter \ - --path .:wsluarm_src:$(srcdir) \ - --nonet custom_layer_pdf.xsl $< > $@ + --nonet custom_layer_pdf.xsl $< > $@ # create pdf file (through XSL-FO), portrait pages on A4 paper # you will get lot's of errors, but that's ok user-guide-a4.fo: $(WSUG_SOURCE) custom_layer_pdf.xsl wsluarm @ echo --- WSUG - PDF A4 PAPER --- $(XSLTPROC) --stringparam paper.type A4 \ - --path .:wsluarm_src:$(srcdir) \ - --nonet custom_layer_pdf.xsl $< > $@ + --nonet custom_layer_pdf.xsl $< > $@ wsluarm: make-wsluarm.pl $(WSLUA_MODULES) mkdir -p wsluarm_src @@ -182,14 +178,14 @@ developer-guide.xml: developer-guide.asciidoc $(WSDG_FILES) wsdg.validated: $(WSDG_SOURCE) if HAVE_XMLLINT @ echo --- WSDG - VALIDATING XML --- - $(XMLLINT) --path .:$(srcdir) --valid --noout $< + $(XMLLINT) --path .:wsluarm_src:$(srcdir) --valid --noout $< touch $@ else @ echo --- WSDG - SKIP VALIDATION --- endif # create html single page file -wsdg_html: wsdg_html/index.html +wsdg_html: wsdg_html/index.html wsluarm wsdg_html/index.html: $(WSDG_SOURCE) @ echo --- WSDG - HTML SINGLE PAGE --- @@ -199,6 +195,7 @@ wsdg_html/index.html: $(WSDG_SOURCE) cp $(srcdir)/wsdg_graphics/toolbar/* wsdg_html/wsdg_graphics/toolbar/ cp $(srcdir)/ws.css wsdg_html $(XSLTPROC) --stringparam base.dir wsdg_html/ $(COMMON_XSLTPROC_ARGS) \ + --path .:wsluarm_src \ $(WSDG_XSLTPROC_ARGS) $(SINGLE_XSLTPROC_ARGS) $< > $@ -chmod -R og+rX wsdg_html @@ -213,6 +210,7 @@ wsdg_html_chunked/index.html: $(WSDG_SOURCE) cp $(srcdir)/wsdg_graphics/toolbar/* wsdg_html_chunked/wsdg_graphics/toolbar/ cp $(srcdir)/ws.css wsdg_html_chunked $(XSLTPROC) --stringparam base.dir wsdg_html_chunked/ $(COMMON_XSLTPROC_ARGS) \ + --path .:wsluarm_src \ $(WSDG_XSLTPROC_ARGS) $(CHUNKED_XSLTPROC_ARGS) $< -chmod -R og+rX wsdg_html_chunked @@ -221,7 +219,7 @@ wsdg_html_chunked/index.html: $(WSDG_SOURCE) developer-guide-us.fo: $(WSDG_SOURCE) custom_layer_pdf.xsl @ echo --- WSDG - PDF US PAPER --- $(XSLTPROC) --stringparam paper.type letter \ - --path .:$(srcdir) \ + --path .:wsluarm_src:$(srcdir) \ --nonet custom_layer_pdf.xsl $< > $@ # create pdf file (through XSL-FO), portrait pages on A4 paper @@ -229,7 +227,7 @@ developer-guide-us.fo: $(WSDG_SOURCE) custom_layer_pdf.xsl developer-guide-a4.fo: $(WSDG_SOURCE) custom_layer_pdf.xsl @ echo --- WSDG - PDF A4 PAPER --- $(XSLTPROC) --stringparam paper.type A4 \ - --path .:$(srcdir) \ + --path .:wsluarm_src:$(srcdir) \ --nonet custom_layer_pdf.xsl $< > $@ diff --git a/docbook/Makefile.common b/docbook/Makefile.common index 557c4ef605..d92d512e9d 100644 --- a/docbook/Makefile.common +++ b/docbook/Makefile.common @@ -19,7 +19,6 @@ WSUG_FILES = \ wsug_src/WSUG_chapter_work.asciidoc \ wsug_src/WSUG_meta_info.xml \ wsug_src/WSUG_preface.asciidoc \ - wsluarm.xml \ ws.css WSUG_GENERATED_SOURCE = \ @@ -184,6 +183,7 @@ WSDG_FILES = \ wsdg_src/WSDG_chapter_userinterface.asciidoc \ wsdg_src/WSDG_chapter_works.asciidoc \ wsdg_src/WSDG_preface.asciidoc \ + wsluarm.asciidoc \ ws.css WSDG_GENERATED_SOURCE = \ diff --git a/docbook/Makefile.nmake b/docbook/Makefile.nmake index 752f061e66..e11d916a3c 100644 --- a/docbook/Makefile.nmake +++ b/docbook/Makefile.nmake @@ -92,7 +92,7 @@ git_version.xml: git_version_check wsug_x: wsug_html_chunked wsug_html user-guide-a4.pdf user-guide-us.pdf user-guide.chm # validate the content -wsug.validated: $(WSUG_SOURCE) wsluarm +wsug.validated: $(WSUG_SOURCE) @ echo --- WSUG - VALIDATING XML --- $(XMLLINT) --valid --noout user-guide.xml touch $@ @@ -100,7 +100,7 @@ wsug.validated: $(WSUG_SOURCE) wsluarm # create html single page file wsug_html: wsug_html\index.html -wsug_html\index.html: $(WSUG_SOURCE) wsluarm +wsug_html\index.html: $(WSUG_SOURCE) @ echo --- WSUG - HTML SINGLE PAGE --- if not exist wsug_html\wsug_graphics\toolbar md wsug_html\wsug_graphics\toolbar cp wsug_graphics/*.* wsug_html/wsug_graphics @@ -113,7 +113,7 @@ wsug_html\index.html: $(WSUG_SOURCE) wsluarm # create html chunked page files wsug_html_chunked: wsug_html_chunked\index.html -wsug_html_chunked\index.html: $(WSUG_SOURCE) wsluarm +wsug_html_chunked\index.html: $(WSUG_SOURCE) @ echo --- WSUG - HTML CHUNKED --- if not exist wsug_html_chunked\wsug_graphics\toolbar md wsug_html_chunked\wsug_graphics\toolbar cp wsug_graphics/*.* wsug_html_chunked/wsug_graphics @@ -125,7 +125,7 @@ wsug_html_chunked\index.html: $(WSUG_SOURCE) wsluarm # create pdf file (through XSL-FO), portrait pages on US letter paper (the default) # you will get lot's of errors, but that's ok -user-guide-us.fo: $(WSUG_SOURCE) custom_layer_pdf.xsl wsluarm +user-guide-us.fo: $(WSUG_SOURCE) custom_layer_pdf.xsl !ifdef FOP @ echo --- WSUG - PDF US PAPER --- $(XSLTPROC) --stringparam paper.type letter --nonet custom_layer_pdf.xsl user-guide.xml > $@ @@ -133,14 +133,14 @@ user-guide-us.fo: $(WSUG_SOURCE) custom_layer_pdf.xsl wsluarm # create pdf file (through XSL-FO), portrait pages on A4 paper # you will get lot's of errors, but that's ok -user-guide-a4.fo: $(WSUG_SOURCE) custom_layer_pdf.xsl wsluarm +user-guide-a4.fo: $(WSUG_SOURCE) custom_layer_pdf.xsl !ifdef FOP @ echo --- WSUG - PDF A4 PAPER --- $(XSLTPROC) --stringparam paper.type A4 --nonet custom_layer_pdf.xsl user-guide.xml > $@ !endif # create MS html help file (through html chunked pages) -user-guide.chm: $(WSUG_SOURCE) wsluarm +user-guide.chm: $(WSUG_SOURCE) !ifdef HHC_EXE @ echo --- WSUG - MICROSOFT HTML HELP --- if not exist wsug_chm\wsug_graphics\toolbar md wsug_chm\wsug_graphics\toolbar @@ -178,7 +178,7 @@ developer-guide.xml: developer-guide.asciidoc $(WSDG_FILES) << # validate the content -wsdg.validated: $(WSDG_SOURCE) +wsdg.validated: $(WSDG_SOURCE) wsluarm @ echo --- WSDG - VALIDATING XML --- $(XMLLINT) --valid --noout developer-guide.xml touch $@ @@ -186,7 +186,7 @@ wsdg.validated: $(WSDG_SOURCE) # create html single page file wsdg_html: wsdg_html\index.html -wsdg_html\index.html: $(WSDG_SOURCE) +wsdg_html\index.html: $(WSDG_SOURCE) wsluarm @ echo --- WSDG - HTML SINGLE PAGE --- if not exist wsdg_html\wsdg_graphics md wsdg_html\wsdg_graphics if not exist wsdg_html\wsdg_graphics\toolbar md wsdg_html\wsdg_graphics\toolbar @@ -200,7 +200,7 @@ wsdg_html\index.html: $(WSDG_SOURCE) # create html chunked page files wsdg_html_chunked: wsdg_html_chunked\index.html -wsdg_html_chunked\index.html: $(WSDG_SOURCE) +wsdg_html_chunked\index.html: $(WSDG_SOURCE) wsluarm @ echo --- WSDG - HTML CHUNKED --- if not exist wsdg_html_chunked\wsdg_graphics md wsdg_html_chunked\wsdg_graphics if not exist wsdg_html_chunked\wsdg_graphics\toolbar md wsdg_html_chunked\wsdg_graphics\toolbar @@ -213,7 +213,7 @@ wsdg_html_chunked\index.html: $(WSDG_SOURCE) # create pdf file (through XSL-FO), portrait pages on US letter paper (the default) # you will get lot's of errors, but that's ok -developer-guide-us.fo: $(WSDG_SOURCE) custom_layer_pdf.xsl +developer-guide-us.fo: $(WSDG_SOURCE) custom_layer_pdf.xsl wsluarm !ifdef FOP @ echo --- WSDG - PDF US PAPER --- $(XSLTPROC) --stringparam paper.type letter --nonet custom_layer_pdf.xsl developer-guide.xml > $@ @@ -221,14 +221,14 @@ developer-guide-us.fo: $(WSDG_SOURCE) custom_layer_pdf.xsl # create pdf file (through XSL-FO), portrait pages on A4 paper # you will get lot's of errors, but that's ok -developer-guide-a4.fo: $(WSDG_SOURCE) custom_layer_pdf.xsl +developer-guide-a4.fo: $(WSDG_SOURCE) custom_layer_pdf.xsl wsluarm !ifdef FOP @ echo --- WSDG - PDF A4 PAPER --- $(XSLTPROC) --stringparam paper.type A4 --nonet custom_layer_pdf.xsl developer-guide.xml > $@ !endif # create MS html help file (through html chunked pages) -developer-guide.chm: $(WSDG_SOURCE) +developer-guide.chm: $(WSDG_SOURCE) wsluarm !ifdef HHC_EXE @ echo --- WSDG - MICROSOFT HTML HELP --- if not exist wsdg_chm\wsdg_graphics md wsdg_chm\wsdg_graphics diff --git a/docbook/developer-guide-docinfo.xml b/docbook/developer-guide-docinfo.xml index b1f78ebeb9..893ce71fb0 100644 --- a/docbook/developer-guide-docinfo.xml +++ b/docbook/developer-guide-docinfo.xml @@ -20,6 +20,13 @@ + + 1.0 + 2 Nov 2014 + gcc + Moved Lua reference from User's Guide to Developer's Guide. + + 0.9 9 Feb 2014 diff --git a/docbook/developer-guide.asciidoc b/docbook/developer-guide.asciidoc index eff257cd47..4f698d0134 100644 --- a/docbook/developer-guide.asciidoc +++ b/docbook/developer-guide.asciidoc @@ -45,6 +45,8 @@ include::wsdg_src/WSDG_chapter_capture.asciidoc[] include::wsdg_src/WSDG_chapter_dissection.asciidoc[] +include::wsluarm.asciidoc[] + include::wsdg_src/WSDG_chapter_userinterface.asciidoc[] include::GPL_appendix.asciidoc[] diff --git a/docbook/make-wsluarm.pl b/docbook/make-wsluarm.pl index c6fa9cfec9..4bd121426b 100755 --- a/docbook/make-wsluarm.pl +++ b/docbook/make-wsluarm.pl @@ -49,6 +49,10 @@ # * a line starting with "@code" and ending with "@endcode" becomes an # XML programlisting block, with no indenting/parsing within the block # The above '@' commands are based on Doxygen commands +# +# Changed by Gerald Combs to generate AsciiDoc. +# - We might want to convert the epan/wslua/*.c markup to AsciiDoc +# - ...or we might want to generate Doxygen output instead. use strict; #use V2P; @@ -66,27 +70,19 @@ sub gorolla { # remove trailing newlines and spaces at end $s =~ s/([\n]|\s)*$//s; # escape HTML entities everywhere - $s =~ s/&/&/msg; # do this one first so we don't clobber later ones - $s =~ s/\/>/msg; # bold and italics - but don't change a star followed by space (it's a list item) - $s =~ s/(\*\*)([^*]+?)(\*\*)/$2<\/command>/g; # bold=command?? - $s =~ s/(\*)([^\s][^*]*?)(\*)/$2<\/emphasis>/g; # italics + $s =~ s/(\*\*)([^*]+?)(\*\*)/`$2`/g; # bold=command?? # one backtick is quote/command - $s =~ s/([^`]|^)(`)([^`]+?)(`)/$1$3<\/command>/g; # quote=command?? - # two backticks are one - $s =~ s/(``)([^`]+?)(``)/`$2`/g; # quote=command?? + #$s =~ s/([^`]|^)(`)([^`]+?)(`)/$1$3<\/command>/g; # quote=command?? + # two backticks are one (...and don't appear anywhere?) + #$s =~ s/(``)([^`]+?)(``)/`$2`/g; # quote=command?? - # handle '[[url]]' - $s =~ s/(\[\[)([^\]\|]+?)(\]\])/$2<\/ulink>/g; + # Convert wiki-style '[[url]]' + $s =~ s/(\[\[)([^\]\|]+?)(\]\])/link:\$\$$2\$\$:[$2]/g; # handle '[[url|pretty]]' - $s =~ s/(\[\[)(([^\]\|]+?)\|\s*([^\]]+?))(\]\])/$4<\/ulink>/g; - # unescape gorolla'd ampersands in url - while ($s =~ //; + $line =~ s/\@code/[source,lua]\n----\n/; # if this line didn't have ending token, keep eating paragraphs while (!($line =~ /\@endcode\b/) && $idx <= $#lines) { # also insert back the line separator we ate in earlier split() $line .= $lines[++$idx] . "\n"; } # fix ending token, and also remove trailing whitespace before it - $line =~ s/[\s\n]*\@endcode/<\/programlisting>/; + $line =~ s/[\s\n]*\@endcode/\n----/; $r[++$#r] = $line . "\n"; } elsif ($lines[$idx] =~ /^\s*$/) { # line is either empty or just whitespace, and we're not in a @code block # so it's the end of a previous paragraph, beginning of new one - $r[++$#r] = "\n"; - $r[++$#r] = "\n"; + $r[++$#r] = "\n\n"; } else { - # we have a regular line, not in a @code block - # XML-ify it + # We have a regular line, not in a @code block. + # Add it as-is. my $line = $lines[$idx]; - # if line starts with "Note:" or "@note", make it an XML + # If line starts with "Note:" or "@note", make it an admonition if ($line =~ /^[nN]ote:|^\@note /) { - $r[++$#r] = "\n"; - $r[++$#r] = "\n"; - $r[++$#r] = "\t\n"; + $r[++$#r] = "[NOTE]\n"; + $r[++$#r] = "====\n"; $line =~ s/^([nN]ote:\s*|\@note\s*)//; - $r[++$#r] = "\t\t" . $line . "\n"; + $r[++$#r] = "" . $line . "\n"; # keep eating until we find a blank line or end while (!($lines[++$idx] =~ /^\s*$/) && $idx <= $#lines) { $lines[$idx] =~ s/^(\s*)//; # remove leading whitespace - $r[++$#r] = "\t\t" . $lines[$idx]. "\n"; + $r[++$#r] = "" . $lines[$idx]. "\n"; } - $r[++$#r] = "\t\n"; - $r[++$#r] = "\n"; - $r[++$#r] = "\n"; + $r[++$#r] = "====\n\n"; - # if line starts with "Warning:"" or @warning", make it an XML + # If line starts with "Warning:"" or @warning", make it an admonition } elsif ($line =~ /^[wW]arning:|^\@warning /) { - $r[++$#r] = "\n"; - $r[++$#r] = "\n"; - $r[++$#r] = "\t\n"; + $r[++$#r] = "[WARNING]\n"; + $r[++$#r] = "====\n"; $line =~ s/^(wW]arning:\s*|\@warning\s*)//; # keep eating until we find a blank line or end - $r[++$#r] = "\t\t" . $line . "\n"; + $r[++$#r] = "" . $line . "\n"; while (!($lines[++$idx] =~ /^\s*$/) && $idx <= $#lines) { $lines[$idx] =~ s/^(\s*)//; # remove leading whitespace - $r[++$#r] = "\t\t" . $lines[$idx] . "\n"; + $r[++$#r] = "" . $lines[$idx] . "\n"; } - $r[++$#r] = "\t\n"; - $r[++$#r] = "\n"; - $r[++$#r] = "\n"; + $r[++$#r] = "====\n"; # if line starts with "@version" or "@since", make it a "Since:" } elsif ($line =~ /^\@version |^\@since /) { - $r[++$#r] = "\n"; - $r[++$#r] = "\n"; $line =~ s/^\@version\s+|^\@since\s+/Since: /; - $r[++$#r] = "\t" . $line . "\n"; - $r[++$#r] = "\n"; - $r[++$#r] = "\n"; + $r[++$#r] = "\n" . $line . "\n\n"; - # if line starts with single "*" and space, make it an XML + # if line starts with single "*" and space, leave it mostly intact. } elsif ($line =~ /^\*\s/) { - $r[++$#r] = "\n"; - $r[++$#r] = "\n"; - $r[++$#r] = "\t\n"; - $r[++$#r] = "\t\t\n"; - $line =~ s/^\*\s*//; # remove the star and whitespace - $r[++$#r] = "\t\t\t" . $line . "\n"; + $r[++$#r] = "\n"; + $r[++$#r] = "" . $line . "\n"; # keep eating until we find a blank line or end while (!($lines[++$idx] =~ /^\s*$/) && $idx <= $#lines) { $lines[$idx] =~ s/^(\s*)//; # count and remove leading whitespace # if this is less indented than before, break out last if length($1) < $indent; - if ($lines[$idx] =~ /^\*\s/) { - # another star, new list item - $r[++$#r] = "\t\t\n"; - $r[++$#r] = "\t\n"; - $r[++$#r] = "\t\n"; - $r[++$#r] = "\t\t\n"; - $lines[$idx] =~ s/^\*\s*//; # remove star and whitespace - } - $r[++$#r] = "\t\t\t" . $lines[$idx] . "\n"; + $r[++$#r] = "" . $lines[$idx] . "\n"; } - $r[++$#r] = "\t\t\n"; - $r[++$#r] = "\t\n"; - $r[++$#r] = "\n"; - $r[++$#r] = "\n"; + $r[++$#r] = "\n\n"; - # if line starts with "1." and space, make it an XML + # if line starts with "1." and space, leave it mostly intact. } elsif ($line =~ /^1\.\s/) { - $r[++$#r] = "\n"; - $r[++$#r] = "\n"; - $r[++$#r] = "\t\n"; - $r[++$#r] = "\t\t\n"; - $line =~ s/^1\.\s*//; # remove the 1. and whitespace - $r[++$#r] = "\t\t\t" . $line . "\n"; + $r[++$#r] = "\n"; + $r[++$#r] = "" . $line . "\n"; # keep eating until we find a blank line or end while (!($lines[++$idx] =~ /^\s*$/) && $idx <= $#lines) { $lines[$idx] =~ s/^(\s*)//; # count and remove leading whitespace # if this is less indented than before, break out last if length($1) < $indent; - if ($lines[$idx] =~ /^[0-9]+\.\s/) { - # another number, new list item - $r[++$#r] = "\t\t\n"; - $r[++$#r] = "\t\n"; - $r[++$#r] = "\t\n"; - $r[++$#r] = "\t\t\n"; - $lines[$idx] =~ s/^[0-9]+\.\s*//; # remove star and whitespace - } - $r[++$#r] = "\t\t\t" . $lines[$idx] . "\n"; + $r[++$#r] = "" . $lines[$idx] . "\n"; } - $r[++$#r] = "\t\t\n"; - $r[++$#r] = "\t\n"; - $r[++$#r] = "\n"; - $r[++$#r] = "\n"; + $r[++$#r] = "\n\n"; # just a normal line, add it to array } else { - $r[++$#r] = "\t" . $line . "\n"; + # Nested Lua arrays + $line =~ s/\[\[(.*)\]\]/\$\$$1\$\$/g; + $r[++$#r] = "" . $line . "\n"; } } } - $r[++$#r] = "\n"; + $r[++$#r] = "\n\n"; - # now go through @r, and copy into @ret but skip empty - # paragraphs (ie, followed by ) - # I could have used splice(), but I think this is easier (and faster?) - # this isn't strictly necessary since the XML tool seems - # to ignore empty paragraphs, but in case it ever changes... + # Now go through @r, and copy into @ret but skip empty lines. + # This isn't strictly necessary but makes the AsciiDoc output prettier. for (my $idx=0; $idx <= $#r; $idx++) { - if ($r[$idx] =~ /^\n$/ && $r[$idx+1] =~ /^<\/para>\n$/) { + if ($r[$idx] =~ /^\s*$/ && $r[$idx+1] =~ /^\s*$/ && $r[$idx+2] =~ /^\s*$/) { $idx++; # for-loop will increment $idx and skip the other one } else { $ret[++$#ret] = $r[$idx]; @@ -286,7 +239,7 @@ sub parse_module_desc { my @lines = split(/\n/, $s); my $line = shift @lines; - $r[++$#r] = "$line\n"; + $r[++$#r] = "=== $line\n\n"; return parse_desc_common(\@r, \@lines); } @@ -295,12 +248,12 @@ sub parse_module_desc { sub parse_function_arg_desc { my $s = gorolla(shift); # break description into separate sections - my @r = ( "\n" ); # the array we return + my @r = ( "\n" ); # the array we return my @lines = split(/\n/, $s); @r = @{ parse_desc_common(\@r, \@lines) }; - $r[++$#r] = "\n"; + #$r[++$#r] = "\n"; return \@r; } @@ -316,7 +269,7 @@ sub parse_attrib_desc { $mode =~ s/RO/ Retrieve only./; $mode =~ s/WO/ Assign only./; $mode =~ s/RW|WR/ Retrieve or assign./; - $r[++$#r] = "Mode: $mode\n"; + $r[++$#r] = "Mode: $mode\n\n"; } else { die "Attribute does not have a RO/WO/RW mode: '$s'\n"; } @@ -336,10 +289,10 @@ sub print_desc { if (!$indent) { $indent = 2; } - my $tabs = "\t" x $indent; + #my $tabs = "\t" x $indent; for my $line ( @{ $desc_ref } ) { - printf D "%s%s", $tabs, $line; + printf D "%s", $line; } } @@ -350,51 +303,44 @@ my %classes; my $function; my @functions; -my $docbook_template = { - module_header => "
\n", +my $asciidoc_template = { + module_header => "[[lua_module_%s]]\n\n", # module_desc => "\t%s\n", - class_header => "\t
\n" . - "\t\t%s\n", + class_header => "[[lua_class_%s]]\n\n" . + "==== %s\n\n", #class_desc => "\t\t%s\n", - class_attr_header => "\t\t
\n" . - "\t\t\t%s\n", + class_attr_header => "[[lua_class_attrib_%s]]\n\n" . + "==== %s\n\n", #class_attr_descr => "\t\t\t%s%s\n", - class_attr_footer => "\t\t
\n", - function_header => "\t\t
\n" . - "\t\t\t%s\n", + class_attr_footer => "// End %s\n\n", + function_header => "[[lua_fn_%s]]\n\n" . + "===== %s\n\n", #function_descr => "\t\t\t%s\n", - function_args_header => "\t\t\t
\n" . - "\t\t\t\tArguments\n" . - "\t\t\t\t\n", - function_arg_header => "\t\t\t\t\t\n" . - "\t\t\t\t\t\t%s\n", + function_args_header => "[float]\n" . + "===== Arguments\n\n", + function_arg_header => "%s::\n", #function_arg_descr => "\t\t\t\t\t\t\n" . # "\t\t\t\t\t\t\t%s\n" . # "\t\t\t\t\t\t\n", - function_arg_footer => "\t\t\t\t\t \n", - function_args_footer => "\t\t\t\t\n" . - "\t\t\t
\n", + function_arg_footer => "// function_arg_footer: %s\n\n", + function_args_footer => "// end of function_args\n\n", function_argerror_header => "", #"\t\t\t\t\t
Errors\n\t\t\t\t\t\t\n", function_argerror => "", #"\t\t\t\t\t\t\t%s\n", function_argerror_footer => "", #"\t\t\t\t\t\t
\n", - function_returns_header => "\t\t\t
\n" . - "\t\t\t\tReturns\n", - function_returns => "\t\t\t\t%s\n", - function_returns_footer => "\t\t\t
\n", - function_errors_header => "\t\t\t
\n" . - "\t\t\t\tErrors\n" . - "\t\t\t\t\n", - function_errors => "\t\t\t\t\t\n" . - "\t\t\t\t\t\t%s\n" . - "\t\t\t\t\t\n", - function_errors_footer => "\t\t\t\t\n" . - "\t\t\t
\n", - function_footer => "\t\t
\n", - class_footer => "\t
\n", - global_functions_header => "\t
\n" . - "\t\tGlobal Functions\n", - global_functions_footer => "\t
\n", - module_footer => "
\n", + function_returns_header => "[float]\n" . + "===== Returns\n\n", + function_returns => "%s\n\n", + function_returns_footer => "// function_returns_footer: %s\n", + function_errors_header => "[float]\n" . + "===== Errors\n\n", + function_errors => "* %s\n", + function_errors_footer => "// function_errors_footer: %s\n", + function_footer => "// function_footer: %s\n\n", + class_footer => "// class_footer: %s\n", + global_functions_header => "[[global_functions_%s]]\n\n" . + "==== Global Functions\n\n", + global_functions_footer => "// Global function\n", + module_footer => "// end of module\n", }; # class_constructors_header => "\t\t
\n\t\t\t%s Constructors\n", @@ -403,8 +349,8 @@ my $docbook_template = { # class_methods_footer => "\t\t
\n", -my $template_ref = $docbook_template; -my $out_extension = "xml"; +my $template_ref = $asciidoc_template; +my $out_extension = "asciidoc"; # It's said that only perl can parse perl... my editor isn't perl... # if unencoded this causes my editor's autoindent to bail out so I encoded in octal diff --git a/docbook/user-guide.xml b/docbook/user-guide.xml index eb20e44265..12a9e96ee7 100644 --- a/docbook/user-guide.xml +++ b/docbook/user-guide.xml @@ -329,25 +329,6 @@ FILE SECTION - - - - - - - - - - - - - - - - - ]> @@ -366,8 +347,6 @@ WSLua Reference Manual &ChapterTelephony; &ChapterCustomize; - &WsLuaRm; - &AppFiles; &AppProtocols; &AppMessages; diff --git a/docbook/wsluarm.asciidoc b/docbook/wsluarm.asciidoc new file mode 100644 index 0000000000..197723b1c6 --- /dev/null +++ b/docbook/wsluarm.asciidoc @@ -0,0 +1,689 @@ +[[wsluarm]] + +// Attributes +:build_dir: . + +== Lua Support in Wireshark + +[[wsluarm_intro]] + +=== Introduction + +Wireshark has an embedded Lua interpreter. Lua is a powerful light-weight +programming language designed for extending applications. Lua is designed and +implemented by a team at PUC-Rio, the Pontifical Catholic University of Rio de +Janeiro in Brazil. Lua was born and raised at Tecgraf, the Computer Graphics +Technology Group of PUC-Rio, and is now housed at +link:http://www.lua.org[Lua.org]. Both Tecgraf and Lua.org are laboratories of +the Department of Computer Science. + +In Wireshark Lua can be used to write dissectors, taps, and capture file readers +and writers. + +Wireshark's Lua interpreter starts by loading `init.lua` that is located in the +global configuration directory of Wireshark. Lua is enabled by default. To +disable Lua the line variable _$$disable_lua$$_ should be set to _true_ in +`init.lua`. + +After loading _init.lua_ from the data directory if Lua is enabled Wireshark +will try to load a file named `init.lua` in the user's directory. + +Wireshark will also load all files with `.lua` suffix from both the global and +the personal plugins directory. + +The command line option _$$-X lua_script:$$++file.lua++_ can be used to load +Lua scripts as well. + +The Lua code will be executed once after all the protocol dissectors have being +initialized and before reading any file. + +[[wslua_dissector_example]] + +=== Example of Dissector written in Lua + +[source,lua] +---- +local p_multi = Proto("multi","MultiProto"); + +local vs_protos = { + [2] = "mtp2", + [3] = "mtp3", + [4] = "alcap", + [5] = "h248", + [6] = "ranap", + [7] = "rnsap", + [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") + +p_multi.fields = { f_proto, f_dir, f_text } + +local data_dis = Dissector.get("data") + +local protos = { + [2] = Dissector.get("mtp2"), + [3] = Dissector.get("mtp3"), + [4] = Dissector.get("alcap"), + [5] = Dissector.get("h248"), + [6] = Dissector.get("ranap"), + [7] = Dissector.get("rnsap"), + [8] = Dissector.get("nbap"), + [9] = Dissector.get("rrc"), + [10] = DissectorTable.get("sctp.ppi"):get_dissector(3), -- m3ua + [11] = DissectorTable.get("ip.proto"):get_dissector(132), -- sctp +} + +function p_multi.dissector(buf,pkt,root) + + local t = root:add(p_multi,buf(0,2)) + t:add(f_proto,buf(0,1)) + t: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) + elseif proto_id < 2 then + t:add(f_text,buf(2)) + -- pkt.cols.info:set(buf(2,buf:len() - 3):string()) + else + data_dis:call(buf(2):tvb(),pkt,root) + end + +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) +---- + +[[wslua_tap_example]] + +=== Example of Listener written in Lua + +[source,lua] +---- +-- This program will register a menu that will open a window with a count of occurrences +-- of every address in the capture + +local function menuable_tap() + -- Declare the window we will use + local tw = TextWindow.new("Address Counter") + + -- This will contain a hash of counters of appearances of a certain address + local ips = {} + + -- this is our tap + local tap = Listener.new(); + + function remove() + -- this way we remove the listener that otherwise will remain running indefinitely + tap:remove(); + end + + -- we tell the window to call the remove() function when closed + tw:set_atclose(remove) + + -- this function will be called once for each packet + function tap.packet(pinfo,tvb) + local src = ips[tostring(pinfo.src)] or 0 + local dst = ips[tostring(pinfo.dst)] or 0 + + ips[tostring(pinfo.src)] = src + 1 + ips[tostring(pinfo.dst)] = dst + 1 + end + + -- this function will be called once every few seconds to update our window + function tap.draw(t) + tw:clear() + for ip,num in pairs(ips) do + tw:append(ip .. "\t" .. num .. "\n"); + end + end + + -- this function will be called whenever a reset is needed + -- e.g. when reloading the capture file + function tap.reset() + tw:clear() + ips = {} + end +end + +-- using this function we register our function +-- to be called when the user selects the Tools->Test->Packets menu +register_menu("Test/Packets", menuable_tap, MENU_TOOLS_UNSORTED) +---- + +[[wsluarm_modules]] + +=== Wireshark's Lua API Reference Manual + +This Part of the User Guide describes the Wireshark specific functions in the embedded Lua. + +include::{build_dir}/wsluarm_src/wslua_dumper.asciidoc[] +include::{build_dir}/wsluarm_src/wslua_field.asciidoc[] +include::{build_dir}/wsluarm_src/wslua_gui.asciidoc[] +include::{build_dir}/wsluarm_src/wslua_listener.asciidoc[] +include::{build_dir}/wsluarm_src/wslua_pinfo.asciidoc[] +include::{build_dir}/wsluarm_src/wslua_proto.asciidoc[] +include::{build_dir}/wsluarm_src/wslua_tree.asciidoc[] +include::{build_dir}/wsluarm_src/wslua_tvb.asciidoc[] +include::{build_dir}/wsluarm_src/wslua_file.asciidoc[] +include::{build_dir}/wsluarm_src/wslua_dir.asciidoc[] +include::{build_dir}/wsluarm_src/wslua_utility.asciidoc[] +include::{build_dir}/wsluarm_src/wslua_int64.asciidoc[] +include::{build_dir}/wsluarm_src/wslua_struct.asciidoc[] + +// WsLuaDumper +// WsLuaField +// WsLuaGui +// WsLuaListener +// WsLuaPinfo +// WsLuaProto +// WsLuaTree +// WsLuaTvb +// WsLuaFile +// WsLuaDir +// WsLuaUtility +// WsLuaInt64 +// WsLuaStruct + +[[lua_module_GRegex]] + +=== GLib Regular Expressions + +Lua has its own native 'pattern' syntax in the string library, but sometimes a +real regex engine is more useful. Wireshark comes with GLib's Regex +implementation, which itself is based on Perl Compatible Regular Expressions +(PCRE). This engine is exposed into Wireshark's Lua engine through the +well-known Lrexlib library, following the same syntax and semantics as the +Lrexlib PCRE implementation, with a few differences as follows: + +* There is no support for using custom locale/chartables + +* 'dfa_exec()' doesn't take 'ovecsize' nor 'wscount' arguments + +* 'dfa_exec()' returns boolean true for partial match, without subcapture info + +* Named subgroups do not return name-keyed entries in the return table (i.e., in + match/tfind/exec) + +* The 'flags()' function still works, returning all flags, but two new functions + 'compile_flags()' and 'match_flags()' return just their respective flags, + since GLib has a different and smaller set of such flags, for regex compile + vs. match functions + +* Using some assertions and POSIX character classes against strings with + non-ASCII characters might match high-order characters, because glib always + sets PCRE_UCP even if G_REGEX_RAW is set. For example, '[:alpha;]' matches + certain non-ASCII bytes. The following assertions have this issue: '\b', '\B', + '\s', '\S', '\w', '\W'. The following character classes have this issue: + [:alpha:], [:alnum:], [:lower:], [:upper:], [:space:], [:word:], and + [:graph:]. + +* The compile flag G_REGEX_RAW is always set/used, even if you didn't specify + it. This is because GLib runs PCRE in UTF-8 mode by default, whereas Lua + strings are not UTF-aware. + + +Since: 1.11.3 + +This page is based on the full documentation for Lrexlib at +link:http://rrthomas.github.io/lrexlib/manual.html[http://rrthomas.github.io/lrexlib/manual.html] + +The GLib Regular expression syntax (which is essentially PCRE syntax) can be +found at +link:https://developer.gnome.org/glib/2.38/glib-regex-syntax.html[https://developer.gnome.org/glib/2.38/glib-regex-syntax.html] + +[[lua_class_GRegex]] + +==== GRegex + +GLib Regular Expressions based on PCRE. + +Since: 1.11.3 + +[[lua_class_GRegex_notes]] + +===== Notes + +All functions that take a regular expression pattern as an argument will +generate an error if that pattern is found invalid by the regex library. + +All functions that take a string-type regex argument accept a compiled regex +too. In this case, the compile flags argument is ignored (should be either +supplied as nils or omitted). + +The capture flag argument 'cf' may also be supplied as a string, whose +characters stand for compilation flags. Combinations of the following characters +(case sensitive) are supported: + +* '__i__' = G_REGEX_CASELESS - Letters in the pattern match both upper- and + lowercase letters. This option can be changed within a pattern by a ``(?i)'' + option setting. + +* '__m__' = G_REGEX_MULTILINE - By default, GRegex treats the strings as + consisting of a single line of characters (even if it actually contains + newlines). The ``start of line'' metacharacter (``^'') matches only at the start + of the string, while the ``end of line'' metacharacter (``$'') matches only at + the end of the string, or before a terminating newline (unless + G_REGEX_DOLLAR_ENDONLY is set). When G_REGEX_MULTILINE is set, the ``start of + line'' and ``end of line'' constructs match immediately following or + immediately before any newline in the string, respectively, as well as at the + very start and end. This can be changed within a pattern by a ``(?m)'' option + setting. + +* '__s__' = G_REGEX_DOTALL - A dot metacharater (``.'') in the pattern matches + all characters, including newlines. Without it, newlines are excluded. This + option can be changed within a pattern by a ("?s") option setting. + +* '__x__' = G_REGEX_EXTENDED - Whitespace data characters in the pattern are + totally ignored except when escaped or inside a character class. Whitespace + does not include the VT character (code 11). In addition, characters between + an unescaped ``$$#$$'' outside a character class and the next newline character, + inclusive, are also ignored. This can be changed within a pattern by a + ``(?x)'' option setting. + +* '__U__' = G_REGEX_UNGREEDY - Inverts the ``greediness'' of the quantifiers so + that they are not greedy by default, but become greedy if followed by ``?''. + It can also be set by a ``(?U)'' option setting within the pattern. + +[[lua_fn_GRegex_new_pattern_]] + +===== GRegex.new(pattern) + +Compiles regular expression pattern into a regular expression object whose +internal representation is corresponding to the library used. The returned +result then can be used by the methods, e.g. match, exec, etc. Regular +expression objects are automatically garbage collected. + +Since: 1.11.3 + +[float] +===== Arguments + +pattern:: A Perl-compatible regular expression pattern string + +[float] +===== Returns + +The compiled regular expression (a userdata object) + +[float] +===== Errors + +* A malformed pattern generates a Lua error + +[[lua_fn_GRegex_flags__table__]] + +===== GRegex.flags([table]) + +Returns a table containing the numeric values of the constants defined by the +regex library, with the keys being the (string) names of the constants. If the +table argument is supplied then it is used as the output table, otherwise a new +table is created. The constants contained in the returned table can then be used +in most functions and methods where compilation flags or execution flags can be +specified. They can also be used for comparing with return codes of some +functions and methods for determining the reason of failure. + +Since: 1.11.3 + +[float] +===== Arguments + +table (optional):: A table for placing results into + +[float] +===== Returns + +A table filled with the results. + +[[lua_fn_GRegex_compile_flags__table__]] + + +===== GRegex.compile_flags([table]) + +Returns a table containing the numeric values of the constants defined by the +regex library for compile flags, with the keys being the (string) names of the +constants. If the table argument is supplied then it is used as the output +table, otherwise a new table is created. + +Since: 1.11.3 + +[float] +===== Arguments + +table (optional):: A table for placing results into + +[float] +===== Returns + +A table filled with the results. + +[[lua_fn_GRegex_match_flags__table__]] + +===== GRegex.match_flags([table]) + +Returns a table containing the numeric values of the constants defined by the +regex library for match flags, with the keys being the (string) names of the +constants. If the table argument is supplied then it is used as the output +table, otherwise a new table is created. + +Since: 1.11.3 + +[float] +===== Arguments + +table (optional):: A table for placing results into + +[float] +===== Returns + +A table filled with the results. + +[[lua_fn_GRegex_match_subject__pattern___init____cf____ef__]] + +===== GRegex.match(subject, pattern, [init], [cf], [ef]) + +Searches for the first match of the regexp pattern in the string subject, +starting from offset init, subject to flags cf and ef. The pattern is compiled +each time this is called, unlike the class method 'match' function. + +Since: 1.11.3 + +[float] +===== Arguments + +subject:: Subject string to search + +pattern:: A Perl-compatible regular expression pattern string or GRegex object + +init (optional):: start offset in the subject (can be negative) + +cf (optional):: compilation flags (bitwise OR) + +ef (optional):: match execution flags (bitwise OR) + +[float] +===== Returns + +On success, returns all substring matches ("captures"), in the order they appear +in the pattern. false is returned for sub-patterns that did not participate in +the match. If the pattern specified no captures then the whole matched substring +is returned. On failure, returns nil. + +[[lua_fn_GRegex_find_subject__pattern___init____cf____ef__]] + +===== GRegex.find(subject, pattern, [init], [cf], [ef]) + +Searches for the first match of the regexp pattern in the string subject, +starting from offset init, subject to flags ef. The pattern is compiled each +time this is called, unlike the class method 'find' function. + +Since: 1.11.3 + +[float] +===== Arguments + +subject:: Subject string to search + +pattern:: A Perl-compatible regular expression pattern string or GRegex object + +init (optional):: start offset in the subject (can be negative) + +cf (optional):: compilation flags (bitwise OR) + +ef (optional):: match execution flags (bitwise OR) + +[float] +===== Returns + +On success, returns the start point of the match (a number), the end point of +the match (a number), and all substring matches ("captures"), in the order they +appear in the pattern. false is returned for sub-patterns that did not +participate in the match. On failure, returns nil. + +[[lua_fn_GRegex_gmatch_subject__pattern___init____cf____ef__]] + + +===== GRegex.gmatch(subject, pattern, [init], [cf], [ef]) + +Returns an iterator for repeated matching of the pattern patt in the string +subj, subject to flags cf and ef. The function is intended for use in the +generic for Lua construct. The pattern can be a string or a GRegex object +previously compiled with GRegex.new(). + +Since: 1.11.3 + +[float] +===== Arguments + +subject:: Subject string to search + +pattern:: A Perl-compatible regular expression pattern string or GRegex object + +init (optional):: start offset in the subject (can be negative) + +cf (optional):: compilation flags (bitwise OR) + +ef (optional):: match execution flags (bitwise OR) + +[float] +===== Returns + +The iterator function is called by Lua. On every iteration (that is, on every +match), it returns all captures in the order they appear in the pattern (or the +entire match if the pattern specified no captures). The iteration will continue +till the subject fails to match. + +[[lua_fn_GRegex_gsub_subject__pattern___repl____max____cf____ef__]] + +===== GRegex.gsub(subject, pattern, [repl], [max], [cf], [ef]) + +Searches for all matches of the pattern in the string subject and replaces them +according to the parameters repl and max. The pattern can be a string or a +GRegex object previously compiled with GRegex.new(). + +Since: 1.11.3 + +For details see: +link:http://rrthomas.github.io/lrexlib/manual.html#gsub[http://rrthomas.github.io/lrexlib/manual.html#gsub] + +[float] +===== Arguments + +subject:: Subject string to search + +pattern:: A Perl-compatible regular expression pattern string or GRegex object + +repl (optional):: Substitution source string, function, table, false or nil + +max (optional):: Maximum number of matches to search for, or control function, or nil + +cf (optional):: Compilation flags (bitwise OR) + +ef (optional):: Match execution flags (bitwise OR) + +[float] +===== Returns + +On success, returns the subject string with the substitutions made, the number +of matches found, and the number of substitutions made. + +[[lua_fn_GRegex_split_subject__sep___cf____ef__]] + +===== GRegex.split(subject, sep, [cf], [ef]) + +Splits a subject string subj into parts (sections). The sep parameter is a +regular expression pattern representing separators between the sections. The +function is intended for use in the generic for Lua construct. The function +returns an iterator for repeated matching of the pattern sep in the string subj, +subject to flags cf and ef. The sep pattern can be a string or a GRegex object +previously compiled with GRegex.new(). Unlike gmatch, there will always be at +least one iteration pass, even if there are no matches in the subject. + +Since: 1.11.3 + +[float] +===== Arguments + +subject:: Subject string to search + +sep:: A Perl-compatible regular expression pattern string or GRegex object + +cf (optional):: compilation flags (bitwise OR) + +ef (optional):: match execution flags (bitwise OR) + +[float] +===== Returns + +The iterator function is called by Lua. On every iteration, it returns a subject +section (can be an empty string), followed by all captures in the order they +appear in the sep pattern (or the entire match if the sep pattern specified no +captures). If there is no match (this can occur only in the last iteration), +then nothing is returned after the subject section. The iteration will continue +till the end of the subject. + +[[lua_fn_GRegex_version__]] + +===== GRegex.version() + +Returns a returns a string containing the version of the used library. + +Since: 1.11.3 + +[float] +===== Returns + +The version string + +[[lua_fn_gregex_match_subject___init____ef__]] + +===== gregex:match(subject, [init], [ef]) + +Searches for the first match of the regexp pattern in the string subject, +starting from offset init, subject to flags ef. + +Since: 1.11.3 + +[float] +===== Arguments + +subject:: Subject string to search + +init (optional):: start offset in the subject (can be negative) + +ef (optional):: match execution flags (bitwise OR) + +[float] +===== Returns + +On success, returns all substring matches (``captures''), in the order they appear +in the pattern. false is returned for sub-patterns that did not participate in +the match. If the pattern specified no captures then the whole matched substring +is returned. nil is returned if the pattern did not match. + +[[lua_fn_gregex_find_subject___init____ef__]] + +===== gregex:find(subject, [init], [ef]) + +Searches for the first match of the regexp pattern in the string subject, +starting from offset init, subject to flags ef. + +Since: 1.11.3 + +[float] +===== Arguments + +subject:: Subject string to search + +init (optional):: start offset in the subject (can be negative) + +ef (optional):: match execution flags (bitwise OR) + +[float] +===== Returns + +On success, returns the start point of the match (a number), the end point of +the match (a number), and all substring matches ("captures"), in the order they +appear in the pattern. false is returned for sub-patterns that did not +participate in the match. On failure, returns nil. + +[[lua_fn_gregex_exec_subject___init____ef__]] + +===== gregex:exec(subject, [init], [ef]) + +Searches for the first match of the compiled GRegex object in the string +subject, starting from offset init, subject to the execution match flags ef. + +Since: 1.11.3 + +[float] +===== Arguments + +subject:: Subject string to search + +init (optional):: start offset in the subject (can be negative) + +ef (optional):: match execution flags (bitwise OR) + +[float] +===== Returns + +On success, returns the start point of the first match (a number), the end point +of the first match (a number), and the offsets of substring matches (``captures'' +in Lua terminology) are returned as a third result, in a table. This table +contains false in the positions where the corresponding sub-pattern did not +participate in the match. On failure, returns nil. Example: If the whole match +is at offsets 10,20 and substring matches are at offsets 12,14 and 16,19 then +the function returns the following: 10, 20, { 12,14,16,19 }. + +[[lua_fn_gregex_dfa_exec_subject___init____ef__]] + +===== gregex:dfa_exec(subject, [init], [ef]) + +Matches a compiled regular expression GRegex object against a given subject +string subj, using a DFA matching algorithm. + +Since: 1.11.3 + +[float] +===== Arguments + +subject:: Subject string to search + +init (optional):: start offset in the subject (can be negative) + +ef (optional):: match execution flags (bitwise OR) + +[float] +===== Returns + +On success, returns the start point of the matches found (a number), a table +containing the end points of the matches found, the longer matches first, and +the number of matches found as the third return value. On failure, returns nil. +Example: If there are 3 matches found starting at offset 10 and ending at +offsets 15, 20 and 25 then the function returns the following: 10, { 25,20,15 }, +3 + +[[lua_fn_gregex___tostring__]] + +===== gregex:__tostring() + +Returns a string containing debug information about the GRegex object. + +Since: 1.11.3 + +[float] +===== Returns + +The debug string diff --git a/docbook/wsluarm.xml b/docbook/wsluarm.xml deleted file mode 100644 index 6e6c58b5f4..0000000000 --- a/docbook/wsluarm.xml +++ /dev/null @@ -1,713 +0,0 @@ - - Lua Support in Wireshark -
- Introduction - - Wireshark has an embedded Lua interpreter. Lua is a powerful light-weight - programming language designed for extending applications. Lua is designed - and implemented by a team at PUC-Rio, the Pontifical Catholic University - of Rio de Janeiro in Brazil. Lua was born and raised at Tecgraf, the - Computer Graphics Technology Group of PUC-Rio, and is now housed at - Lua.org. - Both Tecgraf and Lua.org are laboratories of the Department of Computer Science. - - - In Wireshark Lua can be used to write dissectors, taps, and capture file readers and writers. - - - Wireshark's Lua interpreter starts by loading init.lua that - is located in the global configuration directory of Wireshark. - Lua is enabled by default. To disable Lua the line variable disable_lua - should be set to true in init.lua. - - - After loading init.lua from the data directory if Lua is enabled - Wireshark will try to load a file named init.lua in the user's - directory. - - - Wireshark will also load all files with .lua suffix from both the - global and the personal plugins directory. - - - The command line option -X lua_script:<file.lua> can be used to - load Lua scripts as well. - - - The Lua code will be executed once after all the protocol dissectors have being initialized - and before reading any file. - -
-
- Example of Dissector written in Lua -local p_multi = Proto("multi","MultiProto"); - -local vs_protos = { - [2] = "mtp2", - [3] = "mtp3", - [4] = "alcap", - [5] = "h248", - [6] = "ranap", - [7] = "rnsap", - [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") - -p_multi.fields = { f_proto, f_dir, f_text } - -local data_dis = Dissector.get("data") - -local protos = { - [2] = Dissector.get("mtp2"), - [3] = Dissector.get("mtp3"), - [4] = Dissector.get("alcap"), - [5] = Dissector.get("h248"), - [6] = Dissector.get("ranap"), - [7] = Dissector.get("rnsap"), - [8] = Dissector.get("nbap"), - [9] = Dissector.get("rrc"), - [10] = DissectorTable.get("sctp.ppi"):get_dissector(3), -- m3ua - [11] = DissectorTable.get("ip.proto"):get_dissector(132), -- sctp -} - -function p_multi.dissector(buf,pkt,root) - - local t = root:add(p_multi,buf(0,2)) - t:add(f_proto,buf(0,1)) - t: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) - elseif proto_id < 2 then - t:add(f_text,buf(2)) - -- pkt.cols.info:set(buf(2,buf:len() - 3):string()) - else - data_dis:call(buf(2):tvb(),pkt,root) - end - -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) -
-
- Example of Listener written in Lua - -- This program will register a menu that will open a window with a count of occurrences --- of every address in the capture - -local function menuable_tap() - -- Declare the window we will use - local tw = TextWindow.new("Address Counter") - - -- This will contain a hash of counters of appearances of a certain address - local ips = {} - - -- this is our tap - local tap = Listener.new(); - - function remove() - -- this way we remove the listener that otherwise will remain running indefinitely - tap:remove(); - end - - -- we tell the window to call the remove() function when closed - tw:set_atclose(remove) - - -- this function will be called once for each packet - function tap.packet(pinfo,tvb) - local src = ips[tostring(pinfo.src)] or 0 - local dst = ips[tostring(pinfo.dst)] or 0 - - ips[tostring(pinfo.src)] = src + 1 - ips[tostring(pinfo.dst)] = dst + 1 - end - - -- this function will be called once every few seconds to update our window - function tap.draw(t) - tw:clear() - for ip,num in pairs(ips) do - tw:append(ip .. "\t" .. num .. "\n"); - end - end - - -- this function will be called whenever a reset is needed - -- e.g. when reloading the capture file - function tap.reset() - tw:clear() - ips = {} - end -end - --- using this function we register our function --- to be called when the user selects the Tools->Test->Packets menu -register_menu("Test/Packets", menuable_tap, MENU_TOOLS_UNSORTED) -
-
- Wireshark's Lua API Reference Manual - - This Part of the User Guide describes the Wireshark specific functions in the embedded Lua. - -
- &WsLuaDumper; - &WsLuaField; - &WsLuaGui; - &WsLuaListener; - &WsLuaPinfo; - &WsLuaProto; - &WsLuaTree; - &WsLuaTvb; - &WsLuaFile; - &WsLuaDir; - &WsLuaUtility; - &WsLuaInt64; - &WsLuaStruct; - -
- GLib Regular Expressions - - Lua has its own native 'pattern' syntax in the string library, but sometimes a real - regex engine is more useful. Wireshark comes with GLib's Regex implementation, which - itself is based on Perl Compatible Regular Expressions (PCRE). This engine is exposed - into Wireshark's Lua engine through the well-known Lrexlib library, following the - same syntax and semantics as the Lrexlib PCRE implementation, with a few differences as follows: - - - There is no support for using custom locale/chartables - - - dfa_exec() doesn't take 'ovecsize' nor 'wscount' arguments - - - dfa_exec() returns boolean true for partial match, without subcapture info - - - Named subgroups do not return name-keyed entries in the return - table (i.e., in match/tfind/exec) - - - - The 'flags()' function still works, returning all flags, but two new - functions 'compile_flags()' and 'match_flags()' return just their respective - flags, since GLib has a different and smaller set of such flags, for - regex compile vs. match functions - - - - - Using some assertions and POSIX character classes against strings with non-ASCII characters - might match high-order characters, because glib always sets PCRE_UCP - even if G_REGEX_RAW is set. For example, '[:alpha;]' matches certain - non-ASCII bytes. The following assertions have this issue: '\b', '\B', '\s', '\S', '\w', '\W'. - The following character classes have this issue: [:alpha:], [:alnum:], [:lower:], [:upper:], - [:space:], [:word:], and [:graph:]. - - - - - The compile flag G_REGEX_RAW is always set/used, even if you didn't specify it. This is because - GLib runs PCRE in UTF-8 mode by default, whereas Lua strings are not UTF-aware. - - - - - - Since: 1.11.3 - - - This page is based on the full documentation for Lrexlib at - http://rrthomas.github.io/lrexlib/manual.html - - - The GLib Regular expression syntax (which is essentially PCRE syntax) can be found at - https://developer.gnome.org/glib/2.38/glib-regex-syntax.html - -
GRegex - - GLib Regular Expressions based on PCRE. - - - Since: 1.11.3 - -
Notes - - All functions that take a regular expression pattern as an argument will - generate an error if that pattern is found invalid by the regex library. - - - All functions that take a string-type regex argument accept a compiled regex - too. In this case, the compile flags argument is ignored (should be either supplied as nils or omitted). - - - The capture flag argument 'cf' may also be supplied as a string, whose characters stand for compilation flags. - Combinations of the following characters (case sensitive) are supported: - - - 'i' = G_REGEX_CASELESS - Letters in the pattern match both upper- and lowercase letters. - This option can be changed within a pattern by a "(?i)" option setting. - - - 'm' = G_REGEX_MULTILINE - By default, GRegex treats the strings as consisting of a single - line of characters (even if it actually contains newlines). The "start of line" - metacharacter ("^") matches only at the start of the string, while the "end of line" - metacharacter ("$") matches only at the end of the string, or before a terminating newline - (unless G_REGEX_DOLLAR_ENDONLY is set). When G_REGEX_MULTILINE is set, the "start of line" - and "end of line" constructs match immediately following or immediately before any newline - in the string, respectively, as well as at the very start and end. This can be changed - within a pattern by a "(?m)" option setting. - - - 's' = G_REGEX_DOTALL - A dot metacharater (".") in the pattern matches all characters, - including newlines. Without it, newlines are excluded. This option can be changed within - a pattern by a ("?s") option setting. - - - 'x' = G_REGEX_EXTENDED - Whitespace data characters in the pattern are totally ignored - except when escaped or inside a character class. Whitespace does not include the VT - character (code 11). In addition, characters between an unescaped "#" outside a character - class and the next newline character, inclusive, are also ignored. This can be changed - within a pattern by a "(?x)" option setting. - - - 'U' = G_REGEX_UNGREEDY - Inverts the "greediness" of the quantifiers so that they are not - greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" - option setting within the pattern. - - - -
-
- GRegex.new(pattern) - Compiles regular expression pattern into a regular expression object whose - internal representation is corresponding to the library used. The returned - result then can be used by the methods, e.g. match, exec, etc. Regular - expression objects are automatically garbage collected. - - - Since: 1.11.3 - -
Arguments - - pattern - A Perl-compatible regular expression pattern string - - -
-
Returns - The compiled regular expression (a userdata object) -
-
Errors - - A malformed pattern generates a Lua error - -
-
-
- GRegex.flags([table]) - Returns a table containing the numeric values of the constants defined by - the regex library, with the keys being the (string) names of the - constants. If the table argument is supplied then it is used as the - output table, otherwise a new table is created. The constants contained - in the returned table can then be used in most functions and methods where - compilation flags or execution flags can be specified. They can also be - used for comparing with return codes of some functions and methods for - determining the reason of failure. - - - Since: 1.11.3 - -
Arguments - - table (optional) - A table for placing results into - - -
-
Returns - A table filled with the results. -
-
-
- GRegex.compile_flags([table]) - Returns a table containing the numeric values of the constants defined by - the regex library for compile flags, with the keys being the (string) names of the - constants. If the table argument is supplied then it is used as the - output table, otherwise a new table is created. - - - Since: 1.11.3 - -
Arguments - - table (optional) - A table for placing results into - - -
-
Returns - A table filled with the results. -
-
-
- GRegex.match_flags([table]) - Returns a table containing the numeric values of the constants defined by - the regex library for match flags, with the keys being the (string) names of the - constants. If the table argument is supplied then it is used as the - output table, otherwise a new table is created. - - - Since: 1.11.3 - -
Arguments - - table (optional) - A table for placing results into - - -
-
Returns - A table filled with the results. -
-
-
- GRegex.match(subject, pattern, [init], [cf], [ef]) - Searches for the first match of the regexp pattern in the string subject, starting - from offset init, subject to flags cf and ef. The pattern is compiled each time this is - called, unlike the class method 'match' function. - - - Since: 1.11.3 - -
Arguments - - subject - Subject string to search - - pattern - A Perl-compatible regular expression pattern string or GRegex object - - init (optional) - start offset in the subject (can be negative) - - cf (optional) - compilation flags (bitwise OR) - - ef (optional) - match execution flags (bitwise OR) - - -
-
Returns - On success, returns all substring matches ("captures"), in the order they appear in the pattern. - false is returned for sub-patterns that did not participate in the match. If - the pattern specified no captures then the whole matched substring is - returned. On failure, returns nil. - -
-
-
- GRegex.find(subject, pattern, [init], [cf], [ef]) - Searches for the first match of the regexp pattern in the string subject, starting - from offset init, subject to flags ef. The pattern is compiled each time this is - called, unlike the class method 'find' function. - - - Since: 1.11.3 - -
Arguments - - subject - Subject string to search - - pattern - A Perl-compatible regular expression pattern string or GRegex object - - init (optional) - start offset in the subject (can be negative) - - cf (optional) - compilation flags (bitwise OR) - - ef (optional) - match execution flags (bitwise OR) - - -
-
Returns - On success, returns the start point of the match (a number), the - end point of the match (a number), and all substring matches ("captures"), in - the order they appear in the pattern. false is returned for sub-patterns that did - not participate in the match. On failure, returns nil. - -
-
-
- GRegex.gmatch(subject, pattern, [init], [cf], [ef]) - Returns an iterator for repeated matching of the pattern patt in the string subj, subject - to flags cf and ef. The function is intended for use in the generic for Lua construct. - The pattern can be a string or a GRegex object previously compiled with GRegex.new(). - - - Since: 1.11.3 - -
Arguments - - subject - Subject string to search - - pattern - A Perl-compatible regular expression pattern string or GRegex object - - init (optional) - start offset in the subject (can be negative) - - cf (optional) - compilation flags (bitwise OR) - - ef (optional) - match execution flags (bitwise OR) - - -
-
Returns - The iterator function is called by Lua. On every iteration (that is, on every - match), it returns all captures in the order they appear in the pattern (or - the entire match if the pattern specified no captures). The iteration will - continue till the subject fails to match. - -
-
-
- GRegex.gsub(subject, pattern, [repl], [max], [cf], [ef]) - Searches for all matches of the pattern in the string subject and replaces them according - to the parameters repl and max. - The pattern can be a string or a GRegex object previously compiled with GRegex.new(). - - - Since: 1.11.3 - - For details see: - http://rrthomas.github.io/lrexlib/manual.html#gsub - -
Arguments - - subject - Subject string to search - - pattern - A Perl-compatible regular expression pattern string or GRegex object - - repl (optional) - Substitution source string, function, table, false or nil - - max (optional) - Maximum number of matches to search for, or control function, or nil - - cf (optional) - Compilation flags (bitwise OR) - - ef (optional) - Match execution flags (bitwise OR) - - -
-
Returns - On success, returns the subject string with the substitutions made, - the number of matches found, and the number of substitutions made. - -
-
-
- GRegex.split(subject, sep, [cf], [ef]) - Splits a subject string subj into parts (sections). The sep parameter - is a regular expression pattern representing separators between the sections. - The function is intended for use in the generic for Lua construct. - The function returns an iterator for repeated matching of the pattern sep in - the string subj, subject to flags cf and ef. - The sep pattern can be a string or a GRegex object previously compiled with GRegex.new(). - Unlike gmatch, there will always be at least one iteration pass, even if there are no matches in the subject. - - - Since: 1.11.3 - -
Arguments - - subject - Subject string to search - - sep - A Perl-compatible regular expression pattern string or GRegex object - - cf (optional) - compilation flags (bitwise OR) - - ef (optional) - match execution flags (bitwise OR) - - -
-
Returns - The iterator function is called by Lua. On every iteration, it returns - a subject section (can be an empty string), followed by all captures in the order they - appear in the sep pattern (or the entire match if the sep pattern specified no captures). - If there is no match (this can occur only in the last iteration), then nothing is - returned after the subject section. The iteration will continue till the end of the subject. - -
-
-
- GRegex.version() - Returns a returns a string containing the version of the used library. - - Since: 1.11.3 - -
Returns - The version string -
-
-
- gregex:match(subject, [init], [ef]) - Searches for the first match of the regexp pattern in the string subject, starting - from offset init, subject to flags ef. - - - Since: 1.11.3 - -
Arguments - - subject - Subject string to search - - init (optional) - start offset in the subject (can be negative) - - ef (optional) - match execution flags (bitwise OR) - - -
-
Returns - On success, returns all substring matches ("captures"), in the order they appear in the pattern. - false is returned for sub-patterns that did not participate in the match. If - the pattern specified no captures then the whole matched substring is - returned. nil is returned if the pattern did not match. - -
-
-
- gregex:find(subject, [init], [ef]) - Searches for the first match of the regexp pattern in the string subject, starting - from offset init, subject to flags ef. - - - Since: 1.11.3 - -
Arguments - - subject - Subject string to search - - init (optional) - start offset in the subject (can be negative) - - ef (optional) - match execution flags (bitwise OR) - - -
-
Returns - On success, returns the start point of the match (a number), the - end point of the match (a number), and all substring matches ("captures"), in - the order they appear in the pattern. false is returned for sub-patterns that did - not participate in the match. On failure, returns nil. - -
-
-
- gregex:exec(subject, [init], [ef]) - Searches for the first match of the compiled GRegex object in the string subject, starting - from offset init, subject to the execution match flags ef. - - - Since: 1.11.3 - -
Arguments - - subject - Subject string to search - - init (optional) - start offset in the subject (can be negative) - - ef (optional) - match execution flags (bitwise OR) - - -
-
Returns - On success, returns the start point of the first match (a number), the - end point of the first match (a number), and the offsets of substring matches ("captures" - in Lua terminology) are returned as a third result, in a table. This table contains false - in the positions where the corresponding sub-pattern did not participate in the match. - On failure, returns nil. - Example: - If the whole match is at offsets 10,20 and substring matches are at offsets 12,14 and 16,19 - then the function returns the following: 10, 20, { 12,14,16,19 }. - -
-
-
- gregex:dfa_exec(subject, [init], [ef]) - Matches a compiled regular expression GRegex object against a given subject string subj, using a DFA matching algorithm. - - Since: 1.11.3 - -
Arguments - - subject - Subject string to search - - init (optional) - start offset in the subject (can be negative) - - ef (optional) - match execution flags (bitwise OR) - - -
-
Returns - On success, returns the start point of the matches found (a number), a - table containing the end points of the matches found, the longer matches first, and the - number of matches found as the third return value. - On failure, returns nil. - Example: - If there are 3 matches found starting at offset 10 and ending at offsets 15, 20 and 25 - then the function returns the following: 10, { 25,20,15 }, 3 - -
-
-
- gregex:__tostring() - Returns a string containing debug information about the GRegex object. - - Since: 1.11.3 - -
Returns - The debug string -
-
-
-
- - - diff --git a/docbook/wsug_src/WSUG_chapter_use.asciidoc b/docbook/wsug_src/WSUG_chapter_use.asciidoc index 5faed769d3..d9a0cc50a1 100644 --- a/docbook/wsug_src/WSUG_chapter_use.asciidoc +++ b/docbook/wsug_src/WSUG_chapter_use.asciidoc @@ -512,7 +512,7 @@ image::wsug_graphics/ws-tools-menu.png[] It is assumed that the rules will be applied to an outside interface. -|menu:Lua[]|| These options allow you to work with the Lua interpreter optionally build into Wireshark, see <>. +|menu:Lua[]|| These options allow you to work with the Lua interpreter optionally build into Wireshark. See the ``Lua Support in Wireshark'' in the Wireshark Developer's Guide. |=============== [[ChUseInternalsMenuSection]] diff --git a/epan/wslua/wslua_int64.c b/epan/wslua/wslua_int64.c index 8cb79b755d..6c08373184 100644 --- a/epan/wslua/wslua_int64.c +++ b/epan/wslua/wslua_int64.c @@ -607,7 +607,7 @@ LUALIB_API int Int64_register(lua_State* L) { WSLUA_CLASS_DEFINE_BASE(UInt64,NOP,NOP,0); /* `UInt64` represents a 64 bit unsigned integer, similar to `Int64`. - For details, see: http://wiki.wireshark.org/LuaAPI/`Int64`. + For details, see: [[http://wiki.wireshark.org/LuaAPI/Int64]]. */ /* A checkUInt64 but that also auto-converts numbers, strings, and `Int64` to a guint64. */ diff --git a/epan/wslua/wslua_struct.c b/epan/wslua/wslua_struct.c index e6b5471eb9..a05d69760d 100644 --- a/epan/wslua/wslua_struct.c +++ b/epan/wslua/wslua_struct.c @@ -118,36 +118,36 @@ The supported elements in the format string are as follows: - * "` `" (empty space) ignored. - * "`!`n" flag to set the current alignment requirement to 'n' (necessarily a power of 2); + * `$$ $$' (empty space) ignored. + * `++!++__n__' flag to set the current alignment requirement to 'n' (necessarily a power of 2); an absent 'n' means the machine's native alignment. - * "`>`" flag to set mode to big endian (i.e., network-order). - * "`<`" flag to set mode to little endian. - * "`x`" a padding zero byte with no corresponding Lua value. - * "`b`" a signed char. - * "`B`" an unsigned char. - * "`h`" a signed short (native size). - * "`H`" an unsigned short (native size). - * "`l`" a signed long (native size). - * "`L`" an unsigned long (native size). - * "`T`" a size_t (native size). - * "`i`n" a signed integer with 'n' bytes. An absent 'n' means the native size of an int. - * "`I`n" like "`i`n" but unsigned. - * "`e`" signed 8-byte Integer (64-bits, long long), to/from a `Int64` object. - * "`E`" unsigned 8-byte Integer (64-bits, long long), to/from a `UInt64` object. - * "`f`" a float (native size). - * "`d`" a double (native size). - * "`s`" a zero-terminated string. - * "`c`n" a sequence of exactly 'n' chars corresponding to a single Lua string. An absent 'n' + * `++>++' flag to set mode to big endian (i.e., network-order). + * `++<++' flag to set mode to little endian. + * `++x++' a padding zero byte with no corresponding Lua value. + * `++b++' a signed char. + * `++B++' an unsigned char. + * `++h++' a signed short (native size). + * `++H++' an unsigned short (native size). + * `++l++' a signed long (native size). + * `++L++' an unsigned long (native size). + * `++T++' a size_t (native size). + * `++i++__n__' a signed integer with 'n' bytes. An absent 'n' means the native size of an int. + * `++I++__n__' like `++i++__n__' but unsigned. + * `++e++' signed 8-byte Integer (64-bits, long long), to/from a +Int64+ object. + * `++E++' unsigned 8-byte Integer (64-bits, long long), to/from a +UInt64+ object. + * `++f++' a float (native size). + * `++d++' a double (native size). + * `++s++' a zero-terminated string. + * `++c++__n__' a sequence of exactly 'n' chars corresponding to a single Lua string. An absent 'n' means 1. When packing, the given string must have at least 'n' characters (extra characters are discarded). - * "`c0`" this is like "`c`n", except that the 'n' is given by other means: When packing, 'n' is + * `++c0++' this is like `++c++__n__', except that the 'n' is given by other means: When packing, 'n' is the length of the given string; when unpacking, 'n' is the value of the previous unpacked value (which must be a number). In that case, this previous value is not returned. - * "`x`n" pad to 'n' number of bytes, default 1. - * "`X`n" pad to 'n' alignment, default MAXALIGN. - * "`(`" to stop assigning items, and "`)`" start assigning (padding when packing). - * "`=`" to return the current position / offset. + * `++x++__n__' pad to 'n' number of bytes, default 1. + * `++X++__n__' pad to 'n' alignment, default MAXALIGN. + * `++(++' to stop assigning items, and `++)++' start assigning (padding when packing). + * `++=++' to return the current position / offset. @note Using `i`, `I`, `h`, `H`, `l`, `L`, `f`, and `T` is strongly discouraged, as those sizes are system-dependent. Use the explicitly sized variants instead, such as `i4` or `E`. diff --git a/epan/wslua/wslua_tree.c b/epan/wslua/wslua_tree.c index 8e6c334fa3..141229611a 100644 --- a/epan/wslua/wslua_tree.c +++ b/epan/wslua/wslua_tree.c @@ -49,8 +49,8 @@ TreeItem* push_TreeItem(lua_State*L, TreeItem t) { CLEAR_OUTSTANDING(TreeItem, expired, TRUE) WSLUA_CLASS_DEFINE(TreeItem,FAIL_ON_NULL_OR_EXPIRED("TreeItem"),NOP); -/* `TreeItem`s represent information in the packet-details pane. - A root `TreeItem` is passed to dissectors as the third argument. */ +/* ++TreeItem++s represent information in the packet-details pane. + A root +TreeItem+ is passed to dissectors as the third argument. */ /* the following is used by TreeItem_add_packet_field() - this can THROW errors */ static proto_item * diff --git a/epan/wslua/wslua_tvb.c b/epan/wslua/wslua_tvb.c index 2e129ade98..7c02a8cfd2 100644 --- a/epan/wslua/wslua_tvb.c +++ b/epan/wslua/wslua_tvb.c @@ -382,7 +382,7 @@ WSLUA_CLASS_DEFINE(Tvb,FAIL_ON_NULL_OR_EXPIRED("Tvb"),NOP); To create a `TvbRange` the `Tvb` must be called with offset and length as optional arguments; the offset defaults to 0 and the length to `tvb:len()`. - @warning `Tvb`s are usable only by the current listener or dissector call and are destroyed + @warning Tvbs are usable only by the current listener or dissector call and are destroyed as soon as the listener/dissector returns, so references to them are unusable once the function has returned. */