2014-11-02 21:20:08 +00:00
|
|
|
|
[[wsluarm]]
|
|
|
|
|
|
|
|
|
|
// Attributes
|
|
|
|
|
:build_dir: .
|
|
|
|
|
|
|
|
|
|
== Lua Support in Wireshark
|
|
|
|
|
|
|
|
|
|
[[wsluarm_intro]]
|
|
|
|
|
|
|
|
|
|
=== Introduction
|
|
|
|
|
|
2019-05-16 02:21:30 +00:00
|
|
|
|
Lua is a powerful light-weight programming language designed for extending
|
|
|
|
|
applications. Wireshark contains an embedded Lua 5.2 interpreter which
|
|
|
|
|
can be used to write dissectors, taps, and capture file readers
|
2014-11-02 21:20:08 +00:00
|
|
|
|
and writers.
|
|
|
|
|
|
2019-05-16 02:21:30 +00:00
|
|
|
|
Wireshark’s Lua interpreter starts by loading a file named `init.lua` from
|
2019-06-14 23:03:17 +00:00
|
|
|
|
Wireshark's link:{wireshark-users-guide-url}ChAppFilesConfigurationSection.html[_global configuration directory_].
|
2019-05-16 02:21:30 +00:00
|
|
|
|
The _global configuration directory_'s `init.lua` controls whether or not Lua
|
|
|
|
|
scripts are enabled via the
|
|
|
|
|
_$$enable_lua$$_ variable. Lua scripts are enabled by
|
|
|
|
|
default. To disable Lua scripts, set the _$$enable_lua$$_ variable to _false_.
|
|
|
|
|
Wireshark 2.6 and earlier enabled or disabled Lua scripts using
|
|
|
|
|
the variable _$$disable_lua$$_ (deprecated). If both _$$enable_lua$$_ and
|
|
|
|
|
_$$disable_lua$$_ are present, _$$disable_lua$$_ is ignored.
|
|
|
|
|
|
|
|
|
|
If Lua is enabled, Wireshark will try to load a file named `init.lua`
|
|
|
|
|
from the user’s
|
2019-06-14 23:03:17 +00:00
|
|
|
|
link:{wireshark-users-guide-url}ChAppFilesConfigurationSection.html[_personal configuration directory_]
|
2019-05-16 02:21:30 +00:00
|
|
|
|
and all files ending with _.lua_ in the global and the personal
|
2019-06-14 23:03:17 +00:00
|
|
|
|
link:{wireshark-users-guide-url}ChPluginFolders.html[_plugins directory_].
|
2019-05-16 02:21:30 +00:00
|
|
|
|
|
|
|
|
|
The command line option _$$-X lua_script:$$++file.lua++_ can also be used to load
|
|
|
|
|
specific Lua scripts.
|
|
|
|
|
|
|
|
|
|
The Lua code is executed after all protocol dissectors are
|
2014-11-02 21:20:08 +00:00
|
|
|
|
initialized and before reading any file.
|
|
|
|
|
|
2018-12-28 11:49:33 +00:00
|
|
|
|
Wireshark for Windows uses a modified Lua runtime
|
2019-05-16 02:21:30 +00:00
|
|
|
|
(link:https://github.com/Lekensteyn/lua-unicode[lua-unicode]) to
|
2018-12-28 11:49:33 +00:00
|
|
|
|
support Unicode (UTF-8) filesystem paths. This brings consistency with other
|
|
|
|
|
platforms (for example, Linux and macOS).
|
|
|
|
|
|
2019-05-16 02:21:30 +00:00
|
|
|
|
[[wslua_menu_example]]
|
|
|
|
|
|
|
|
|
|
=== Example: Creating a Menu with Lua
|
|
|
|
|
|
|
|
|
|
The code below adds a menu "Lua Dialog Test" under the Tools menu.
|
|
|
|
|
When selected, it opens a dialog prompting the user for input
|
|
|
|
|
and then opens a text window with the output.
|
|
|
|
|
|
|
|
|
|
[source,lua]
|
|
|
|
|
----
|
|
|
|
|
|
2019-07-02 21:18:52 +00:00
|
|
|
|
-- Define the menu entry's callback
|
2019-05-16 02:21:30 +00:00
|
|
|
|
local function dialog_menu()
|
|
|
|
|
local function dialog_func(person,eyes,hair)
|
|
|
|
|
local window = TextWindow.new("Person Info");
|
|
|
|
|
local message = string.format("Person %s with %s eyes and %s hair.", person, eyes, hair);
|
|
|
|
|
window:set(message);
|
|
|
|
|
end
|
|
|
|
|
|
|
|
|
|
new_dialog("Dialog Test",dialog_func,"A Person","Eyes","Hair")
|
|
|
|
|
end
|
|
|
|
|
|
2019-07-02 21:18:52 +00:00
|
|
|
|
-- Create the menu entry
|
2019-05-16 02:21:30 +00:00
|
|
|
|
register_menu("Lua Dialog Test",dialog_menu,MENU_TOOLS_UNSORTED)
|
2019-07-02 21:18:52 +00:00
|
|
|
|
|
|
|
|
|
-- Notify the user that the menu was created
|
|
|
|
|
if gui_enabled() then
|
|
|
|
|
local splash = TextWindow.new("Hello!");
|
|
|
|
|
splash:set("Wireshark has been enhanced with a useless feature.\n")
|
|
|
|
|
splash:append("Go to 'Tools->Lua Dialog Test' and check it out!")
|
|
|
|
|
end
|
|
|
|
|
|
2019-05-16 02:21:30 +00:00
|
|
|
|
----
|
|
|
|
|
|
2014-11-02 21:20:08 +00:00
|
|
|
|
[[wslua_dissector_example]]
|
|
|
|
|
|
2019-05-16 02:21:30 +00:00
|
|
|
|
=== Example: Dissector written in Lua
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
|
|
|
|
[source,lua]
|
|
|
|
|
----
|
2016-10-17 00:08:44 +00:00
|
|
|
|
local p_multi = Proto("multi", "MultiProto");
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
|
|
|
|
local vs_protos = {
|
|
|
|
|
[2] = "mtp2",
|
|
|
|
|
[3] = "mtp3",
|
|
|
|
|
[4] = "alcap",
|
|
|
|
|
[5] = "h248",
|
|
|
|
|
[6] = "ranap",
|
|
|
|
|
[7] = "rnsap",
|
|
|
|
|
[8] = "nbap"
|
|
|
|
|
}
|
|
|
|
|
|
2016-10-17 00:08:44 +00:00
|
|
|
|
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")
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
}
|
|
|
|
|
|
2016-10-17 00:08:44 +00:00
|
|
|
|
function p_multi.dissector(buf, pkt, tree)
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
2016-10-17 00:08:44 +00:00
|
|
|
|
local subtree = tree:add(p_multi, buf(0,2))
|
|
|
|
|
subtree:add(f_proto, buf(0,1))
|
|
|
|
|
subtree:add(f_dir, buf(1,1))
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
|
|
|
|
local proto_id = buf(0,1):uint()
|
|
|
|
|
|
|
|
|
|
local dissector = protos[proto_id]
|
|
|
|
|
|
|
|
|
|
if dissector ~= nil then
|
2016-10-17 00:08:44 +00:00
|
|
|
|
-- Dissector was found, invoke subdissector with a new Tvb,
|
|
|
|
|
-- created from the current buffer (skipping first two bytes).
|
|
|
|
|
dissector:call(buf(2):tvb(), pkt, tree)
|
2014-11-02 21:20:08 +00:00
|
|
|
|
elseif proto_id < 2 then
|
2016-10-17 00:08:44 +00:00
|
|
|
|
subtree:add(f_text, buf(2))
|
|
|
|
|
-- pkt.cols.info:set(buf(2, buf:len() - 3):string())
|
2014-11-02 21:20:08 +00:00
|
|
|
|
else
|
2016-10-17 00:08:44 +00:00
|
|
|
|
-- fallback dissector that just shows the raw data.
|
|
|
|
|
data_dis:call(buf(2):tvb(), pkt, tree)
|
2014-11-02 21:20:08 +00:00
|
|
|
|
end
|
|
|
|
|
|
|
|
|
|
end
|
|
|
|
|
|
|
|
|
|
local wtap_encap_table = DissectorTable.get("wtap_encap")
|
|
|
|
|
local udp_encap_table = DissectorTable.get("udp.port")
|
|
|
|
|
|
2016-10-17 00:08:44 +00:00
|
|
|
|
wtap_encap_table:add(wtap.USER15, p_multi)
|
|
|
|
|
wtap_encap_table:add(wtap.USER12, p_multi)
|
|
|
|
|
udp_encap_table:add(7555, p_multi)
|
2014-11-02 21:20:08 +00:00
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
[[wslua_tap_example]]
|
|
|
|
|
|
2019-05-16 02:21:30 +00:00
|
|
|
|
=== Example: Listener written in Lua
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
|
|
|
|
[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();
|
|
|
|
|
|
2018-03-23 17:05:13 +00:00
|
|
|
|
local function remove()
|
2014-11-02 21:20:08 +00:00
|
|
|
|
-- 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
|
2018-03-23 17:05:13 +00:00
|
|
|
|
|
|
|
|
|
-- Ensure that all existing packets are processed.
|
|
|
|
|
retap_packets()
|
2014-11-02 21:20:08 +00:00
|
|
|
|
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]]
|
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
== Wireshark’s Lua API Reference Manual
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
|
|
|
|
This Part of the User Guide describes the Wireshark specific functions in the embedded Lua.
|
|
|
|
|
|
2016-10-17 00:08:44 +00:00
|
|
|
|
Classes group certain functionality, the following notational conventions are
|
|
|
|
|
used:
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _Class.function()_ represents a class method (named _function_) on class
|
|
|
|
|
_Class_, taking no arguments.
|
2016-10-17 00:08:44 +00:00
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _Class.function(a)_ represents a class method taking one argument.
|
2016-10-17 00:08:44 +00:00
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _Class.function(...)_ represents a class method taking a variable number of
|
2016-10-17 00:08:44 +00:00
|
|
|
|
arguments.
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _class:method()_ represents an instance method (named _method_) on an instance
|
|
|
|
|
of class _Class_, taking no arguments. Note the lowercase notation in the
|
2016-10-17 00:08:44 +00:00
|
|
|
|
documentation to clarify an instance.
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _class.prop_ represents a property _prop_ on the instance of class _Class_.
|
2016-10-17 00:08:44 +00:00
|
|
|
|
|
|
|
|
|
Trying to access a non-existing property, function or method currently gives an
|
|
|
|
|
error, but do not rely on it as the behavior may change in the future.
|
|
|
|
|
|
|
|
|
|
|
2019-02-14 23:23:05 +00:00
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_dumper.adoc[]
|
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_field.adoc[]
|
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_gui.adoc[]
|
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_listener.adoc[]
|
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_pinfo.adoc[]
|
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_proto.adoc[]
|
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_tree.adoc[]
|
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_tvb.adoc[]
|
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_file.adoc[]
|
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_dir.adoc[]
|
2021-02-13 03:29:33 +00:00
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_wtap.adoc[]
|
2019-02-14 23:23:05 +00:00
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_util.adoc[]
|
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_int64.adoc[]
|
|
|
|
|
include::{build_dir}/wsluarm_src/wslua_struct.adoc[]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
|
|
|
|
[[lua_module_GRegex]]
|
|
|
|
|
|
|
|
|
|
=== GLib Regular Expressions
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
Lua has its own native _pattern_ syntax in the string library, but sometimes a
|
2018-02-04 23:15:02 +00:00
|
|
|
|
real regex engine is more useful. Wireshark comes with GLib’s Regex
|
2014-11-02 21:20:08 +00:00
|
|
|
|
implementation, which itself is based on Perl Compatible Regular Expressions
|
2018-02-04 23:15:02 +00:00
|
|
|
|
(PCRE). This engine is exposed into Wireshark’s Lua engine through the
|
2014-11-02 21:20:08 +00:00
|
|
|
|
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
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _dfa_exec()_ doesn't take _ovecsize_ nor _wscount_ arguments
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _dfa_exec()_ returns boolean true for partial match, without subcapture info
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
|
|
|
|
* Named subgroups do not return name-keyed entries in the return table (i.e., in
|
|
|
|
|
match/tfind/exec)
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* The _flags()_ function still works, returning all flags, but two new functions
|
|
|
|
|
_compile_flags()_ and _match_flags()_ return just their respective flags,
|
2014-11-02 21:20:08 +00:00
|
|
|
|
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
|
2018-02-04 19:39:56 +00:00
|
|
|
|
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:
|
2014-11-02 21:20:08 +00:00
|
|
|
|
[: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
|
2019-07-20 15:13:59 +00:00
|
|
|
|
https://rrthomas.github.io/lrexlib/manual.html[]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
|
|
|
|
The GLib Regular expression syntax (which is essentially PCRE syntax) can be
|
|
|
|
|
found at
|
2019-07-20 15:13:59 +00:00
|
|
|
|
https://developer.gnome.org/glib/2.38/glib-regex-syntax.html[]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
|
|
|
|
[[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).
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
The capture flag argument _cf_ may also be supplied as a string, whose
|
2014-11-02 21:20:08 +00:00
|
|
|
|
characters stand for compilation flags. Combinations of the following characters
|
|
|
|
|
(case sensitive) are supported:
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _i_ = G_REGEX_CASELESS - Letters in the pattern match both upper- and
|
2018-02-04 23:15:02 +00:00
|
|
|
|
lowercase letters. This option can be changed within a pattern by a “(?i)”
|
2014-11-02 21:20:08 +00:00
|
|
|
|
option setting.
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _m_ = G_REGEX_MULTILINE - By default, GRegex treats the strings as
|
2014-11-02 21:20:08 +00:00
|
|
|
|
consisting of a single line of characters (even if it actually contains
|
2019-01-04 20:00:59 +00:00
|
|
|
|
newlines). The “start of line” metacharacter (“^”) matches only at the start
|
|
|
|
|
of the string, while the “end of line” metacharacter (“$”) matches only at
|
2014-11-02 21:20:08 +00:00
|
|
|
|
the end of the string, or before a terminating newline (unless
|
2019-01-04 20:00:59 +00:00
|
|
|
|
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
|
2014-11-02 21:20:08 +00:00
|
|
|
|
immediately before any newline in the string, respectively, as well as at the
|
2018-02-04 23:15:02 +00:00
|
|
|
|
very start and end. This can be changed within a pattern by a “(?m)” option
|
2014-11-02 21:20:08 +00:00
|
|
|
|
setting.
|
|
|
|
|
|
2020-09-03 21:22:00 +00:00
|
|
|
|
* _s_ = G_REGEX_DOTALL - A dot metacharacter (“.”) in the pattern matches
|
2014-11-02 21:20:08 +00:00
|
|
|
|
all characters, including newlines. Without it, newlines are excluded. This
|
|
|
|
|
option can be changed within a pattern by a ("?s") option setting.
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _x_ = G_REGEX_EXTENDED - Whitespace data characters in the pattern are
|
2014-11-02 21:20:08 +00:00
|
|
|
|
totally ignored except when escaped or inside a character class. Whitespace
|
|
|
|
|
does not include the VT character (code 11). In addition, characters between
|
2018-02-04 23:15:02 +00:00
|
|
|
|
an unescaped “$$#$$” outside a character class and the next newline character,
|
2014-11-02 21:20:08 +00:00
|
|
|
|
inclusive, are also ignored. This can be changed within a pattern by a
|
2018-02-04 23:15:02 +00:00
|
|
|
|
“(?x)” option setting.
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
* _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.
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
|
|
|
|
[[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
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== Arguments
|
|
|
|
|
|
|
|
|
|
pattern:: A Perl-compatible regular expression pattern string
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== Returns
|
|
|
|
|
|
|
|
|
|
The compiled regular expression (a userdata object)
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== Arguments
|
|
|
|
|
|
|
|
|
|
table (optional):: A table for placing results into
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== Arguments
|
|
|
|
|
|
|
|
|
|
table (optional):: A table for placing results into
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== Arguments
|
|
|
|
|
|
|
|
|
|
table (optional):: A table for placing results into
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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
|
2018-02-04 19:39:56 +00:00
|
|
|
|
each time this is called, unlike the class method _match_ function.
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
|
|
|
|
Since: 1.11.3
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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)
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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
|
2018-02-04 19:39:56 +00:00
|
|
|
|
time this is called, unlike the class method _find_ function.
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
|
|
|
|
Since: 1.11.3
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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)
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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)
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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:
|
2019-07-20 15:13:59 +00:00
|
|
|
|
https://rrthomas.github.io/lrexlib/manual.html#gsub[]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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)
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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)
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== Arguments
|
|
|
|
|
|
|
|
|
|
subject:: Subject string to search
|
|
|
|
|
|
|
|
|
|
init (optional):: start offset in the subject (can be negative)
|
|
|
|
|
|
|
|
|
|
ef (optional):: match execution flags (bitwise OR)
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== Returns
|
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
On success, returns all substring matches (“captures”), in the order they appear
|
2014-11-02 21:20:08 +00:00
|
|
|
|
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
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== Arguments
|
|
|
|
|
|
|
|
|
|
subject:: Subject string to search
|
|
|
|
|
|
|
|
|
|
init (optional):: start offset in the subject (can be negative)
|
|
|
|
|
|
|
|
|
|
ef (optional):: match execution flags (bitwise OR)
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== Arguments
|
|
|
|
|
|
|
|
|
|
subject:: Subject string to search
|
|
|
|
|
|
|
|
|
|
init (optional):: start offset in the subject (can be negative)
|
|
|
|
|
|
|
|
|
|
ef (optional):: match execution flags (bitwise OR)
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== Returns
|
|
|
|
|
|
|
|
|
|
On success, returns the start point of the first match (a number), the end point
|
2018-02-04 23:15:02 +00:00
|
|
|
|
of the first match (a number), and the offsets of substring matches (“captures”
|
2014-11-02 21:20:08 +00:00
|
|
|
|
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
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== Arguments
|
|
|
|
|
|
|
|
|
|
subject:: Subject string to search
|
|
|
|
|
|
|
|
|
|
init (optional):: start offset in the subject (can be negative)
|
|
|
|
|
|
|
|
|
|
ef (optional):: match execution flags (bitwise OR)
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== 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
|
|
|
|
|
|
2020-04-24 20:09:13 +00:00
|
|
|
|
[discrete]
|
2014-11-02 21:20:08 +00:00
|
|
|
|
===== Returns
|
|
|
|
|
|
|
|
|
|
The debug string
|