Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Update doc. Get ready for 0.41 release

  • Loading branch information...
commit e7c467a9dca9d142d2b74f7086b9a7ccb69585ca 1 parent 8721164
rocky authored
View
3  Build.PL
@@ -56,6 +56,7 @@ my $builder = Module::Build->new(
},
test_requires => {
'Test::More' => '0.81',
+ 'rlib' => '0.02',
},
recommends => {
'Data::Printer' => 0,
@@ -75,7 +76,7 @@ my $builder = Module::Build->new(
'Digest::SHA' => 0,
'PadWalker' => 0,
'Pod::Text' => 3.13,
- 'Syntax::Highlight::Perl::Improved' => 0,
+ 'Syntax::Highlight::Perl::Improved' => 1.01,
'rlib' => '0.02',
'version' => 0,
},
View
26 META.json
@@ -4,9 +4,9 @@
"Rocky Bernstein <rocky@cpan.org>"
],
"dynamic_config" : 1,
- "generated_by" : "Module::Build version 0.4, CPAN::Meta::Converter version 2.120921",
+ "generated_by" : "Module::Build version 0.4003, CPAN::Meta::Converter version 2.110440",
"license" : [
- "open_source"
+ "gpl_1"
],
"meta-spec" : {
"url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",
@@ -21,24 +21,24 @@
},
"runtime" : {
"recommends" : {
- "Data::Printer" : "0",
- "Devel::Callsite" : "0",
- "Eval::WithLexicals" : "0",
+ "Data::Printer" : 0,
+ "Devel::Callsite" : 0,
+ "Eval::WithLexicals" : 0,
"Pod::Text::Color" : "2.06",
- "Term::ReadKey" : "0",
- "Term::ReadLine::Perl" : "0"
+ "Term::ReadKey" : 0,
+ "Term::ReadLine::Perl" : 0
},
"requires" : {
"Array::Columnize" : "1.01",
- "Data::Dumper" : "0",
- "Digest::SHA" : "0",
+ "Data::Dumper" : 0,
+ "Digest::SHA" : 0,
"Getopt::Long" : "2.36",
- "PadWalker" : "0",
+ "PadWalker" : 0,
"Pod::Text" : "3.13",
- "Syntax::Highlight::Perl::Improved" : "0",
+ "Syntax::Highlight::Perl::Improved" : "1.01",
"perl" : "5.008008",
"rlib" : "0.02",
- "version" : "0"
+ "version" : 0
}
}
},
@@ -674,7 +674,7 @@
"web" : "https://github.com/rocky/Perl-Devel-Trepan/issues"
},
"license" : [
- "http://www.gnu.org/licenses/old-licenses/gpl-1.0.txt"
+ "http://opensource.org/licenses/gpl-license.php"
],
"repository" : {
"url" : "http://github.com/rocky/Perl-Devel-Trepan"
View
8 META.yml
@@ -6,8 +6,8 @@ build_requires: {}
configure_requires:
Module::Build: 0.32
dynamic_config: 1
-generated_by: 'Module::Build version 0.4, CPAN::Meta::Converter version 2.120921'
-license: open_source
+generated_by: 'Module::Build version 0.4003, CPAN::Meta::Converter version 2.110440'
+license: gpl
meta-spec:
url: http://module-build.sourceforge.net/META-spec-v1.4.html
version: 1.4
@@ -495,12 +495,12 @@ requires:
Getopt::Long: 2.36
PadWalker: 0
Pod::Text: 3.13
- Syntax::Highlight::Perl::Improved: 0
+ Syntax::Highlight::Perl::Improved: 1.01
perl: 5.008008
rlib: 0.02
version: 0
resources:
bugtracker: https://github.com/rocky/Perl-Devel-Trepan/issues
- license: http://www.gnu.org/licenses/old-licenses/gpl-1.0.txt
+ license: http://opensource.org/licenses/gpl-license.php
repository: http://github.com/rocky/Perl-Devel-Trepan
version: 0.40_01
View
205 lib/Devel/Trepan.pm
@@ -160,6 +160,10 @@ L</"Examining the call stack">
=item *
+L</"Support facilities">
+
+=item *
+
L</"Syntax of debugger commands">
=back
@@ -167,6 +171,11 @@ L</"Syntax of debugger commands">
=head3 Commands involving running the program
+The commands in the section involve controlling execution of the
+program, either by kinds of stepping (step into, step over, step out)
+restarting or termintating the program altogether. However setting
+breakpoints is in L</Making the program stop at certain points>.
+
=over
=item *
@@ -187,7 +196,7 @@ L</"Step out (finish)">
=item *
-L</"Terminate gently (quit)">
+L</"Gently exit debugged program (quit)">
=item *
@@ -265,18 +274,18 @@ B<finish>
Continue execution until the program is about to leave the current
function. Sometimes this is called 'step out'.
-=head4 Terminate gently (quit)
+=head4 Gently exit debugged program (quit)
B<quit>[B<!>] [B<unconditionally>] [I<exit-code>]
Gently exit the debugger and debugged program.
-The program being debugged is exited via I<exit()> which runs the Kernel
-I<at_exit> finalizers. If a return code is given, that is the return code
-passed to I<exit()> - presumably the return code that will be passed back
-to the OS. If no exit code is given, 0 is used.
+The program being debugged is exited via I<exit()> which runs the
+Kernel I<at_exit()> finalizers. If a return code is given, that is the
+return code passed to I<exit()> - presumably the return code that will
+be passed back to the OS. If no exit code is given, 0 is used.
-I<Examples:>
+B<Examples:>
quit # quit prompting if we are interactive
quit unconditionally # quit without prompting
@@ -284,8 +293,8 @@ I<Examples:>
quit 0 # same as "quit"
quit! 1 # unconditional quit setting exit code 1
-See also L<C<kill>|Devel::Trepan::CmdProcessor::Command::Kill> and
-C<set confirm>.
+See also C<set confirm> and
+L<C<kill>|Devel::Trepan::CmdProcessor::Command::Kill>.
=head4 Hard termination (kill)
@@ -384,6 +393,18 @@ I<Examples:>
=head3 Making the program stop at certain points
+A I<Breakpoint> is a way to have the program stop at a pre-determined
+location. A breakpoint can be perminant or one-time. A one-time
+breakpoint is removed as soon as it is hit. In a sense, stepping is
+like setting one-time breakpoints. Breakpoints can also be disabled
+which allows you to temporarily ignore stopping at that breakpoint
+while it is disabled. Finally one can control conditions under which a
+breakpoint is enacted upon.
+
+Another way to force a stop is to watch to see if the value of an
+expression changes. Often that expression is simply examinging a
+variable's value.
+
=over
=item *
@@ -548,6 +569,22 @@ I<Examples:>
=head3 Examining the call stack
+The commands in this section show the call stack and let set a
+reference for the default call stack which other commands like C<list>
+or C<break> use as a position when one is not specified.
+
+The most recent call stack entry is 0. Except for the relative motion
+commands C<up> and C<down>, you can refer to the oldest or top-level
+stack entry with -1 and negative numbers refer to the stack from the
+other end.
+
+Beware that in contrast to debuggers in other programming languages,
+Perl really doesn't have an easy way for one to evaluate statements
+and expressions other than at the most recent call stack. There are
+ways to see lexical variables I<my> and I<our>, however localized
+variables which can hide global variables and other lexicals variables
+can be problematic.
+
=over
=item *
@@ -568,7 +605,7 @@ L</"Move to a less recent frame (down)">
=back
-=head4 Print call stack (backtrace)
+=head4 Print all or parts of the call stack (backtrace)
B<backtrace> [I<count>]
@@ -618,6 +655,154 @@ B<down> [I<count>]
Move the current frame down in the stack trace (to a newer frame). 0
is the most recent frame. If no count is given, move down 1.
+=head3 Support facilities
+
+=over
+
+=item *
+
+L</"Define an alias (alias)">
+
+=item *
+
+L</"Remove an alias (unalias)">
+
+=item *
+
+L</"Define a macro (macro)">
+
+=item *
+
+L</"Allow remote connections (server)">
+
+=item *
+
+L</"Run debugger commands from a file (source)">
+
+=back
+
+=head4 Define an alias
+
+B<alias> I<alias> I<command>
+
+Add alias I<alias> for a debugger command I<command>.
+
+Add an alias when you want to use a command abbreviation for a command
+that would otherwise be ambigous. For example, by default we make C<s>
+be an alias of C<step> to force it to be used. Without the alias, C<s>
+might be C<step>, C<show>, or C<set>, among others.
+
+B<Examples:>
+
+ alias cat list # "cat file.pl" is the same as "list file.pl"
+ alias s step # "s" is now an alias for "step".
+ # The above examples done by default.
+
+For more complex definitions, see C<macro>.
+See also C<unalias> and C<show alias>.
+
+=head4 Remove an unalias
+
+B<unalias> I<alias1> [I<alias2> ...]
+
+Remove alias I<alias1> and so on.
+
+B<Example:>
+
+ unalias s # Remove 's' as an alias for 'step'
+
+See also C<alias>.
+
+
+=head4 Define a debugger macro
+
+B<macro> I<macro-name> B<sub {> ... B<}>
+
+Define I<macro-name> as a debugger macro. Debugger macros get a list of
+arguments which you supply without parenthesis or commas. See below
+for an example.
+
+The macro (really a Perl anonymous subroutine) should return either a
+string or an array reference to a list of strings. The string in both
+cases are strings of debugger commands. If the return is a string,
+that gets tokenized by a simple C<split(/ /, $string)>. Note that
+macro processing is done right after splitting on C<;;> so if the macro
+returns a string containing C<;;> this will not be handled on the
+string returned.
+
+If instead, a reference to a list of strings is returned, then the
+first string is shifted from the array and executed. The remaining
+strings are pushed onto the command queue. In contrast to the first
+string, subsequent strings can contain other macros. Any C<;;> in those
+strings will be split into separate commands.
+
+B<Examples:>
+
+The below creates a macro called I<fin+> which issues two commands
+C<finish> followed by C<step>:
+
+ macro fin+ sub{ ['finish', 'step']}
+
+If you wanted to parameterize the argument of the C<finish> command
+you could do it this way:
+
+ macro fin+ sub{ \
+ ['finish', 'step ' . (shift)] \
+ }
+
+Invoking with:
+
+ fin+ 3
+
+would expand to C<["finish", "step 3"]>
+
+If you were to add another parameter, note that the invocation is like
+you use for other debugger commands, no commas or parenthesis. That is:
+
+ fin+ 3 2
+
+rather than C<fin+(3,2)> or C<fin+ 3, 2>.
+
+See also C<info macro>.
+
+=head4 Gently exit debugged program (quit)
+
+B<quit>[B<!>] [B<unconditionally>] [I<exit-code>]
+
+=head4 Allow remote debugger connections (server)
+
+B<server> [I<options>]
+
+options:
+
+ -p | --port NUMBER
+ -a | --address
+
+Suspends interactive debugger session and puts debugger in server mode
+which opens a socket for debugger connections
+
+=head4 Run debugger commands from a file (source)
+
+B<source> [I<options>] I<file>
+
+options:
+
+ -q | --quiet | --no-quiet
+ -c | --continue | --no-continue
+ -Y | --yes | -N | --no
+ -v | --verbose | --no-verbose
+
+Read debugger commands from a file named I<file>. Optional C<-v> switch
+causes each command in FILE to be echoed as it is executed. Option C<-Y>
+sets the default value in any confirmation command to be 'yes' and C<-N>
+sets the default value to 'no'.
+
+Option C<-q> will turn off any debugger output that normally occurs in
+the running of the program.
+
+An error in any command terminates execution of the command file
+unless option C<-c> or C<--continue> is given.
+
=head3 Syntax of debugger commands
=head4 Overall Debugger Command Syntax
View
7 lib/Devel/Trepan/CmdProcessor/Command/Alias.pm
@@ -21,10 +21,10 @@ use strict; use vars qw(@ISA); @ISA = @CMD_ISA;
use vars @CMD_VARS; # Value inherited from parent
our $NAME = set_name();
-our $HELP = <<"HELP";
+our $HELP = <<'HELP';
=pod
-B<${NAME}> I<alias> I<command>
+B<alias> I<alias> I<command>
Add alias I<alias> for a debugger command I<command>.
@@ -39,7 +39,8 @@ might be C<step>, C<show>, or C<set>, among others.
alias s step # "s" is now an alias for "step".
# The above examples done by default.
-See also C<unalias> and C<show> ${NAME}.
+For more complex definitions, see C<macro>.
+See also C<unalias> and C<show alias>.
=cut
HELP
View
4 lib/Devel/Trepan/CmdProcessor/Command/Macro.pm
@@ -45,13 +45,13 @@ strings will be split into separate commands.
=head2 Examples:
-The below creates a macro called fin+ which issues two commands
+The below creates a macro called I<fin+> which issues two commands
C<finish> followed by C<step>:
macro fin+ sub{ ['finish', 'step']}
If you wanted to parameterize the argument of the C<finish> command
-you could do that this way:
+you could do it this way:
macro fin+ sub{ \
['finish', 'step ' . (shift)] \
View
4 lib/Devel/Trepan/CmdProcessor/Command/Quit.pm
@@ -9,8 +9,8 @@ use if !@ISA, Devel::Trepan::CmdProcessor::Command ;
unless (@ISA) {
eval <<'EOE';
use constant ALIASES => ('quit!', 'q', 'q!');
-use constant CATEGORY => 'support';
-use constant SHORT_HELP => 'Quit program - gently';
+use constant CATEGORY => 'running';
+use constant SHORT_HELP => 'Gently exit debugged program';
use constant MIN_ARGS => 0; # Need at least this many
use constant MAX_ARGS => 2; # Need at most this many - undef -> unlimited.
EOE
View
10 lib/Devel/Trepan/CmdProcessor/Command/Server.pm
@@ -16,7 +16,7 @@ use if !@ISA, Devel::Trepan::CmdProcessor::Command ;
unless (@ISA) {
eval <<'EOE';
use constant CATEGORY => 'support';
-use constant SHORT_HELP => 'Allow remote connections';
+use constant SHORT_HELP => 'Allow remote debugger connections';
use constant MIN_ARGS => 0; # Need at least this many
use constant MAX_ARGS => undef; # Need at most this many - undef -> unlimited.
EOE
@@ -28,17 +28,19 @@ use vars qw(@ISA); @ISA = qw(Devel::Trepan::CmdProcessor::Command);
use vars @CMD_VARS; # Value inherited from parent
$NAME = set_name();
-$HELP = <<"HELP";
+$HELP = <<'HELP';
=pod
-server [I<options>]
+B<server> [I<options>]
options:
-p | --port NUMBER
-a | --address
-Put debugger in server mode which opens a socket for debugger connections
+Suspends interactive debugger session and puts debugger in server mode
+which opens a socket for debugger connections
+
=cut
HELP
View
4 lib/Devel/Trepan/CmdProcessor/Command/Source.pm
@@ -20,7 +20,7 @@ use if !@ISA, Devel::Trepan::CmdProcessor::Command ;
unless (@ISA) {
eval <<'EOE';
use constant CATEGORY => 'support';
-use constant SHORT_HELP => 'Read and run debugger commands from a file';
+use constant SHORT_HELP => 'Run debugger commands from a file';
use constant MIN_ARGS => 1; # Need at least this many
use constant MAX_ARGS => undef; # Need at most this many - undef -> unlimited.
use constant NEED_STACK => 0;
@@ -36,7 +36,7 @@ our $NAME = set_name();
our $HELP = <<'HELP';
=pod
-source [I<options>] I<file>
+B<source> [I<options>] I<file>
options:
View
8 lib/Devel/Trepan/CmdProcessor/Command/Unalias.pm
@@ -24,9 +24,13 @@ our $NAME = set_name();
our $HELP = <<'HELP';
=pod
-unalias I<alias>
+B<unalias> I<alias1> [I<alias2> ...]
-Remove alias I<alias>
+Remove alias I<alias1> and so on.
+
+B<Example:>
+
+ unalias s # Remove 's' as an alias for 'step'
See also C<alias>.
=cut
View
65 lib/Devel/Trepan/DB/LineCache.pm
@@ -343,7 +343,7 @@ sub cache_file($;$$)
B<cache(I<$file_or_script>)> => I<boolean>
-Return true if I<$file_or_script> is cached.
+Return I<true> if I<$file_or_script> is cached.
=cut
@@ -496,7 +496,7 @@ sub getlines($;$)
B<highlight_string($string)> => I<marked-up-string>
Add syntax-formatting characters via
-L<Syntax::Highlight::Pel::Improved> to I<string> according to table
+L<Syntax::Highlight::Pel::Improved> to I<marked-up-string> according to table
given in L<Devel::Trepan::DB::Colors>.
=cut
@@ -527,6 +527,29 @@ sub path($)
$file_cache{$filename}->path();
}
+=pod
+
+=head2 remap_file
+
+B<remap_file($from_file, $to_file)> => $to_file
+
+Set to make any lookups retriving lines from of I<$from_file> refer to
+I<$to_file>.
+
+B<Example>:
+
+Running:
+
+ use Devel::Trepan::DB::LineCache;
+ DB::LineCache::remap_file('another_name', __FILE__);
+ print DB::LineCache::getline('another_name', __LINE__), "\n";
+
+gives:
+
+ print DB::LineCache::getline('another_name', __LINE__), "\n";
+
+=cut
+
sub remap_file($$)
{
my ($from_file, $to_file) = @_;
@@ -692,6 +715,11 @@ Return an array of line numbers in (control opcodes) COP in
$I<filename>. These line numbers are the places where a breakpoint
might be set in a debugger.
+We get this information from the Perl run-time, so that should have
+been set up for this to take effect. See L<B::CodeLines> for a way to
+get this information, basically by running an Perl invocation that has
+this set up.
+
=cut
sub trace_line_numbers($;$)
@@ -710,6 +738,9 @@ B<is_trace_line($filename, $line_num [,$reload_on_change])> => I<boolean>
Return I<true> if I<$line_num> is a trace line number of I<$filename>.
+See the comment in L<trace_line_numbers> regarding run-time setup that
+needs to take place for this to work.
+
=cut
sub is_trace_line($$;$)
@@ -720,13 +751,37 @@ sub is_trace_line($$;$)
return !!$file_cache{$filename}{trace_nums}{$line_num};
}
+=pod
+
+=head2 map_file
+
+B<map_file($filename)> => string
+
+A previous invocation of I<remap_file()> could have mapped
+I<$filename> into something else. If that is the case we return the
+name that I<$filename> was mapped into. Otherwise we return I<$filename>
+
+=cut
+
sub map_file($)
{
- my $file = shift;
- return undef unless defined($file);
- $file2file_remap{$file} ? $file2file_remap{$file} : $file
+ my $filename = shift;
+ return undef unless defined($filename);
+ $file2file_remap{$filename} ? $file2file_remap{$filename} : $filename
}
+=pod
+
+=head2 map_script
+
+B<map_script($script)> => string
+
+A previous invocation of I<remap_file()> could have mapped I<$script>
+(a pseudo-file name that I<eval()> uses) into something else. If that
+is the case we return the name that I<$script> was mapped
+into. Otherwise we return I<$script>
+
+=cut
use File::Temp qw(tempfile);
sub map_script($$)
{

0 comments on commit e7c467a

Please sign in to comment.
Something went wrong with that request. Please try again.