osmith
/
wireshark
forked from osmocom/wireshark
1
0
Fork 0
Code Pull Requests Releases Wiki Activity

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 <gerald@wireshark.org>
This commit is contained in:
Gerald Combs 2014-11-02 13:20:08 -08:00 committed by Gerald Combs
parent 502085662f
commit 04aad36c0e
16 changed files with 838 additions and 929 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docbook/CMakeLists.txt
View File

@ -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

4
docbook/GPL_appendix.asciidoc
View File

@ -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.
----
----

22
docbook/Makefile.am
View File

@ -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 $< > $@

2
docbook/Makefile.common
View File

@ -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 = \

24
docbook/Makefile.nmake
View File

@ -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

7
docbook/developer-guide-docinfo.xml
View File

@ -20,6 +20,13 @@
<revhistory>
<revision>
<revnumber>1.0</revnumber>
<date>2 Nov 2014</date>
<authorinitials>gcc</authorinitials>
<revremark>Moved Lua reference from User's Guide to Developer's Guide.</revremark>
</revision>
<revision>
<revnumber>0.9</revnumber>
<date>9 Feb 2014</date>

2
docbook/developer-guide.asciidoc
View File

@ -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[]

218
docbook/make-wsluarm.pl
View File

@ -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/&/&amp;/msg; # do this one first so we don't clobber later ones
$s =~ s/\</&lt;/msg;
$s =~ s/\>/&gt;/msg;
# bold and italics - but don't change a star followed by space (it's a list item)
$s =~ s/(\*\*)([^*]+?)(\*\*)/<command>$2<\/command>/g; # bold=command??
$s =~ s/(\*)([^\s][^*]*?)(\*)/<emphasis>$2<\/emphasis>/g; # italics
$s =~ s/(\*\*)([^*]+?)(\*\*)/`$2`/g; # bold=command??
# one backtick is quote/command
$s =~ s/([^`]|^)(`)([^`]+?)(`)/$1<command>$3<\/command>/g; # quote=command??
# two backticks are one
$s =~ s/(``)([^`]+?)(``)/`$2`/g; # quote=command??
#$s =~ s/([^`]|^)(`)([^`]+?)(`)/$1<command>$3<\/command>/g; # quote=command??
# two backticks are one (...and don't appear anywhere?)
#$s =~ s/(``)([^`]+?)(``)/`$2`/g; # quote=command??
# handle '[[url]]'
$s =~ s/(\[\[)([^\]\|]+?)(\]\])/<ulink url="$2">$2<\/ulink>/g;
# Convert wiki-style '[[url]]'
$s =~ s/(\[\[)([^\]\|]+?)(\]\])/link:\$\$$2\$\$:[$2]/g;
# handle '[[url|pretty]]'
$s =~ s/(\[\[)(([^\]\|]+?)\|\s*([^\]]+?))(\]\])/<ulink url="$3">$4<\/ulink>/g;
# unescape gorolla'd ampersands in url
while ($s =~ /<ulink url="[^"]*&amp;/) {
$s =~ s/(<ulink url="[^"]*)(&amp;)/$1\&/;
}
$s =~ s/(\[\[)(([^\]\|]+?)\|\s*([^\]]+?))(\]\])/link:\$\$$3\$\$:[$4]/g;
$s;
}
@ -113,7 +109,6 @@ sub parse_desc_common {
# capitalize the first letter of the first line
$lines[0] = ucfirst($lines[0]);
# for each double newline, break into separate para's
$r[++$#r] = "<para>\n";
for (my $idx=0; $idx <= $#lines; $idx++) {
$lines[$idx] =~ s/^(\s*)//; # remove leading whitespace
@ -123,137 +118,95 @@ sub parse_desc_common {
# if we find @code then treat it as a blob
if ($lines[$idx] =~ /^\@code\b/) {
my $line = $lines[$idx];
$line =~ s/\@code/<programlisting language="lua">/;
$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] = "</para>\n";
$r[++$#r] = "<para>\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 <note>
# If line starts with "Note:" or "@note", make it an admonition
if ($line =~ /^[nN]ote:|^\@note /) {
$r[++$#r] = "</para>\n";
$r[++$#r] = "<note>\n";
$r[++$#r] = "\t<para>\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</para>\n";
$r[++$#r] = "</note>\n";
$r[++$#r] = "<para>\n";
$r[++$#r] = "====\n\n";
# if line starts with "Warning:"" or @warning", make it an XML <warning>
# If line starts with "Warning:"" or @warning", make it an admonition
} elsif ($line =~ /^[wW]arning:|^\@warning /) {
$r[++$#r] = "</para>\n";
$r[++$#r] = "<warning>\n";
$r[++$#r] = "\t<para>\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</para>\n";
$r[++$#r] = "</warning>\n";
$r[++$#r] = "<para>\n";
$r[++$#r] = "====\n";
# if line starts with "@version" or "@since", make it a "Since:"
} elsif ($line =~ /^\@version |^\@since /) {
$r[++$#r] = "</para>\n";
$r[++$#r] = "<para>\n";
$line =~ s/^\@version\s+|^\@since\s+/Since: /;
$r[++$#r] = "\t" . $line . "\n";
$r[++$#r] = "</para>\n";
$r[++$#r] = "<para>\n";
$r[++$#r] = "\n" . $line . "\n\n";
# if line starts with single "*" and space, make it an XML <itemizedlist>
# if line starts with single "*" and space, leave it mostly intact.
} elsif ($line =~ /^\*\s/) {
$r[++$#r] = "</para>\n";
$r[++$#r] = "<itemizedlist>\n";
$r[++$#r] = "\t<listitem>\n";
$r[++$#r] = "\t\t<para>\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</para>\n";
$r[++$#r] = "\t</listitem>\n";
$r[++$#r] = "\t<listitem>\n";
$r[++$#r] = "\t\t<para>\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</para>\n";
$r[++$#r] = "\t</listitem>\n";
$r[++$#r] = "</itemizedlist>\n";
$r[++$#r] = "<para>\n";
$r[++$#r] = "\n\n";
# if line starts with "1." and space, make it an XML <orderedlist>
# if line starts with "1." and space, leave it mostly intact.
} elsif ($line =~ /^1\.\s/) {
$r[++$#r] = "</para>\n";
$r[++$#r] = "<orderedlist>\n";
$r[++$#r] = "\t<listitem>\n";
$r[++$#r] = "\t\t<para>\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</para>\n";
$r[++$#r] = "\t</listitem>\n";
$r[++$#r] = "\t<listitem>\n";
$r[++$#r] = "\t\t<para>\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</para>\n";
$r[++$#r] = "\t</listitem>\n";
$r[++$#r] = "</orderedlist>\n";
$r[++$#r] = "<para>\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] = "</para>\n";
$r[++$#r] = "\n\n";
# now go through @r, and copy into @ret but skip empty
# paragraphs (ie, <para> followed by </para>)
# 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] =~ /^<para>\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] = "<title>$line</title>\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 = ( "<listitem>\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] = "</listitem>\n";
#$r[++$#r] = "</listitem>\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] = "<para>Mode: $mode</para>\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 => "<section id='lua_module_%s'>\n",
my $asciidoc_template = {
module_header => "[[lua_module_%s]]\n\n",
# module_desc => "\t<title>%s</title>\n",
class_header => "\t<section id='lua_class_%s'>\n" .
"\t\t<title>%s</title>\n",
class_header => "[[lua_class_%s]]\n\n" .
"==== %s\n\n",
#class_desc => "\t\t<para>%s</para>\n",
class_attr_header => "\t\t<section id='lua_class_attrib_%s'>\n" .
"\t\t\t<title>%s</title>\n",
class_attr_header => "[[lua_class_attrib_%s]]\n\n" .
"==== %s\n\n",
#class_attr_descr => "\t\t\t<para>%s%s</para>\n",
class_attr_footer => "\t\t</section> <!-- class_attr_footer: %s -->\n",
function_header => "\t\t<section id='lua_fn_%s'>\n" .
"\t\t\t<title>%s</title>\n",
class_attr_footer => "// End %s\n\n",
function_header => "[[lua_fn_%s]]\n\n" .
"===== %s\n\n",
#function_descr => "\t\t\t<para>%s</para>\n",
function_args_header => "\t\t\t<section>\n" .
"\t\t\t\t<title>Arguments</title>\n" .
"\t\t\t\t<variablelist>\n",
function_arg_header => "\t\t\t\t\t<varlistentry>\n" .
"\t\t\t\t\t\t<term>%s</term>\n",
function_args_header => "[float]\n" .
"===== Arguments\n\n",
function_arg_header => "%s::\n",
#function_arg_descr => "\t\t\t\t\t\t<listitem>\n" .
# "\t\t\t\t\t\t\t<para>%s</para>\n" .
# "\t\t\t\t\t\t</listitem>\n",
function_arg_footer => "\t\t\t\t\t</varlistentry> <!-- function_arg_footer: %s -->\n",
function_args_footer => "\t\t\t\t</variablelist>\n" .
"\t\t\t</section> <!-- end of function_args -->\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<section><title>Errors</title>\n\t\t\t\t\t\t<itemizedlist>\n",
function_argerror => "", #"\t\t\t\t\t\t\t<listitem><para>%s</para></listitem>\n",
function_argerror_footer => "", #"\t\t\t\t\t\t</itemizedlist></section> <!-- function_argerror_footer: %s -->\n",
function_returns_header => "\t\t\t<section>\n" .
"\t\t\t\t<title>Returns</title>\n",
function_returns => "\t\t\t\t<para>%s</para>\n",
function_returns_footer => "\t\t\t</section> <!-- function_returns_footer: %s -->\n",
function_errors_header => "\t\t\t<section>\n" .
"\t\t\t\t<title>Errors</title>\n" .
"\t\t\t\t<itemizedlist>\n",
function_errors => "\t\t\t\t\t<listitem>\n" .
"\t\t\t\t\t\t<para>%s</para>\n" .
"\t\t\t\t\t</listitem>\n",
function_errors_footer => "\t\t\t\t</itemizedlist>\n" .
"\t\t\t</section> <!-- function_errors_footer: %s -->\n",
function_footer => "\t\t</section> <!-- function_footer: %s -->\n",
class_footer => "\t</section> <!-- class_footer: %s -->\n",
global_functions_header => "\t<section id='global_functions_%s'>\n" .
"\t\t<title>Global Functions</title>\n",
global_functions_footer => "\t</section> <!-- Global function -->\n",
module_footer => "</section> <!-- end of module -->\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<section id='lua_class_constructors_%s'>\n\t\t\t<title>%s Constructors</title>\n",
@ -403,8 +349,8 @@ my $docbook_template = {
# class_methods_footer => "\t\t</section> <!-- class_methods_footer: %s -->\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

21
docbook/user-guide.xml
View File

@ -329,25 +329,6 @@ FILE SECTION
<!ENTITY AppHowItWorks SYSTEM "wsug_src/WSUG_app_howitworks.xml">
<!ENTITY AppTools SYSTEM "wsug_src/WSUG_app_tools.xml">
<!ENTITY AppGPL SYSTEM "GPL_appendix.xml">
<!--
WSLua Reference Manual
-->
<!ENTITY WsLuaRm SYSTEM "wsluarm.xml">
<!ENTITY WsLuaDumper SYSTEM "wsluarm_src/wslua_dumper.xml">
<!ENTITY WsLuaField SYSTEM "wsluarm_src/wslua_field.xml">
<!ENTITY WsLuaGui SYSTEM "wsluarm_src/wslua_gui.xml">
<!ENTITY WsLuaListener SYSTEM "wsluarm_src/wslua_listener.xml">
<!ENTITY WsLuaPinfo SYSTEM "wsluarm_src/wslua_pinfo.xml">
<!ENTITY WsLuaProto SYSTEM "wsluarm_src/wslua_proto.xml">
<!ENTITY WsLuaTree SYSTEM "wsluarm_src/wslua_tree.xml">
<!ENTITY WsLuaTvb SYSTEM "wsluarm_src/wslua_tvb.xml">
<!ENTITY WsLuaFile SYSTEM "wsluarm_src/wslua_file.xml">
<!ENTITY WsLuaDir SYSTEM "wsluarm_src/wslua_dir.xml">
<!ENTITY WsLuaUtility SYSTEM "wsluarm_src/wslua_util.xml">
<!ENTITY WsLuaInt64 SYSTEM "wsluarm_src/wslua_int64.xml">
<!ENTITY WsLuaStruct SYSTEM "wsluarm_src/wslua_struct.xml">
]>
<book>
@ -366,8 +347,6 @@ WSLua Reference Manual
&ChapterTelephony;
&ChapterCustomize;
&WsLuaRm;
&AppFiles;
&AppProtocols;
&AppMessages;

689
docbook/wsluarm.asciidoc Normal file
View File

@ -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

713
docbook/wsluarm.xml
View File

@ -1,713 +0,0 @@
<chapter id="wsluarm">
<title>Lua Support in Wireshark</title>
<section id="wsluarm_intro">
<title>Introduction</title>
<para>
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
<ulink url="http://www.lua.org">Lua.org</ulink>.
Both Tecgraf and Lua.org are laboratories of the Department of Computer Science.
</para>
<para>
In Wireshark Lua can be used to write dissectors, taps, and capture file readers and writers.
</para>
<para>
Wireshark's Lua interpreter starts by loading <command>init.lua</command> that
is located in the global configuration directory of Wireshark.
Lua is enabled by default. To disable Lua the line variable <command>disable_lua</command>
should be set to <command>true</command> in <command>init.lua</command>.
</para>
<para>
After loading <command>init.lua</command> from the data directory if Lua is enabled
Wireshark will try to load a file named <command>init.lua</command> in the user's
directory.
</para>
<para>
Wireshark will also load all files with <command>.lua</command> suffix from both the
global and the personal plugins directory.
</para>
<para>
The command line option <command>-X lua_script:&lt;file.lua&gt;</command> can be used to
load Lua scripts as well.
</para>
<para>
The Lua code will be executed once after all the protocol dissectors have being initialized
and before reading any file.
</para>
</section>
<section id="wslua_dissector_example">
<title>Example of Dissector written in Lua</title>
<programlisting>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 &lt; 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)</programlisting>
</section>
<section id="wslua_tap_example">
<title>Example of Listener written in Lua</title>
<programlisting>-- 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)</programlisting>
</section>
<section id="wsluarm_modules">
<title>Wireshark's Lua API Reference Manual</title>
<para>
This Part of the User Guide describes the Wireshark specific functions in the embedded Lua.
</para>
</section>
&WsLuaDumper;
&WsLuaField;
&WsLuaGui;
&WsLuaListener;
&WsLuaPinfo;
&WsLuaProto;
&WsLuaTree;
&WsLuaTvb;
&WsLuaFile;
&WsLuaDir;
&WsLuaUtility;
&WsLuaInt64;
&WsLuaStruct;
<section id='lua_module_GRegex'>
<title> GLib Regular Expressions </title>
<para>
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:
<itemizedlist>
<listitem>
<para> There is no support for using custom locale/chartables </para>
</listitem>
<listitem>
<para> dfa_exec() doesn't take 'ovecsize' nor 'wscount' arguments </para>
</listitem>
<listitem>
<para> dfa_exec() returns boolean true for partial match, without subcapture info </para>
</listitem>
<listitem>
<para> Named subgroups do not return name-keyed entries in the return
table (i.e., in match/tfind/exec)
</para>
</listitem>
<listitem>
<para> 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
</para>
</listitem>
<listitem>
<para>
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:].
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
</itemizedlist>
</para>
<para>
Since: 1.11.3
</para>
<para>
This page is based on the full documentation for Lrexlib at
<ulink url="http://rrthomas.github.io/lrexlib/manual.html">http://rrthomas.github.io/lrexlib/manual.html</ulink>
</para>
<para>
The GLib Regular expression syntax (which is essentially PCRE syntax) can be found at
<ulink url="https://developer.gnome.org/glib/2.38/glib-regex-syntax.html">https://developer.gnome.org/glib/2.38/glib-regex-syntax.html</ulink>
</para>
<section id='lua_class_GRegex'><title>GRegex</title>
<para>
GLib Regular Expressions based on PCRE.
</para>
<para>
Since: 1.11.3
</para>
<section id='lua_class_GRegex_notes'><title>Notes</title>
<para>
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.
</para>
<para>
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).
</para>
<para>
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:
<itemizedlist>
<listitem>
<para> '<command>i</command>' = 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. </para>
</listitem>
<listitem>
<para> '<command>m</command>' = 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.</para>
</listitem>
<listitem>
<para> '<command>s</command>' = 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. </para>
</listitem>
<listitem>
<para> '<command>x</command>' = 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. </para>
</listitem>
<listitem>
<para> '<command>U</command>' = 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. </para>
</listitem>
</itemizedlist>
</para>
</section><!-- end of notes -->
<section id='lua_fn_GRegex_new_pattern_'>
<title>GRegex.new(pattern)</title>
<para>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.
</para>
<para>
Since: 1.11.3
</para>
<section><title>Arguments</title>
<variablelist>
<varlistentry><term>pattern</term>
<listitem><para> A Perl-compatible regular expression pattern string </para></listitem>
</varlistentry> <!-- function_arg_footer: pattern -->
</variablelist>
</section>
<section><title>Returns</title>
<para> The compiled regular expression (a userdata object) </para>
</section> <!-- function_returns_footer: GRegex.new -->
<section><title>Errors</title>
<itemizedlist>
<listitem><para>A malformed pattern generates a Lua error </para></listitem>
</itemizedlist>
</section> <!-- function_error_footer: GRegex.new -->
</section> <!-- function_footer: GRegex.new -->
<section id='lua_fn_GRegex_flags__table__'>
<title>GRegex.flags([table])</title>
<para>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.
</para>
<para>
Since: 1.11.3
</para>
<section><title>Arguments</title>
<variablelist>
<varlistentry><term>table (optional)</term>
<listitem><para> A table for placing results into </para></listitem>
</varlistentry> <!-- function_arg_footer: table (optional) -->
</variablelist>
</section>
<section><title>Returns</title>
<para>A table filled with the results.</para>
</section> <!-- function_returns_footer: GRegex.flags -->
</section> <!-- function_footer: GRegex.flags -->
<section id='lua_fn_GRegex_compile_flags__table__'>
<title>GRegex.compile_flags([table])</title>
<para>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.
</para>
<para>
Since: 1.11.3
</para>
<section><title>Arguments</title>
<variablelist>
<varlistentry><term>table (optional)</term>
<listitem><para> A table for placing results into </para></listitem>
</varlistentry> <!-- function_arg_footer: table (optional) -->
</variablelist>
</section>
<section><title>Returns</title>
<para>A table filled with the results.</para>
</section> <!-- function_returns_footer: GRegex.compile_flags -->
</section> <!-- function_footer: GRegex.compile_flags -->
<section id='lua_fn_GRegex_match_flags__table__'>
<title>GRegex.match_flags([table])</title>
<para>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.
</para>
<para>
Since: 1.11.3
</para>
<section><title>Arguments</title>
<variablelist>
<varlistentry><term>table (optional)</term>
<listitem><para> A table for placing results into </para></listitem>
</varlistentry> <!-- function_arg_footer: table (optional) -->
</variablelist>
</section>
<section><title>Returns</title>
<para>A table filled with the results.</para>
</section> <!-- function_returns_footer: GRegex.match_flags -->
</section> <!-- function_footer: GRegex.match_flags -->
<section id='lua_fn_GRegex_match_subject__pattern___init____cf____ef__'>
<title>GRegex.match(subject, pattern, [init], [cf], [ef])</title>
<para>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.
</para>
<para>
Since: 1.11.3
</para>
<section><title>Arguments</title>
<variablelist>
<varlistentry><term>subject</term>
<listitem><para> Subject string to search </para></listitem>
</varlistentry> <!-- function_arg_footer: subject -->
<varlistentry><term>pattern</term>
<listitem><para> A Perl-compatible regular expression pattern string or GRegex object </para></listitem>
</varlistentry> <!-- function_arg_footer: pattern -->
<varlistentry><term>init (optional)</term>
<listitem><para> start offset in the subject (can be negative) </para></listitem>
</varlistentry> <!-- function_arg_footer: init (optional) -->
<varlistentry><term>cf (optional)</term>
<listitem><para> compilation flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: cf (optional) -->
<varlistentry><term>ef (optional)</term>
<listitem><para> match execution flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: ef (optional) -->
</variablelist>
</section>
<section><title>Returns</title>
<para>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.
</para>
</section> <!-- function_returns_footer: GRegex.match -->
</section> <!-- function_footer: GRegex.match -->
<section id='lua_fn_GRegex_find_subject__pattern___init____cf____ef__'>
<title>GRegex.find(subject, pattern, [init], [cf], [ef])</title>
<para>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.
</para>
<para>
Since: 1.11.3
</para>
<section><title>Arguments</title>
<variablelist>
<varlistentry><term>subject</term>
<listitem><para> Subject string to search </para></listitem>
</varlistentry> <!-- function_arg_footer: subject -->
<varlistentry><term>pattern</term>
<listitem><para> A Perl-compatible regular expression pattern string or GRegex object </para></listitem>
</varlistentry> <!-- function_arg_footer: pattern -->
<varlistentry><term>init (optional)</term>
<listitem><para> start offset in the subject (can be negative) </para></listitem>
</varlistentry> <!-- function_arg_footer: init (optional) -->
<varlistentry><term>cf (optional)</term>
<listitem><para> compilation flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: cf (optional) -->
<varlistentry><term>ef (optional)</term>
<listitem><para> match execution flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: ef (optional) -->
</variablelist>
</section>
<section><title>Returns</title>
<para>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.
</para>
</section> <!-- function_returns_footer: GRegex.find -->
</section> <!-- function_footer: GRegex.find -->
<section id='lua_fn_GRegex_gmatch_subject__pattern___init____cf____ef__'>
<title>GRegex.gmatch(subject, pattern, [init], [cf], [ef])</title>
<para>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().
</para>
<para>
Since: 1.11.3
</para>
<section><title>Arguments</title>
<variablelist>
<varlistentry><term>subject</term>
<listitem><para> Subject string to search </para></listitem>
</varlistentry> <!-- function_arg_footer: subject -->
<varlistentry><term>pattern</term>
<listitem><para> A Perl-compatible regular expression pattern string or GRegex object </para></listitem>
</varlistentry> <!-- function_arg_footer: pattern -->
<varlistentry><term>init (optional)</term>
<listitem><para> start offset in the subject (can be negative) </para></listitem>
</varlistentry> <!-- function_arg_footer: init (optional) -->
<varlistentry><term>cf (optional)</term>
<listitem><para> compilation flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: cf (optional) -->
<varlistentry><term>ef (optional)</term>
<listitem><para> match execution flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: ef (optional) -->
</variablelist>
</section>
<section><title>Returns</title>
<para>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.
</para>
</section> <!-- function_returns_footer: GRegex.gmatch -->
</section> <!-- function_footer: GRegex.gmatch -->
<section id='lua_fn_GRegex_gsub_subject__pattern___repl____max____cf____ef__'>
<title>GRegex.gsub(subject, pattern, [repl], [max], [cf], [ef])</title>
<para>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().
</para>
<para>
Since: 1.11.3
</para>
<para> For details see:
<ulink url="http://rrthomas.github.io/lrexlib/manual.html#gsub">http://rrthomas.github.io/lrexlib/manual.html#gsub</ulink>
</para>
<section><title>Arguments</title>
<variablelist>
<varlistentry><term>subject</term>
<listitem><para> Subject string to search </para></listitem>
</varlistentry> <!-- function_arg_footer: subject -->
<varlistentry><term>pattern</term>
<listitem><para> A Perl-compatible regular expression pattern string or GRegex object </para></listitem>
</varlistentry> <!-- function_arg_footer: pattern -->
<varlistentry><term>repl (optional)</term>
<listitem><para> Substitution source string, function, table, false or nil </para></listitem>
</varlistentry> <!-- function_arg_footer: repl (optional) -->
<varlistentry><term>max (optional)</term>
<listitem><para> Maximum number of matches to search for, or control function, or nil </para></listitem>
</varlistentry> <!-- function_arg_footer: max (optional) -->
<varlistentry><term>cf (optional)</term>
<listitem><para> Compilation flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: cf (optional) -->
<varlistentry><term>ef (optional)</term>
<listitem><para> Match execution flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: ef (optional) -->
</variablelist>
</section>
<section><title>Returns</title>
<para>On success, returns the subject string with the substitutions made,
the number of matches found, and the number of substitutions made.
</para>
</section> <!-- function_returns_footer: GRegex.gsub -->
</section> <!-- function_footer: GRegex.gsub -->
<section id='lua_fn_GRegex_split_subject__sep___cf____ef__'>
<title>GRegex.split(subject, sep, [cf], [ef])</title>
<para>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.
</para>
<para>
Since: 1.11.3
</para>
<section><title>Arguments</title>
<variablelist>
<varlistentry><term>subject</term>
<listitem><para> Subject string to search </para></listitem>
</varlistentry> <!-- function_arg_footer: subject -->
<varlistentry><term>sep</term>
<listitem><para> A Perl-compatible regular expression pattern string or GRegex object </para></listitem>
</varlistentry> <!-- function_arg_footer: sep -->
<varlistentry><term>cf (optional)</term>
<listitem><para> compilation flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: cf (optional) -->
<varlistentry><term>ef (optional)</term>
<listitem><para> match execution flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: ef (optional) -->
</variablelist>
</section>
<section><title>Returns</title>
<para>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.
</para>
</section> <!-- function_returns_footer: GRegex.split -->
</section> <!-- function_footer: -->
<section id='lua_fn_GRegex_version__'>
<title>GRegex.version()</title>
<para>Returns a returns a string containing the version of the used library.</para>
<para>
Since: 1.11.3
</para>
<section><title>Returns</title>
<para>The version string</para>
</section> <!-- function_returns_footer: GRegex.version -->
</section> <!-- function_footer: GRegex.version -->
<section id='lua_fn_gregex_match_subject___init____ef__'>
<title>gregex:match(subject, [init], [ef])</title>
<para>Searches for the first match of the regexp pattern in the string subject, starting
from offset init, subject to flags ef.
</para>
<para>
Since: 1.11.3
</para>
<section><title>Arguments</title>
<variablelist>
<varlistentry><term>subject</term>
<listitem><para> Subject string to search </para></listitem>
</varlistentry> <!-- function_arg_footer: subject -->
<varlistentry><term>init (optional)</term>
<listitem><para> start offset in the subject (can be negative) </para></listitem>
</varlistentry> <!-- function_arg_footer: init (optional) -->
<varlistentry><term>ef (optional)</term>
<listitem><para> match execution flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: ef (optional) -->
</variablelist>
</section>
<section><title>Returns</title>
<para>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.
</para>
</section> <!-- function_returns_footer: gregex:match -->
</section> <!-- function_footer: gregex:match -->
<section id='lua_fn_gregex_find_subject___init____ef__'>
<title>gregex:find(subject, [init], [ef])</title>
<para>Searches for the first match of the regexp pattern in the string subject, starting
from offset init, subject to flags ef.
</para>
<para>
Since: 1.11.3
</para>
<section><title>Arguments</title>
<variablelist>
<varlistentry><term>subject</term>
<listitem><para> Subject string to search </para></listitem>
</varlistentry> <!-- function_arg_footer: subject -->
<varlistentry><term>init (optional)</term>
<listitem><para> start offset in the subject (can be negative) </para></listitem>
</varlistentry> <!-- function_arg_footer: init (optional) -->
<varlistentry><term>ef (optional)</term>
<listitem><para> match execution flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: ef (optional) -->
</variablelist>
</section>
<section><title>Returns</title>
<para>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.
</para>
</section> <!-- function_returns_footer: gregex:find -->
</section> <!-- function_footer: -->
<section id='lua_fn_gregex_exec_subject___init____ef__'>
<title>gregex:exec(subject, [init], [ef])</title>
<para>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.
</para>
<para>
Since: 1.11.3
</para>
<section><title>Arguments</title>
<variablelist>
<varlistentry><term>subject</term>
<listitem><para> Subject string to search </para></listitem>
</varlistentry> <!-- function_arg_footer: subject -->
<varlistentry><term>init (optional)</term>
<listitem><para> start offset in the subject (can be negative) </para></listitem>
</varlistentry> <!-- function_arg_footer: init (optional) -->
<varlistentry><term>ef (optional)</term>
<listitem><para> match execution flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: ef (optional) -->
</variablelist>
</section>
<section><title>Returns</title>
<para>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 }.
</para>
</section> <!-- function_returns_footer: gregex:exec -->
</section> <!-- function_footer: gregex:exec -->
<section id='lua_fn_gregex_dfa_exec_subject___init____ef__'>
<title>gregex:dfa_exec(subject, [init], [ef])</title>
<para>Matches a compiled regular expression GRegex object against a given subject string subj, using a DFA matching algorithm.</para>
<para>
Since: 1.11.3
</para>
<section><title>Arguments</title>
<variablelist>
<varlistentry><term>subject</term>
<listitem><para> Subject string to search </para></listitem>
</varlistentry> <!-- function_arg_footer: subject -->
<varlistentry><term>init (optional)</term>
<listitem><para> start offset in the subject (can be negative) </para></listitem>
</varlistentry> <!-- function_arg_footer: init (optional) -->
<varlistentry><term>ef (optional)</term>
<listitem><para> match execution flags (bitwise OR) </para></listitem>
</varlistentry> <!-- function_arg_footer: ef (optional) -->
</variablelist>
</section>
<section><title>Returns</title>
<para>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
</para>
</section> <!-- function_returns_footer: gregex:dfa_exec -->
</section> <!-- function_footer: gregex:dfa_exec -->
<section id='lua_fn_gregex___tostring__'>
<title>gregex:__tostring()</title>
<para>Returns a string containing debug information about the GRegex object.</para>
<para>
Since: 1.11.3
</para>
<section><title>Returns</title>
<para>The debug string</para>
</section> <!-- function_returns_footer: gregex:__tostring -->
</section> <!-- function_footer: -->
</section> <!-- class_footer: GRegex -->
</section>
</chapter>

2
docbook/wsug_src/WSUG_chapter_use.asciidoc
View File

@ -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 <<wsluarm_intro>>.
|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]]

2
epan/wslua/wslua_int64.c
View File

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

50
epan/wslua/wslua_struct.c
View File

@ -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`.

4
epan/wslua/wslua_tree.c
View File

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

2
epan/wslua/wslua_tvb.c
View File

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