forked from osmocom/wireshark
714 lines
32 KiB
XML
714 lines
32 KiB
XML
<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:<file.lua></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 < 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>
|