Debug::Client(3pm)

1Debug::Client(3)      User Contributed Perl Documentation     Debug::Client(3)
2
3
4

NAME

6       Debug::Client - debugger client side code for Padre, The Perl IDE.
7

VERSION

9       This document describes Debug::Client version: 0.30
10

SYNOPSIS

12         use Debug::Client;
13         my $debugger = Debug::Client->new(host => $host, port => $port);
14
15       Where $host is the host-name to be used by the script under test (SUT)
16       to access the machine where Debug::Client runs. If they are on the same
17       machine this should be "localhost".  $port can be any port number where
18       the Debug::Client could listen.
19
20       This is the point where the external SUT needs to be launched
21        by first setting
22
23         $ENV{PERLDB_OPTS} = "RemotePort=$host:$port"
24
25       then running
26
27         perl -d script
28
29       Once the script under test was launched we can call the following:
30
31         my $out = $debugger->get;
32
33         $out = $debugger->step_in;
34
35         $out = $debugger->step_over;
36
37
38         my ($prompt, $module, $file, $row, $content) = $debugger->step_in;
39         my ($module, $file, $row, $content, $return_value) = $debugger->step_out;
40         my $value = $debugger->get_value('$x');
41
42         $debugger->run();         # run till end of breakpoint or watch
43         $debugger->run( 42 );     # run till line 42  (c in the debugger)
44         $debugger->run( 'foo' );  # run till beginning of sub
45
46         $debugger->execute_code( '$answer = 42' );
47
48         $debugger->execute_code( '@name = qw(foo bar)' );
49
50         my $value = $debugger->get_value('@name'); # $value is the dumped data?
51
52         $debugger->execute_code( '%phone_book = (foo => 123, bar => 456)' );
53
54         my $value = $debugger->get_value('%phone_book'); # $value is the dumped data?
55
56         $debugger->set_breakpoint( "file", 23 ); # set breakpoint on file, line
57
58         $debugger->get_stack_trace
59
60   Example
61         my $script = 'script_to_debug.pl';
62         my @args   = ('param', 'param');
63
64         my $perl = $^X; # the perl might be a different perl
65         my $host = '127.0.0.1';
66         my $port = 24642;
67         my $pid = fork();
68         die if not defined $pid;
69
70         if (not $pid) {
71               local $ENV{PERLDB_OPTS} = "RemotePort=$host:$port"
72               exec("$perl -d $script @args");
73         }
74
75
76         require Debug::Client;
77         my $debugger = Debug::Client->new(
78           host => $host,
79           port => $port,
80         );
81         $debugger->listener;
82         my $out = $debugger->get;
83         $out = $debugger->step_in;
84         # ...
85

DESCRIPTION

87       This is a DEVELOPMENT Release only, you have been warned!
88
89       The primary use of this module is to provide debugger functionality for
90       Padre 0.98 and beyond,
91
92       This module has been tested against Perl 5.18.0
93

METHODS

