path: root/docbook/wsluarm.xml

<!-- $Id$ -->
<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>