Display mode configuration

    # Show dynamic visualization of matching (the default)...
    display : visual

    # Show dynamic heatmap visualization of matching...
    display : heatmap

    # Show multi-line matching event log...
    display : events

    # Show JSON encoding of matching process...
    display : JSON

Whitespace display configuration

    # Compact whitespace and comments to a single space (the default)...
    show_ws : compact

    # Compact whitespace, but show comments, newlines (\n), and tabs (\t)...
    show_ws : visible

    # Don't compact whitespace, and show newlines and tabs as \n and \t...
    show_ws : original

Colour configuration

Colours for debugging information

• "try_col"

  The colour in which attempts to match part of the regex are reported

• "match_col"

  The colour in which successful matches of part of the regex are reported

• "fail_col"

  The colour in which unsuccessful matches of part of the regex are reported

• "ws_col"

  The colour in which special characters (such as "\n", "\t", "\e", etc.) are reported (as single letters: 'n', 't', 'e', etc.)

• "info_col"

  The colour in which other information is reported

Colours for regex descriptions

• "desc_regex_col"

  The colour in which components of the regex are displayed

• "desc_text_col"

  The colour in which descriptions of regex components are displayed

• "desc_sep_col"

  The colour in which separators between component descriptions are displayed.

Colours for heatmaps

Any key that starts with "heatmap"... is treated as a specifier for an equal part of the total range of each heatmap.

These names are sorted (numerically, if possible; otherwise alphabetically) and the corresponding values are then used to display equal percentiles from the heatmap.

For example (using numeric sorting):

    heatmap_0_colour      : cyan   on_black   #  0-33rd  percentile
    heatmap_50_colour     : yellow on_black   # 34-66th  percentile
    heatmap_100_colour    : red    on_black   # 67-100th percentile

Or, equivalently (using alphabetic sorting):

    heatmap_infrequent    : cyan   on_black   #  0-33rd  percentile
    heatmap_more_frequent : yellow on_black   # 34-66th  percentile
    heatmap_very_frequent : red    on_black   # 67-100th percentile

Colour specifications

The colour values that may be used in any of the above colour specifications are any combination of the following (i.e. the colour specifiers supported by the Term::ANSIColor module):

         clear           reset             bold            dark
         faint           underline         underscore      blink
         reverse         concealed

         black           red               green           yellow
         blue            magenta           cyan            white
         bright_black    bright_red        bright_green    bright_yellow
         bright_blue     bright_magenta    bright_cyan     bright_white

         on_black        on_red            on_green        on_yellow
         on_blue         on_magenta        on_cyan         on_white
         on_bright_black on_bright_red     on_bright_green on_bright_yellow
         on_bright_blue  on_bright_magenta on_bright_cyan  on_bright_white

The default colour configurations are:

    try_col    :  bold magenta  on_black
    match_col  :  bold cyan     on_black
    fail_col   :       yellow   on_red
    ws_col     :  bold blue     underline
    info_col   :       white    on_black

    desc_regex_col  :  white    on_black
    desc_text_col   :  cyan     on_black
    desc_sep_col    :  blue     on_black underline

    heatmap__20th_percentile  :  white   on_black
    heatmap__40th_percentile  :  cyan    on_blue
    heatmap__60th_percentile  :  blue    on_cyan
    heatmap__80th_percentile  :  red     on_yellow
    heatmap_100th_percentile  :  yellow  on_red

Output configuration

However, you can configure the module to output its information (in standard JSON format) to a nominated file instead, using the 'save_to' option:

    save_to : filename_to_save_data_to.json

Data saved in this way may be re-animated using the "rxrx" utility, or by calling "Regexp::Debugger::rxrx()" directly. (See: "COMMAND-LINE DEBUGGING" for details).

Configuration API

For example:

    use Regexp::Debugger  fail => 'bold red',  whitespace => 'compact';

Note that any configuration specified in the user's .rxrx file is overridden by an explicit specification of this type.

The commonest use of this mechanism is to dump regex debugging information from an non-interactive program:

    use Regexp::Debugger  save_to => 'regex_debugged.json';

