File: README

package info (click to toggle)
libdebug-client-perl 0.20-1
  • links: PTS, VCS
  • area: main
  • in suites: wheezy
  • size: 396 kB
  • sloc: perl: 2,867; makefile: 2
file content (404 lines) | stat: -rw-r--r-- 11,744 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
NAME
    Debug::Client - debugger client side code for Padre, The Perl IDE.

VERSION
    This document describes Debug::Client version 0.20

SYNOPSIS
      use Debug::Client;
      my $debugger = Debug::Client->new(host => $host, port => $port);
      $debugger->listener;

    Where $host is the host-name to be used by the script under test (SUT)
    to access the machine where Debug::Client runs. If they are on the same
    machine this should be "localhost". $port can be any port number where
    the Debug::Client could listen.

    This is the point where the external SUT needs to be launched by first
    setting

      $ENV{PERLDB_OPTS} = "RemotePort=$host:$port"

    then running

      perl -d script

    Once the script under test was launched we can call the following:

      my $out = $debugger->get;

      $out = $debugger->step_in;

      $out = $debugger->step_over;


      my ($prompt, $module, $file, $row, $content) = $debugger->step_in;
      my ($module, $file, $row, $content, $return_value) = $debugger->step_out;
      my $value = $debugger->get_value('$x');

      $debugger->run();         # run till end of breakpoint or watch
      $debugger->run( 42 );     # run till line 42  (c in the debugger)
      $debugger->run( 'foo' );  # run till beginning of sub

      $debugger->execute_code( '$answer = 42' );

      $debugger->execute_code( '@name = qw(foo bar)' );

      my $value = $debugger->get_value('@name');  $value is the dumped data?

      $debugger->execute_code( '%phone_book = (foo => 123, bar => 456)' );

      my $value = $debugger->get_value('%phone_book');  $value is the dumped data?
  
  
      $debugger->set_breakpoint( "file", 23 ); # set breakpoint on file, line

      $debugger->get_stack_trace

  Example
      my $script = 'script_to_debug.pl';
      my @args   = ('param', 'param');
  
      my $perl = $^X; # the perl might be a different perl
      my $host = 'localhost';
      my $port = 24642;
      my $pid = fork();
      die if not defined $pid;
  
      if (not $pid) {
            local $ENV{PERLDB_OPTS} = "RemotePort=$host:$port"
            exec("$perl -d $script @args");
      }
  
  
      require Debug::Client;
      my $debugger = Debug::Client->new(
        host => $host,
        port => $port,
      );
      $debugger->listener;
      my $out = $debugger->get;
      $out = $debugger->step_in;
      # ...

DESCRIPTION
    The prime use of this module is to provide debugger functionality for
    Padre 0.94+,

    This module should be Perl 5.16.0 ready.

