docbook/wsluarm.asciidoc

   1 [[wsluarm]]
   2
   3 // Attributes
   4 :build_dir: .
   5
   6 == Lua Support in Wireshark
   7
   8 [[wsluarm_intro]]
   9
  10 === Introduction
  11
  12 Wireshark has an embedded Lua interpreter. Lua is a powerful light-weight
  13 programming language designed for extending applications. Lua is designed and
  14 implemented by a team at PUC-Rio, the Pontifical Catholic University of Rio de
  15 Janeiro in Brazil. Lua was born and raised at Tecgraf, the Computer Graphics
  16 Technology Group of PUC-Rio, and is now housed at
  17 link:http://www.lua.org[Lua.org]. Both Tecgraf and Lua.org are laboratories of
  18 the Department of Computer Science.
  19
  20 In Wireshark Lua can be used to write dissectors, taps, and capture file readers
  21 and writers.
  22
  23 Wireshark’s Lua interpreter starts by loading a file named `init.lua` in
  24 Wireshark's global configuration directory. It is enabled by default. To
  25 disable Lua the line variable _$$enable_lua$$_ should be set to _false_
  26 in _init.lua_. Wireshark 2.6 and earlier enabled and disabled Lua using
  27 the variable _$$disable_lua$$_. It is still supported, but is deprecated
  28 and support may be removed in a future release. _$$enable_lua$$_ takes
  29 precedence over _$$disable_lua$$_.
  30
  31 If Lua is enabled Wireshark will then try to load a file named _init.lua_
  32 in the user’s personal configuration directory. Wireshark will also load
  33 all files with a _.lua_ suffix from both the global and the personal
  34 plugins directory.
  35
  36 The command line option _$$-X lua_script:$$++file.lua++_ can be used to load
  37 Lua scripts as well.
  38
  39 The Lua code will be executed once after all the protocol dissectors have been
  40 initialized and before reading any file.
  41
  42 Lua 5.2 is the current supported version, future releases might use Lua 5.3.
  43
  44 Wireshark for Windows uses a modified Lua runtime
  45 (link:https://github.com/Lekensteyn/lua-unicode[lua-unicode]) in order to
  46 support Unicode (UTF-8) filesystem paths. This brings consistency with other
  47 platforms (for example, Linux and macOS).
  48
  49 [[wslua_dissector_example]]
  50
  51 === Example of Dissector written in Lua
  52
  53 [source,lua]
  54 ----
  55 local p_multi = Proto("multi", "MultiProto");
  56
  57 local vs_protos = {
  58         [2] = "mtp2",
  59         [3] = "mtp3",
  60         [4] = "alcap",
  61         [5] = "h248",
  62         [6] = "ranap",
  63         [7] = "rnsap",
  64         [8] = "nbap"
  65 }
  66
  67 local f_proto = ProtoField.uint8("multi.protocol", "Protocol", base.DEC, vs_protos)
  68 local f_dir = ProtoField.uint8("multi.direction", "Direction", base.DEC, { [1] = "incoming", [0] = "outgoing"})
  69 local f_text = ProtoField.string("multi.text", "Text")
  70
  71 p_multi.fields = { f_proto, f_dir, f_text }
  72
  73 local data_dis = Dissector.get("data")
  74
  75 local protos = {
  76         [2] = Dissector.get("mtp2"),
  77         [3] = Dissector.get("mtp3"),
  78         [4] = Dissector.get("alcap"),
  79         [5] = Dissector.get("h248"),
  80         [6] = Dissector.get("ranap"),
  81         [7] = Dissector.get("rnsap"),
  82         [8] = Dissector.get("nbap"),
  83         [9] = Dissector.get("rrc"),
  84         [10] = DissectorTable.get("sctp.ppi"):get_dissector(3), -- m3ua
  85         [11] = DissectorTable.get("ip.proto"):get_dissector(132), -- sctp
  86 }
  87
  88 function p_multi.dissector(buf, pkt, tree)
  89
  90         local subtree = tree:add(p_multi, buf(0,2))
  91         subtree:add(f_proto, buf(0,1))
  92         subtree:add(f_dir, buf(1,1))
  93
  94         local proto_id = buf(0,1):uint()
  95
  96         local dissector = protos[proto_id]
  97
  98         if dissector ~= nil then
  99                 -- Dissector was found, invoke subdissector with a new Tvb,
 100                 -- created from the current buffer (skipping first two bytes).
 101                 dissector:call(buf(2):tvb(), pkt, tree)
 102         elseif proto_id < 2 then
 103                 subtree:add(f_text, buf(2))
 104                 -- pkt.cols.info:set(buf(2, buf:len() - 3):string())
 105         else
 106                 -- fallback dissector that just shows the raw data.
 107                 data_dis:call(buf(2):tvb(), pkt, tree)
 108         end
 109
 110 end
 111
 112 local wtap_encap_table = DissectorTable.get("wtap_encap")
 113 local udp_encap_table = DissectorTable.get("udp.port")
 114
 115 wtap_encap_table:add(wtap.USER15, p_multi)
 116 wtap_encap_table:add(wtap.USER12, p_multi)
 117 udp_encap_table:add(7555, p_multi)
 118 ----
 119
 120 [[wslua_tap_example]]
 121
 122 === Example of Listener written in Lua
 123
 124 [source,lua]
 125 ----
 126 -- This program will register a menu that will open a window with a count of occurrences
 127 -- of every address in the capture
 128
 129 local function menuable_tap()
 130         -- Declare the window we will use
 131         local tw = TextWindow.new("Address Counter")
 132
 133         -- This will contain a hash of counters of appearances of a certain address
 134         local ips = {}
 135
 136         -- this is our tap
 137         local tap = Listener.new();
 138
 139         local function remove()
 140                 -- this way we remove the listener that otherwise will remain running indefinitely
 141                 tap:remove();
 142         end
 143
 144         -- we tell the window to call the remove() function when closed
 145         tw:set_atclose(remove)
 146
 147         -- this function will be called once for each packet
 148         function tap.packet(pinfo,tvb)
 149                 local src = ips[tostring(pinfo.src)] or 0
 150                 local dst = ips[tostring(pinfo.dst)] or 0
 151
 152                 ips[tostring(pinfo.src)] = src + 1
 153                 ips[tostring(pinfo.dst)] = dst + 1
 154         end
 155
 156         -- this function will be called once every few seconds to update our window
 157         function tap.draw(t)
 158                 tw:clear()
 159                 for ip,num in pairs(ips) do
 160                         tw:append(ip .. "\t" .. num .. "\n");
 161                 end
 162         end
 163
 164         -- this function will be called whenever a reset is needed
 165         -- e.g. when reloading the capture file
 166         function tap.reset()
 167                 tw:clear()
 168                 ips = {}
 169         end
 170
 171         -- Ensure that all existing packets are processed.
 172         retap_packets()
 173 end
 174
 175 -- using this function we register our function
 176 -- to be called when the user selects the Tools->Test->Packets menu
 177 register_menu("Test/Packets", menuable_tap, MENU_TOOLS_UNSORTED)
 178 ----
 179
 180 [[wsluarm_modules]]
 181
 182 == Wireshark’s Lua API Reference Manual
 183
 184 This Part of the User Guide describes the Wireshark specific functions in the embedded Lua.
 185
 186 Classes group certain functionality, the following notational conventions are
 187 used:
 188
 189 * _Class.function()_ represents a class method (named _function_) on class
 190   _Class_, taking no arguments.
 191
 192 * _Class.function(a)_ represents a class method taking one argument.
 193
 194 * _Class.function(...)_ represents a class method taking a variable number of
 195   arguments.
 196
 197 * _class:method()_ represents an instance method (named _method_) on an instance
 198   of class _Class_, taking no arguments. Note the lowercase notation in the
 199   documentation to clarify an instance.
 200
 201 * _class.prop_ represents a property _prop_ on the instance of class _Class_.
 202
 203 Trying to access a non-existing property, function or method currently gives an
 204 error, but do not rely on it as the behavior may change in the future.
 205
 206
 207 include::{build_dir}/wsluarm_src/wslua_dumper.asciidoc[]
 208 include::{build_dir}/wsluarm_src/wslua_field.asciidoc[]
 209 include::{build_dir}/wsluarm_src/wslua_gui.asciidoc[]
 210 include::{build_dir}/wsluarm_src/wslua_listener.asciidoc[]
 211 include::{build_dir}/wsluarm_src/wslua_pinfo.asciidoc[]
 212 include::{build_dir}/wsluarm_src/wslua_proto.asciidoc[]
 213 include::{build_dir}/wsluarm_src/wslua_tree.asciidoc[]
 214 include::{build_dir}/wsluarm_src/wslua_tvb.asciidoc[]
 215 include::{build_dir}/wsluarm_src/wslua_file.asciidoc[]
 216 include::{build_dir}/wsluarm_src/wslua_dir.asciidoc[]
 217 include::{build_dir}/wsluarm_src/wslua_util.asciidoc[]
 218 include::{build_dir}/wsluarm_src/wslua_int64.asciidoc[]
 219 include::{build_dir}/wsluarm_src/wslua_struct.asciidoc[]
 220
 221 [[lua_module_GRegex]]
 222
 223 === GLib Regular Expressions
 224
 225 Lua has its own native _pattern_ syntax in the string library, but sometimes a
 226 real regex engine is more useful. Wireshark comes with GLib’s Regex
 227 implementation, which itself is based on Perl Compatible Regular Expressions
 228 (PCRE). This engine is exposed into Wireshark’s Lua engine through the
 229 well-known Lrexlib library, following the same syntax and semantics as the
 230 Lrexlib PCRE implementation, with a few differences as follows:
 231
 232 * There is no support for using custom locale/chartables
 233
 234 * _dfa_exec()_ doesn't take _ovecsize_ nor _wscount_ arguments
 235
 236 * _dfa_exec()_ returns boolean true for partial match, without subcapture info
 237
 238 * Named subgroups do not return name-keyed entries in the return table (i.e., in
 239   match/tfind/exec)
 240
 241 * The _flags()_ function still works, returning all flags, but two new functions
 242   _compile_flags()_ and _match_flags()_ return just their respective flags,
 243   since GLib has a different and smaller set of such flags, for regex compile
 244   vs. match functions
 245
 246 * Using some assertions and POSIX character classes against strings with
 247   non-ASCII characters might match high-order characters, because glib always
 248   sets PCRE_UCP even if G_REGEX_RAW is set. For example, _[:alpha;]_ matches
 249   certain non-ASCII bytes. The following assertions have this issue: _\b_, _\B_,
 250   _\s_, _\S_, _\w_, _\W_. The following character classes have this issue:
 251   [:alpha:], [:alnum:], [:lower:], [:upper:], [:space:], [:word:], and
 252   [:graph:].
 253
 254 * The compile flag G_REGEX_RAW is always set/used, even if you didn't specify
 255   it. This is because GLib runs PCRE in UTF-8 mode by default, whereas Lua
 256   strings are not UTF-aware.
 257
 258
 259 Since: 1.11.3
 260
 261 This page is based on the full documentation for Lrexlib at
 262 link:http://rrthomas.github.io/lrexlib/manual.html[http://rrthomas.github.io/lrexlib/manual.html]
 263
 264 The GLib Regular expression syntax (which is essentially PCRE syntax) can be
 265 found at
 266 link:https://developer.gnome.org/glib/2.38/glib-regex-syntax.html[https://developer.gnome.org/glib/2.38/glib-regex-syntax.html]
 267
 268 [[lua_class_GRegex]]
 269
 270 ==== GRegex
 271
 272 GLib Regular Expressions based on PCRE.
 273
 274 Since: 1.11.3
 275
 276 [[lua_class_GRegex_notes]]
 277
 278 ===== Notes
 279
 280 All functions that take a regular expression pattern as an argument will
 281 generate an error if that pattern is found invalid by the regex library.
 282
 283 All functions that take a string-type regex argument accept a compiled regex
 284 too. In this case, the compile flags argument is ignored (should be either
 285 supplied as nils or omitted).
 286
 287 The capture flag argument _cf_ may also be supplied as a string, whose
 288 characters stand for compilation flags. Combinations of the following characters
 289 (case sensitive) are supported:
 290
 291 * _i_ = G_REGEX_CASELESS - Letters in the pattern match both upper- and
 292   lowercase letters. This option can be changed within a pattern by a “(?i)”
 293   option setting.
 294
 295 * _m_ = G_REGEX_MULTILINE - By default, GRegex treats the strings as
 296   consisting of a single line of characters (even if it actually contains
 297   newlines). The “start of line” metacharacter (“^”) matches only at the start
 298   of the string, while the “end of line” metacharacter (“$”) matches only at
 299   the end of the string, or before a terminating newline (unless
 300   G_REGEX_DOLLAR_ENDONLY is set). When G_REGEX_MULTILINE is set, the “start of
 301   line” and “end of line” constructs match immediately following or
 302   immediately before any newline in the string, respectively, as well as at the
 303   very start and end. This can be changed within a pattern by a “(?m)” option
 304   setting.
 305
 306 * _s_ = G_REGEX_DOTALL - A dot metacharater (“.”) in the pattern matches
 307   all characters, including newlines. Without it, newlines are excluded. This
 308   option can be changed within a pattern by a ("?s") option setting.
 309
 310 * _x_ = G_REGEX_EXTENDED - Whitespace data characters in the pattern are
 311   totally ignored except when escaped or inside a character class. Whitespace
 312   does not include the VT character (code 11). In addition, characters between
 313   an unescaped “$$#$$” outside a character class and the next newline character,
 314   inclusive, are also ignored. This can be changed within a pattern by a
 315   “(?x)” option setting.
 316
 317 * _U_ = G_REGEX_UNGREEDY - Inverts the “greediness” of the quantifiers so
 318   that they are not greedy by default, but become greedy if followed by “?”.
 319   It can also be set by a “(?U)” option setting within the pattern.
 320
 321 [[lua_fn_GRegex_new_pattern_]]
 322
 323 ===== GRegex.new(pattern)
 324
 325 Compiles regular expression pattern into a regular expression object whose
 326 internal representation is corresponding to the library used. The returned
 327 result then can be used by the methods, e.g. match, exec, etc. Regular
 328 expression objects are automatically garbage collected.
 329
 330 Since: 1.11.3
 331
 332 [float]
 333 ===== Arguments
 334
 335 pattern:: A Perl-compatible regular expression pattern string
 336
 337 [float]
 338 ===== Returns
 339
 340 The compiled regular expression (a userdata object)
 341
 342 [float]
 343 ===== Errors
 344
 345 * A malformed pattern generates a Lua error
 346
 347 [[lua_fn_GRegex_flags__table__]]
 348
 349 ===== GRegex.flags([table])
 350
 351 Returns a table containing the numeric values of the constants defined by the
 352 regex library, with the keys being the (string) names of the constants. If the
 353 table argument is supplied then it is used as the output table, otherwise a new
 354 table is created. The constants contained in the returned table can then be used
 355 in most functions and methods where compilation flags or execution flags can be
 356 specified. They can also be used for comparing with return codes of some
 357 functions and methods for determining the reason of failure.
 358
 359 Since: 1.11.3
 360
 361 [float]
 362 ===== Arguments
 363
 364 table (optional):: A table for placing results into
 365
 366 [float]
 367 ===== Returns
 368
 369 A table filled with the results.
 370
 371 [[lua_fn_GRegex_compile_flags__table__]]
 372
 373
 374 ===== GRegex.compile_flags([table])
 375
 376 Returns a table containing the numeric values of the constants defined by the
 377 regex library for compile flags, with the keys being the (string) names of the
 378 constants. If the table argument is supplied then it is used as the output
 379 table, otherwise a new table is created.
 380
 381 Since: 1.11.3
 382
 383 [float]
 384 ===== Arguments
 385
 386 table (optional):: A table for placing results into
 387
 388 [float]
 389 ===== Returns
 390
 391 A table filled with the results.
 392
 393 [[lua_fn_GRegex_match_flags__table__]]
 394
 395 ===== GRegex.match_flags([table])
 396
 397 Returns a table containing the numeric values of the constants defined by the
 398 regex library for match flags, with the keys being the (string) names of the
 399 constants. If the table argument is supplied then it is used as the output
 400 table, otherwise a new table is created.
 401
 402 Since: 1.11.3
 403
 404 [float]
 405 ===== Arguments
 406
 407 table (optional):: A table for placing results into
 408
 409 [float]
 410 ===== Returns
 411
 412 A table filled with the results.
 413
 414 [[lua_fn_GRegex_match_subject__pattern___init____cf____ef__]]
 415
 416 ===== GRegex.match(subject, pattern, [init], [cf], [ef])
 417
 418 Searches for the first match of the regexp pattern in the string subject,
 419 starting from offset init, subject to flags cf and ef. The pattern is compiled
 420 each time this is called, unlike the class method _match_ function.
 421
 422 Since: 1.11.3
 423
 424 [float]
 425 ===== Arguments
 426
 427 subject:: Subject string to search
 428
 429 pattern:: A Perl-compatible regular expression pattern string or GRegex object
 430
 431 init (optional):: start offset in the subject (can be negative)
 432
 433 cf (optional):: compilation flags (bitwise OR)
 434
 435 ef (optional):: match execution flags (bitwise OR)
 436
 437 [float]
 438 ===== Returns
 439
 440 On success, returns all substring matches ("captures"), in the order they appear
 441 in the pattern. false is returned for sub-patterns that did not participate in
 442 the match. If the pattern specified no captures then the whole matched substring
 443 is returned. On failure, returns nil.
 444
 445 [[lua_fn_GRegex_find_subject__pattern___init____cf____ef__]]
 446
 447 ===== GRegex.find(subject, pattern, [init], [cf], [ef])
 448
 449 Searches for the first match of the regexp pattern in the string subject,
 450 starting from offset init, subject to flags ef. The pattern is compiled each
 451 time this is called, unlike the class method _find_ function.
 452
 453 Since: 1.11.3
 454
 455 [float]
 456 ===== Arguments
 457
 458 subject:: Subject string to search
 459
 460 pattern:: A Perl-compatible regular expression pattern string or GRegex object
 461
 462 init (optional):: start offset in the subject (can be negative)
 463
 464 cf (optional):: compilation flags (bitwise OR)
 465
 466 ef (optional):: match execution flags (bitwise OR)
 467
 468 [float]
 469 ===== Returns
 470
 471 On success, returns the start point of the match (a number), the end point of
 472 the match (a number), and all substring matches ("captures"), in the order they
 473 appear in the pattern. false is returned for sub-patterns that did not
 474 participate in the match. On failure, returns nil.
 475
 476 [[lua_fn_GRegex_gmatch_subject__pattern___init____cf____ef__]]
 477
 478
 479 ===== GRegex.gmatch(subject, pattern, [init], [cf], [ef])
 480
 481 Returns an iterator for repeated matching of the pattern patt in the string
 482 subj, subject to flags cf and ef. The function is intended for use in the
 483 generic for Lua construct. The pattern can be a string or a GRegex object
 484 previously compiled with GRegex.new().
 485
 486 Since: 1.11.3
 487
 488 [float]
 489 ===== Arguments
 490
 491 subject:: Subject string to search
 492
 493 pattern:: A Perl-compatible regular expression pattern string or GRegex object
 494
 495 init (optional):: start offset in the subject (can be negative)
 496
 497 cf (optional):: compilation flags (bitwise OR)
 498
 499 ef (optional):: match execution flags (bitwise OR)
 500
 501 [float]
 502 ===== Returns
 503
 504 The iterator function is called by Lua. On every iteration (that is, on every
 505 match), it returns all captures in the order they appear in the pattern (or the
 506 entire match if the pattern specified no captures). The iteration will continue
 507 till the subject fails to match.
 508
 509 [[lua_fn_GRegex_gsub_subject__pattern___repl____max____cf____ef__]]
 510
 511 ===== GRegex.gsub(subject, pattern, [repl], [max], [cf], [ef])
 512
 513 Searches for all matches of the pattern in the string subject and replaces them
 514 according to the parameters repl and max. The pattern can be a string or a
 515 GRegex object previously compiled with GRegex.new().
 516
 517 Since: 1.11.3
 518
 519 For details see:
 520 link:http://rrthomas.github.io/lrexlib/manual.html#gsub[http://rrthomas.github.io/lrexlib/manual.html#gsub]
 521
 522 [float]
 523 ===== Arguments
 524
 525 subject:: Subject string to search
 526
 527 pattern:: A Perl-compatible regular expression pattern string or GRegex object
 528
 529 repl (optional):: Substitution source string, function, table, false or nil
 530
 531 max (optional):: Maximum number of matches to search for, or control function, or nil
 532
 533 cf (optional):: Compilation flags (bitwise OR)
 534
 535 ef (optional):: Match execution flags (bitwise OR)
 536
 537 [float]
 538 ===== Returns
 539
 540 On success, returns the subject string with the substitutions made, the number
 541 of matches found, and the number of substitutions made.
 542
 543 [[lua_fn_GRegex_split_subject__sep___cf____ef__]]
 544
 545 ===== GRegex.split(subject, sep, [cf], [ef])
 546
 547 Splits a subject string subj into parts (sections). The sep parameter is a
 548 regular expression pattern representing separators between the sections. The
 549 function is intended for use in the generic for Lua construct. The function
 550 returns an iterator for repeated matching of the pattern sep in the string subj,
 551 subject to flags cf and ef. The sep pattern can be a string or a GRegex object
 552 previously compiled with GRegex.new(). Unlike gmatch, there will always be at
 553 least one iteration pass, even if there are no matches in the subject.
 554
 555 Since: 1.11.3
 556
 557 [float]
 558 ===== Arguments
 559
 560 subject:: Subject string to search
 561
 562 sep:: A Perl-compatible regular expression pattern string or GRegex object
 563
 564 cf (optional):: compilation flags (bitwise OR)
 565
 566 ef (optional):: match execution flags (bitwise OR)
 567
 568 [float]
 569 ===== Returns
 570
 571 The iterator function is called by Lua. On every iteration, it returns a subject
 572 section (can be an empty string), followed by all captures in the order they
 573 appear in the sep pattern (or the entire match if the sep pattern specified no
 574 captures). If there is no match (this can occur only in the last iteration),
 575 then nothing is returned after the subject section. The iteration will continue
 576 till the end of the subject.
 577
 578 [[lua_fn_GRegex_version__]]
 579
 580 ===== GRegex.version()
 581
 582 Returns a returns a string containing the version of the used library.
 583
 584 Since: 1.11.3
 585
 586 [float]
 587 ===== Returns
 588
 589 The version string
 590
 591 [[lua_fn_gregex_match_subject___init____ef__]]
 592
 593 ===== gregex:match(subject, [init], [ef])
 594
 595 Searches for the first match of the regexp pattern in the string subject,
 596 starting from offset init, subject to flags ef.
 597
 598 Since: 1.11.3
 599
 600 [float]
 601 ===== Arguments
 602
 603 subject:: Subject string to search
 604
 605 init (optional):: start offset in the subject (can be negative)
 606
 607 ef (optional):: match execution flags (bitwise OR)
 608
 609 [float]
 610 ===== Returns
 611
 612 On success, returns all substring matches (“captures”), in the order they appear
 613 in the pattern. false is returned for sub-patterns that did not participate in
 614 the match. If the pattern specified no captures then the whole matched substring
 615 is returned. nil is returned if the pattern did not match.
 616
 617 [[lua_fn_gregex_find_subject___init____ef__]]
 618
 619 ===== gregex:find(subject, [init], [ef])
 620
 621 Searches for the first match of the regexp pattern in the string subject,
 622 starting from offset init, subject to flags ef.
 623
 624 Since: 1.11.3
 625
 626 [float]
 627 ===== Arguments
 628
 629 subject:: Subject string to search
 630
 631 init (optional):: start offset in the subject (can be negative)
 632
 633 ef (optional):: match execution flags (bitwise OR)
 634
 635 [float]
 636 ===== Returns
 637
 638 On success, returns the start point of the match (a number), the end point of
 639 the match (a number), and all substring matches ("captures"), in the order they
 640 appear in the pattern. false is returned for sub-patterns that did not
 641 participate in the match. On failure, returns nil.
 642
 643 [[lua_fn_gregex_exec_subject___init____ef__]]
 644
 645 ===== gregex:exec(subject, [init], [ef])
 646
 647 Searches for the first match of the compiled GRegex object in the string
 648 subject, starting from offset init, subject to the execution match flags ef.
 649
 650 Since: 1.11.3
 651
 652 [float]
 653 ===== Arguments
 654
 655 subject:: Subject string to search
 656
 657 init (optional):: start offset in the subject (can be negative)
 658
 659 ef (optional):: match execution flags (bitwise OR)
 660
 661 [float]
 662 ===== Returns
 663
 664 On success, returns the start point of the first match (a number), the end point
 665 of the first match (a number), and the offsets of substring matches (“captures”
 666 in Lua terminology) are returned as a third result, in a table. This table
 667 contains false in the positions where the corresponding sub-pattern did not
 668 participate in the match. On failure, returns nil. Example: If the whole match
 669 is at offsets 10,20 and substring matches are at offsets 12,14 and 16,19 then
 670 the function returns the following: 10, 20, { 12,14,16,19 }.
 671
 672 [[lua_fn_gregex_dfa_exec_subject___init____ef__]]
 673
 674 ===== gregex:dfa_exec(subject, [init], [ef])
 675
 676 Matches a compiled regular expression GRegex object against a given subject
 677 string subj, using a DFA matching algorithm.
 678
 679 Since: 1.11.3
 680
 681 [float]
 682 ===== Arguments
 683
 684 subject:: Subject string to search
 685
 686 init (optional):: start offset in the subject (can be negative)
 687
 688 ef (optional):: match execution flags (bitwise OR)
 689
 690 [float]
 691 ===== Returns
 692
 693 On success, returns the start point of the matches found (a number), a table
 694 containing the end points of the matches found, the longer matches first, and
 695 the number of matches found as the third return value. On failure, returns nil.
 696 Example: If there are 3 matches found starting at offset 10 and ending at
 697 offsets 15, 20 and 25 then the function returns the following: 10, { 25,20,15 },
 698 3
 699
 700 [[lua_fn_gregex___tostring__]]
 701
 702 ===== gregex:__tostring()
 703
 704 Returns a string containing debug information about the GRegex object.
 705
 706 Since: 1.11.3
 707
 708 [float]
 709 ===== Returns
 710
 711 The debug string