LOGO

 ____              _   _
|  _ \ _   _ _ __ | |_(_)_ __ ___   ___
| |_) | | | | '_ \| __| | '_ ` _ \ / _ \
|  _ <| |_| | | | | |_| | | | | | |  __/
|_| \_\\__,_|_| |_|\__|_|_| |_| |_|\___|

 ____       _
|  _ \  ___| |__  _   _  __ _  __ _  ___ _ __
| | | |/ _ \ '_ \| | | |/ _` |/ _` |/ _ \ '__|
| |_| |  __/ |_) | |_| | (_| | (_| |  __/ |
|____/ \___|_.__/ \__,_|\__, |\__, |\___|_|
                        |___/ |___/

NAME

Runtime::Debugger - Easy to use REPL with existing lexicals support.

(empahsis on "existing" since I have not yet found this support in others modules).

SYNOPSIS

Start the debugger:

    perl -MRuntime::Debugger -E 'eval run'

Same, but with some variables to play with:

    perl -MRuntime::Debugger -E 'my $str1 = "Func"; our $str2 = "Func2"; my @arr1 = "arr-1"; our @arr2 = "arr-2"; my %hash1 = qw(hash 1); our %hash2 = qw(hash 2); my $coderef = sub { "code-ref: @_" }; {package My; sub Func{"My-Func"} sub Func2{"My-Func2"}} my $obj = bless {}, "My"; eval run; say $@'

DESCRIPTION

"What? Another debugger? What about ... ?"

perl5db.pl

The standard perl debugger (perl5db.pl) is a powerful tool.

Using per5db.pl, one would normally be able to do this:

    # Insert a breakpoint in your code:
    $DB::single = 1;

    # Then run the perl debugger to navigate there quickly:
    PERLDBOPT='Nonstop' perl -d my_script

If that works for you, then dont' bother with this module! (joke. still try it.)

Dilemma

I have this scenario:

 - A perl script gets executed.
 - The script calls a support module.
 - The module reads a test file.
 - The module string evals the string contents of the test file.
 - The test takes possibly minutes to run (Selenium).
 - The test is failing.
 - Not sure what is failing.

Normal workflow would be:

 - Step 1: Apply a fix.
 - Step 2: Run the test.
 - Step 3: Wait ... wait ... wait.
 - Step 4: Goto Step 1 if test fails.

Solution

This module basically inserts a read, evaluate, print loop (REPL) wherever you need it.

    use Runtime::Debugger;
    eval run;

Tab Completion

The module support rich tab completion support:

 - Press TAB with no input to view commands and available variables in the current scope.
 -

TODO

Press tab to autocomplete any lexical variables in scope (where "eval run" is found).

Saves history locally.

Can use 'p' to pretty print a variable or structure.

Ideas

Not sure how to avoid using eval here while keeping access to the top level lexical scope.

(Maybe through abuse of PadWalker and modifying input dynamically.)

Any ideas ? :)

New Variables

Currently its not possible to create any new lexicals variables while I have not yet found a way to run "eval" with a higher scope of lexicals. (perhaps there is another way?)

You can make global variables though if:

 - By default ($var=123)
 - Using our (our $var=123)
 - Given the full path ($My::var = 123)

SUBROUTINES/METHODS

run

Runs the REPL (dont forget eval!)

 eval run

Sets $@ to the exit reason like 'INT' (Control-C) or 'q' (Normal exit/quit).

_match

Returns the possible matches:

Input:

 words   => ARRAYREF, # What to look for.
 partial => STRING,   # Default: ""  - What you typed so far.
 prepend => "STRING", # Default: ""  - prepend to each possiblity.
 nospace => 0,        # Default: "0" - will not append a space after a completion.

help

Show help section.

hist

Show history of commands.

By default will show 20 commands:

 hist

Same thing:

 hist 20

Can show more:

 hist 50

p

Data::Dumper::Dump anything.

 p 123
 p [1, 2, 3]

Can adjust the maxdepth (default is 1) to see with: "#Number".

 p { a => [1, 2, 3] } #1

Output:

 {
   'a' => 'ARRAY(0x55fd914a3d80)'
 }

Set maxdepth to '0' to show all nested structures.

attr

Internal use.

debug

Internal use.

term

Internal use.

ENVIRONMENT

Install required library:

 sudo apt install libreadline-dev

Enable this environmental variable to show debugging information:

 RUNTIME_DEBUGGER_DEBUG=1

SEE ALSO

https://metacpan.org/pod/Devel::REPL

Great extendable module!

Unfortunately, I did not find a way to get the lexical variables in a scope. (maybe I missed a plugin?!)

https://metacpan.org/pod/Reply

This module also looked nice, but same issue.

AUTHOR

Tim Potapov, <tim.potapov[AT]gmail.com> 🐪🥷

BUGS

- no new lexicals

Please report any (other) bugs or feature requests to https://github.com/poti1/runtime-debugger/issues.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Runtime::Debugger

You can also look for information at:

https://metacpan.org/pod/Runtime::Debugger https://github.com/poti1/runtime-debugger

LICENSE AND COPYRIGHT

This software is Copyright (c) 2022 by Tim Potapov.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

cpanm Runtime::Debugger

perl -MCPAN -e shell
install Runtime::Debugger