METHODS
    new The constructor can get two parameters: host and port.

          my $debugger = Debug::Client->new;

          my $debugger = Debug::Client->new(host => 'remote.host.com', port => 24642);

        Immediately after the object creation one needs to call

          $debugger->listener;

        TODO: Is there any reason to separate the two?

    listener
        listener/hearken To listen attentively; give heed. See "BUGS AND
        LIMITATIONS"

        See "new"

         $debugger->listener

    buffer
        Returns the content of the buffer since the last command

          $debugger->buffer;

    quit
         $debugger->quit();

    show_line
        . (dot)

        Return the internal debugger pointer to the line last executed, and
        print out that line.

         $debugger->show_line();

    get_lineinfo
        Return the internal debugger pointer to the line last executed, and
        generate file-name and row for where are we now. trying to use
        perl5db line-info in naff way,

         $debugger->get_lineinfo();

        Then use the following as and when.

         $debugger->filename;
         $debugger->row;

        to get filename and row for ide due to changes in perl5db v1.35 see
        perl5156delta

    show_view
        v [line]

        View a few lines of code around the current line.

         $debugger->show_view();

    step_in
        s [expr]

        Single step. Executes until the beginning of another statement,
        descending into subroutine calls. If an expression is supplied that
        includes function calls, it too will be single-stepped.

         $debugger->step_in();

        Expressions not supported.

    step_over
         $debugger->step_over();

    step_out
         my ($prompt, $module, $file, $row, $content, $return_value) = $debugger->step_out();

        Where $prompt is just a number, probably useless

        $return_value will be undef if the function was called in VOID
        context

        It will hold a scalar value if called in SCALAR context

        It will hold a reference to an array if called in LIST context.

        TODO: check what happens when the return value is a reference to a
        complex data structure or when some of the elements of the returned
        array are themselves references

    get_stack_trace
        Sends the stack trace command "T" to the remote debugger and returns
        it as a string if called in scalar context. Returns the prompt
        number and the stack trace string when called in array context.

    toggle_trace
        Sends the stack trace command "t" Toggle trace mode.

         $debugger->toggle_trace();

    list_subroutine_names
        Sends the stack trace command "S" [[!]pattern] List subroutine names
        [not] matching pattern.

    run
          $debugger->run;

        Will run till the next breakpoint or watch or the end of the script.
        (Like pressing c in the debugger).

          $debugger->run($param)

    set_breakpoint
         $debugger->set_breakpoint($file, $line, $condition);

        *$condition is not currently used*

    remove_breakpoint
         $debugger->remove_breakpoint( $self, $file, $line );

    show_breakpoints
        The data as (L) prints in the command line debugger.

         $debugger->show_breakpoints();

    get_value
         my $value = $debugger->get_value($x);

        If $x is a scalar value, $value will contain that value. If it is a
        reference to a ARRAY or HASH then $value should be the value of that
        reference?

    get_p_exp
        p expr

        Same as print {$DB::OUT} expr in the current package. In particular,
        because this is just Perl's own print function, this means that
        nested data structures and objects are not dumped, unlike with the x
        command.

        The DB::OUT filehandle is opened to /dev/tty, regardless of where
        STDOUT may be redirected to. From perldebug, but defaulted to y 0

          $debugger->get_p_exp();

    get_y_zero
        From perldebug, but defaulted to y 0

         y [level [vars]]

        Display all (or some) lexical variables (mnemonic: my variables) in
        the current scope or level scopes higher. You can limit the
        variables that you see with vars which works exactly as it does for
        the V and X commands. Requires the PadWalker module version 0.08 or
        higher; will warn if this isn't installed. Output is pretty-printed
        in the same style as for V and the format is controlled by the same
        options.

          $debugger->get_y_zero();

    get_v_vars
        V [pkg [vars]]

        Display all (or some) variables in package (defaulting to main )
        using a data pretty-printer (hashes show their keys and values so
        you see what's what, control characters are made printable, etc.).
        Make sure you don't put the type specifier (like $ ) there, just the
        symbol names, like this:

         $debugger->get_v_vars(regex);

    get_x_vars
        X [vars] Same as V currentpackage [vars]

         $debugger->get_x_vars(regex);

    get_h_var
        Enter h or `h h' for help, For more help, type h cmd_letter,
        optional var

         $debugger->get_h_var();

    set_option
        o booloption ...

        Set each listed Boolean option to the value 1 . o anyoption? ...

        Print out the value of one or more options. o option=value ...

        Set the value of one or more options. If the value has internal
        white-space, it should be quoted. For example, you could set o
        pager="less -MQeicsNfr" to call less with those specific options.
        You may use either single or double quotes, but if you do, you must
        escape any embedded instances of same sort of quote you began with,
        as well as any escaping any escapes that immediately precede that
        quote but which are not meant to escape the quote itself. In other
        words, you follow single-quoting rules irrespective of the quote;
        eg: o option='this isn\'t bad' or o option="She said, \"Isn't it?\""
        .

        For historical reasons, the =value is optional, but defaults to 1
        only where it is safe to do so--that is, mostly for Boolean options.
        It is always better to assign a specific value using = . The option
        can be abbreviated, but for clarity probably should not be. Several
        options can be set together. See Configurable Options for a list of
        these.

         $debugger->set_option();

    get_options
        o

        Display all options.

         $debugger->get_options();

    get Actually I think this is an internal method....

        In SCALAR context will return all the buffer collected since the
        last command.

        In LIST context will return ($prompt, $module, $file, $row,
        $content) Where $prompt is the what the standard debugger uses for
        prompt. Probably not too interesting. $file and $row describe the
        location of the next instructions. $content is the actual line -
        this is probably not too interesting as it is in the editor. $module
        is just the name of the module in which the current execution is.

    filename
         $debugger->filename();

    row
         $debugger->row();

    module
         $debugger->module();

  Internal Methods
    *   _get

    *   _logger

    *   _process_line

    *   _prompt

    *   _send

    *   _send_get

BUGS AND LIMITATIONS
    Warning if you use List request you may get spurious results.

    When using against perl5db.pl v1.35 list mode gives an undef response,
    also leading single quote now correct. Tests are skipped for list mode
    against v1.35 now.

    Debug::Client 0.12 tests are failing, due to changes in perl debugger,
    when using perl5db.pl v1.34

    Debug::Client 0.13_01 skips added to failing tests.

     c [line|sub]

    Continue, optionally inserting a one-time-only breakpoint at the
    specified line or subroutine.

     c is now ignoring options [line|sub]

    and just performing c on it's own

    *Warning sub listen has bean deprecated*

    Has bean deprecated since 0.13_04 and all future versions starting with
    v0.14

    Perl::Critic Error Subroutine name is a homonym for built-in function

    Use $debugger->listener instead

AUTHORS
    Kevin Dawson <bowtie@cpan.org>

    Gabor Szabo <gabor@szabgab.com>

CONTRIBUTORS
    Breno G. de Oliveira <garu at cpan.org>

    Ahmad M. Zawawi <ahmad.zawawi@gmail.com>

    Mark Gardner <mjgardner@cpan.org>

    Wolfram Humann <whumann@cpan.org>

COPYRIGHT
    Copyright 2008-2012 Gabor Szabo/Kevin Dawson

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

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

CREDITS and THANKS
    Originally started out from the remote-port.pl script from Pro Perl
    Debugging written by Richard Foley.

See Also
    GRID::Machine::remotedebugtut

    Devel::ebug

    Devel::Trepan