Note that, when 'save_to' is specified within a program, the value supplied does not have to be a string specifying the filename. You can also provide an actual filehandle (or equivalent). For example:

    use Regexp::Debugger save_to => IO::Socket::INET->new(
                                        Proto     => "tcp",
                                        PeerAddr  => 'localhost:666',
                                    );

Regex debugging REPL

• Any line starting with a "/" is treated as a new regex to match with. The closing "/" may be omitted. If the closing "/" is supplied, any one or more of the following flags may be specified immediately after it: "x", "i", "m", "s", "a", "u", "d", "l".
• Any line starting with a "+/" is treated as the first line of a new multi- line regex to match with. Subsequent lines are added to the regex until the closing "/" is encountered. Any one or more of the following flags may be specified immediately after the closing "/": "x", "i", "m", "s", "a", "u", "d", "l".
• Any line starting with a "'" or """ is treated as a new string to match against. The corresponding closing delimiter may be omitted.
• Any line beginning with "m" causes the REPL to match the current regex against the current string, visualizing the match in the usual way.
• Any line beginning with "g" causes the REPL to exhaustively match the current regex against the current string (i.e. as if the regex had a /g flag), visualizing all the matches in the usual way.
• Any line beginning with "d" causes the REPL to display a detailed decomposition and explanation of the current regex.
• Any line beginning with "q" or "x" causes the REPL to quit and exit.
• Any line beginning with "?" invokes the help listing for the REPL.

If the IO::Prompter module (version 0.004 or later) is available, the input process remembers its history, which you can recall by typing "CTRL-R". Repeated "CTRL-R"'s step successively backwards through earlier inputs. "CTRL-N" steps successfully forward again. You can then use "CTRL-B"/"CTRL-F"/"CTRL-A"/"CTRL-E" to move the cursor around the line of recalled input, to delete or insert characters. This is useful for modifying and retrying a recently entered regex or string.

Debugging regexes from a dumped session

This is useful for debugging non-interactive programs where the 'save_to' option was used (see "Output configuration" and "Configuration API").

In this mode, all the features of the interactive debugger (as listed under "INTERFACE") are fully available: you can step forwards and backwards through the match, skip to the successful submatch or a breakpoint, swap visualization modes, and take snapshots.

Wrap-around regex debugging

    rxrx prog.pl

is a convenient shorthand for:

    perl -MRegexp::Debugger prog.pl

"/x"-mode comments

When processing a "# comment to end of line" within a regex, the module currently assumes a "/x" is in effect at start of the regex (unless that assumption causes the regex to fail to compile). This will sometimes cause erroneous behaviour if an unescaped "#" is used in a non-"/x" regex.

Unfortunately, this limitation is unlikely to be fully removed in a future release, unless an additional flag-detection mechanism is added to "overload::constant()".

Note, however, that this limitation does not affect the handling of comments in "(?x:...)" blocks or of literal "#" in "(?-x:...)" blocks within a regex. These are always correctly handled, which means that explicitly using either of these blocks is a reliable workaround. Alternatively, there is no problem if you always use the "/x" modifier on every debugged regex (for example, via "use re '/x'"). Nor if you explicitly escape every literal "#" (i.e. write it as "\#").

As regards whitespace, the one case where the current implementation does not always correctly infer behaviour is where whitespace is used to separate a repetition qualifier from the atom it qualifies in a non-"/x" regex, such as:

    / x + /

Because the module defaults to assuming that regexes always have "/x" applied, this is always interpreted as:

    /\ x+\ /x

rather than what it really is, namely:

    /\ x\ +\ /

The most reliable workaround for the time being is either to always use "/x" on any regex, or never to separate repetition qualifiers from their preceding atoms.

Multiple 'save_to' with the same target

This limitation will be removed in a subsequent release (but this will certainly involve a small change to the structure of the JSON data that is written, even when only one "save_to" is specified).

Variable interpolations

However, it currently does not correctly handle the interpolation of "qr"'d regexes. That is, this:

    use Regexp::Debugger;

    my $ident = qr{ [^\W\d]\w* }x;      # a qr'd regex...

    $str =~ m{ ($ident) : (.*) }xms;    # ...interpolated into another regex

does not work correctly...and usually will not even compile.

It is expected that this limitation will be removed in a future release, however it may only be possible to fix the problem for more recent versions of Perl (i.e. 5.14 and later) in which the regex engine is re-entrant.