95       new The constructor can get two parameters: host and port.
96
97             my $debugger = Debug::Client->new;
98
99             my $debugger = Debug::Client->new(host => 'remote.host.com', port => 24642);
100
101       get_buffer
102           Returns the content of the buffer since the last command
103
104             $debugger->get_buffer;
105
106       quit
107            $debugger->quit();
108
109       show_line
110           . (dot)
111
112           Return the internal debugger pointer to the line last executed, and
113           print out that line.
114
115            $debugger->show_line();
116
117       get_lineinfo
118           Return the internal debugger pointer to the line last executed,
119            and generate file-name and row for where are we now.
120            trying to use perl5db line-info in naff way,
121
122            $debugger->get_lineinfo();
123
124           Then use the following as and when.
125
126            $debugger->get_filename;
127            $debugger->get_row;
128
129           to get filename and row for ide due to changes in perl5db v1.35 see
130           perl5156delta
131
132       show_view
133           v [line]
134
135           View a few lines of code around the current line.
136
137            $debugger->show_view();
138
139       step_in
140           s [expr]
141
142           Single step.  Executes until the beginning of another statement,
143           descending into subroutine calls.
144            If an expression is supplied that includes function calls, it too
145           will be single-stepped.
146
147            $debugger->step_in();
148
149           Expressions not supported.
150
151       step_over
152            $debugger->step_over();
153
154       step_out
155            my ($prompt, $module, $file, $row, $content, $return_value) = $debugger->step_out();
156
157           Where $prompt is just a number, probably useless
158
159           $return_value  will be undef if the function was called in VOID
160           context
161
162           It will hold a scalar value if called in SCALAR context
163
164           It will hold a reference to an array if called in LIST context.
165
166           TODO: check what happens when the return value is a reference to a
167           complex data structure or when some of the elements of the returned
168           array are themselves references
169
170       get_stack_trace
171           Sends the stack trace command "T" to the remote debugger and
172           returns it as a string if called in scalar context.  Returns the
173           prompt number and the stack trace string when called in array
174           context.
175
176       toggle_trace
177           Sends the stack trace command "t" Toggle trace mode.
178
179            $debugger->toggle_trace();
180
181       list_subroutine_names
182           Sends the stack trace command "S" [[!]pattern]
183            List subroutine names [not] matching pattern.
184
185       run
186             $debugger->run;
187
188           Will run till the next breakpoint or watch or the end of the
189           script. (Like pressing c in the debugger).
190
191             $debugger->run($param)
192
193       set_breakpoint
194            $debugger->set_breakpoint($file, $line, $condition);
195
196           $condition is not currently used
197
198       remove_breakpoint
199            $debugger->remove_breakpoint( $self, $file, $line );
200
201       show_breakpoints
202           The data as (L) prints in the command line debugger.
203
204            $debugger->show_breakpoints();
205
206       get_value
207            my $value = $debugger->get_value($x);
208
209           If $x is a scalar value, $value will contain that value.  If it is
210           a reference to a ARRAY or HASH then $value should be the value of
211           that reference?
212
213       get_p_exp
214           p expr
215
216           Same as print {$DB::OUT} expr in the current package.  In
217           particular, because this is just Perl's own print function, this
218           means that nested data structures and objects are not dumped,
219           unlike with the x command.
220
221           The DB::OUT filehandle is opened to /dev/tty, regardless of where
222           STDOUT may be redirected to.  From perldebug, but defaulted to y 0
223
224             $debugger->get_p_exp();
225
226       get_y_zero
227           From perldebug, but defaulted to y 0
228
229            y [level [vars]]
230
231           Display all (or some) lexical variables (mnemonic: my variables) in
232           the current scope or level scopes higher. You can limit the
233           variables that you see with vars which works exactly as it does for
234           the V and X commands. Requires that the PadWalker module be
235           installed Output is pretty-printed in the same style as for V and
236           the format is controlled by the same options.
237
238             $debugger->get_y_zero();
239
240           which is now y=1 since perl 5.17.6,
241
242       get_v_vars
243           V [pkg [vars]]
244
245           Display all (or some) variables in package (defaulting to main )
246           using a data pretty-printer (hashes show their keys and values so
247           you see what's what, control characters are made printable, etc.).
248           Make sure you don't put the type specifier (like $ ) there, just
249           the symbol names, like this:
250
251            $debugger->get_v_vars(regex);
252
253       get_x_vars
254           X [vars] Same as V currentpackage [vars]
255
256            $debugger->get_x_vars(regex);
257
258       get_h_var
259           Enter h or `h h' for help, For more help, type h cmd_letter,
260           optional var
261
262            $debugger->get_h_var();
263
264       set_option
265           o booloption ...
266
267           Set each listed Boolean option to the value 1 .  o anyoption? ...
268
269           Print out the value of one or more options.  o option=value ...
270
271           Set the value of one or more options. If the value has internal
272           white-space, it should be quoted. For example, you could set o
273           pager="less -MQeicsNfr" to call less with those specific options.
274           You may use either single or double quotes, but if you do, you must
275           escape any embedded instances of same sort of quote you began with,
276           as well as any escaping any escapes that immediately precede that
277           quote but which are not meant to escape the quote itself.  In other
278           words, you follow single-quoting rules irrespective of the quote;
279           eg: o option='this isn\'t bad' or o option="She said, \"Isn't
280           it?\"" .
281
282           For historical reasons, the =value is optional, but defaults to 1
283           only where it is safe to do so--that is, mostly for Boolean
284           options.  It is always better to assign a specific value using = .
285           The option can be abbreviated, but for clarity probably should not
286           be. Several options can be set together.  See Configurable Options
287           for a list of these.
288
289            $debugger->set_option();
290
291       get_options
292           o
293
294           Display all options.
295
296            $debugger->get_options();
297
298       get Actually I think this is an internal method....
299
300           In SCALAR context will return all the buffer collected since the
301           last command.
302
303           In LIST context will return ($prompt, $module, $file, $row,
304           $content) Where $prompt is the what the standard debugger uses for
305           prompt. Probably not too interesting.  $file and $row describe the
306           location of the next instructions.  $content is the actual line -
307           this is probably not too interesting as it is in the editor.
308           $module is just the name of the module in which the current
309           execution is.
310
311       get_filename
312            $debugger->get_filename();
313
314       get_row
315            $debugger->get_row();
316
317       module
318            $debugger->module();
319
320   Internal Methods
321       •   _get
322
323       •   _process_line
324
325       •   _prompt
326
327       •   _send
328
329       •   _send_get
330

BUGS AND LIMITATIONS

332       If you get any issues installing, try install Term::ReadLine::Gnu
333       first.
334
335       Warning if you use List request you may get spurious results.
336
337       When using against perl5db.pl v1.35 list mode gives an undef response,
338       also leading single quote now correct.  Tests are skipped for list mode
339       against v1.35 now.
340
341       Debug::Client 0.12 tests are failing, due to changes in perl debugger,
342       when using perl5db.pl v1.34
343
344       Debug::Client 0.13_01 skips added to failing tests.
345
346        c [line|sub]
347
348       Continue, optionally inserting a one-time-only breakpoint at the
349       specified line or subroutine.
350
351        c is now ignoring options [line|sub]
352
353       and just performing c on it's own
354
355       Warning sub listen has bean deprecated
356
357       Has bean deprecated since 0.13_04 and all future version starting with
358       v0.14
359
360       Perl::Critic Error Subroutine name is a homonym for built-in function
361
362       Use $debugger->listener instead
363
364       It will work against perl 5.17.6-7 with rindolf patch 7a0fe8d applied
365       for watches
366

AUTHORS

368       Kevin Dawson <bowtie@cpan.org>
369
370       Gabor Szabo <gabor@szabgab.com>
371
372   CONTRIBUTORS
373       Breno G. de Oliveira <garu at cpan.org>
374
375       Ahmad M. Zawawi <ahmad.zawawi@gmail.com>
376
377       Mark Gardner <mjgardner@cpan.org>
378
379       Wolfram Humann <whumann@cpan.org>
380
381       Adam Kennedy <adamk@cpan.org>
382
383       Alexandr Ciornii <alexchorny@gmail.com>
384

COPYRIGHT

386       Copyright 2008-2011 Gabor Szabo
387
388       Some parts Copyright © 2011-2014 Kevin Dawson and CONTRIBUTORS as
389       listed above.
390

LICENSE

392       This program is free software; you can redistribute it and/or modify it
393       under the same terms as Perl 5 itself.
394

WARRANTY

396       There is no warranty whatsoever.  If you lose data or your hair because
397       of this program, that's your problem.
398

CREDITS and THANKS

400       Originally started out from the remote-port.pl script from Pro Perl
401       Debugging written by Richard Foley.
402