1Devel::Comments(3) User Contributed Perl Documentation Devel::Comments(3)
2
6 Devel::Comments - Debug with executable smart comments to logs
7
9 This document describes Devel::Comments version 1.1.4
10
12 use Devel::Comments; # acts just like Smart::Comments
13 # Dumps...
15 my $scalar = 42;
16 ### $scalar # prints to STDERR:
17 ### $my_scalar: 42
18 ### @array # dumps more complex
20 ### $HoHoA # data structures, too
21 ### Just in the neighborhood # prints literal message
23 # Level control...
25 use Devel::Comments '###'; # only activate level 3
26 ### $scalar # this prints
28 #### $scalar # this doesn't
29 # Output control...
31 use Devel::Comments *STDOUT; # prints to STDOUT instead
32 use Devel::Comments \*FH; # prints to some FH
33 use Devel::Comments $fh; # prints to some $fh
34 use Devel::Comments ({ # hashref calling syntax
36 -file => 'my.log', # opens my.log and prints to it
37 });
38 # Assertions...
40 my ($x, $y) = 1, 0;
41 ### check $x == $y # simulates warning and dumps info
42 ### insist $x == $y # dumps and dies
43 # Progress bars...
45 for my $i (0..1e6) { ### Working===[%] done
46 do_something_expensive_with($i);
47 }
48
50 I get the feeling that the computer just skips over all the comments.
51 -- a grad student
52 Devel::Comments is a source filter for your Perl code, intended to be
54 used only during development. Specially-formatted 'smart' comments are
55 replaced by executable code to dump variables to screen or to file,
56 display loop progress bars, or enforce conditions. These smart comments
57 can all be disabled at once by commenting out the "use Devel::Comments"
58 line, whereupon they return to being simple, dumb comments. Your
59 debugging code can remain in place, guaranteed harmless, ready for the
60 next development cycle.
61 Devel::Comments is a fork of Smart::Comments; current intention is to
63 add new features without breaking backward compatibility. Version
64 1.1.2 implements the 'any filehandle' feature, allowing smart output to
65 go to any filehandle opened for writing. You may instead pass in a
66 filename, which DC will open for you. Future plans include extended
67 calling syntax, numerical level enabling, improved progress bars, dump
68 method callback, and execution of arbitrary code. Bugs raised against
69 Smart::Comments 1.0.4 will be fixed in DC.
70
72 There are two main parts to the DC interface: arguments passed on the
73 "use" line; and 'smart' comments, which are specially-formatted
74 comments introduced by three or more octothorpes, such as '###',
75 '####', or even '########'. Use-line arguments may also be passed in
76 an environment variable.
77 DC provides no run-time public variables, functions, routines, or
79 methods. DC is a source filter and does its work at "compile-time".
80 (Some DC routines are called at run-time from within replacement code
81 previously filtered in.)
82 The Use Line
84 Most setup is done when the module is loaded via "use Devel::Comments".
85 If called with vanilla Smart::Comments arguments, DC will behave the
86 same; it's a drop-in replacement. Backwards compatibility to
87 Smart::Comments 1.0.4 is promised through DC 1.x.x.
88 Smart::Comments required arguments to be passed, in any order, as one
90 flat list. While this is convenient for a small number of restricted-
91 value arguments, it may "getcha" when attempted with many arguments
92 whose values are unrestricted. This "free-form" calling syntax does not
93 even have the security of positional parameters.
94 While every attempt will be made to interpret a flat list correctly, we
96 will make a transition to named parameters as elements of a hash
97 reference. Devel::Comments users are encouraged to use this newer
98 calling syntax.
99 Following sections are headed by the appropriate hashref key, which
101 begins always with a leading dash. NOTE: This early version 1.1.2 does
102 not yet implement hashref calling syntax for parameters other than
103 "-filename". Other sections are headed by the hashref keys that will
104 name their parameters. If the named parameter is unimplemented, you can
105 still pass the argument in the flat list.
106 -fh
108 named parameter syntax unimplemented
110 Example arguments: *STDOUT, "\*FH", $fh
112 Accepts an open, writable filehandle (typeglob or object) as an
114 argument. Caller must do whatever is needed to manage that filehandle,
115 such as opening (but probably not closing) it.
116 Value must be acceptable as a filehandle:
118 $fh # indirect filehandle (perhaps IO::File object); recommended.
120 \*FH # reference to a typeglob
121 *FH # typeglob
122 "FH" # please don't do this; probably won't work as expected.
123 Except for *STDOUT you should probably avoid the typeglob notation.
125 (No need to specify *STDERR explicitly; it's the default.) DC will try
126 to work with a typeglob but there are risks. You'd better localize the
127 typeglob; a lexical may not work. (See "Perl Cookbook Recipie 7.16".)
128 Passing a string will probably fail.
129 See also "perldoc perlopentut".
131 Note that, effectively, modules are used within a BEGIN block.
133 Therefore, your filehandle must be opened within a BEGIN block prior to
134 the use line. If caller needs to do anything else with that filehandle,
135 you might as well store it in a package variable (since source
136 filtering is global anyway). Do not enclose the open and the use line
137 in the same BEGIN block.
138 The filehandle must be opened, obviously, in some writable mode.
140 BEGIN { # get $::fh open early enough
142 my $filename = 'my.log';
143 open my $::fh, '>', $filename
144 or die "Couldn't open $filename to write", $!;
145 }
146 use Devel::Comments $::fh;
147 {...} # do some work
148 ### $some_variable
149 print {$::fh} 'Some message...'; # do something else with $::fh
150 -file
152 flat list parameter syntax unimplemented
154 Example arguments: '/var/my.log', "$0.log", 'ziggy.txt'
156 Value can be any filename or path, relative or fully qualified. The
158 file will be created if it doesn't exist, truncated by default, opened
159 for writing, and set to autoflush. All directory components must exist.
160 Until your entire program ends, there's no way to be sure that caller
162 won't come into scope (say, a sub called from some other script or
163 module). So DC can't do an explicit "close()". That shouldn't be a
164 problem, since perl will close the filehandle when program terminates.
165 If you need to do something differently, supply a filehandle and manage
166 it yourself.
167 You may, in an upcoming version, pass a filename as a flat list
169 argument. There's an issue here in that a filename might be just about
170 any string; if you've chosen a peculiar filename such as '###' or
171 '-ENV', there's going to be confusion. For now, this is unimplemented.
172 -level
174 named parameter syntax unimplemented
176 numerical levels unimplemented
178 Devel::Comments accepts arguments like '###', '####', and so forth. If
180 none are given, then all comments introduced with 3 or more octothorpes
181 are considered smart. Otherwise, only those comments introduced with a
182 matching quantity are smart:
183 use Devel::Comments '###', '#####';
185 ### This is smart.
186 #### This is dumb.
187 ##### This is also smart.
188 Soon, you will be able to pass an integer or a list of integers:
190 use Devel::Comments ({-level => [3, 5] });
192 ### This is smart.
193 #### This is dumb.
194 ##### This is also smart.
195 But not quite yet.
197 A level of 1 or 2 simply doesn't work. So don't do that.
199 -env
201 named parameter syntax unimplemented
203 Example: "use Devel::Comments -ENV;"
205 Yet another way of specifying arguments (besides as a list or hashref
207 in the use line) is to pass them in the environment variable
208 $ENV{Devel_Comments}. But to enable this, you must pass "-ENV" in the
209 use line or define "-env" in a hashref passed in the use line.
210 See "CONFIGURATION AND ENVIRONMENT".
212 Don't try to pass a hashref inside of the environment variable; you
214 won't like the result.
215 Smart Comments Format
217 In some small way, smart comments comprise an alternate language
218 embedded within Perl. If you don't have any smart comments in your
219 code, Devel::Comments, like Smart::Comments before it, will do
220 essentially nothing. If you disable Devel::Comments (see "DISABLING"),
221 then smart comments are guaranteed to do nothing at all, since they are
222 then interpreted by perl as plain old dumb comments.
223 All smart comments, without exception, are introduced by a series of
225 three or more octothorpes: '###' at a minimum. This is not likely to
226 change; the '##' sequence is used by Perl::Tidy to signal the end of
227 lengthy constructs.
228 Aspects of this miniature language-within-a-language now include
230 introducers, messages, dumps, assertions, and progress bars. Extensions
231 are planned.
232 Introducers
234 A basic smart comment is any line beginning with '###':
236 ### This comment is smart at debug level 3.
238 This is considered a level 3 comment; it will only be active if level 3
240 is enabled by one means or another. More octothorpes increase the debug
241 level:
242 ##### This comment is smart at debug level 5.
244 The number of debugging levels is essentially unlimited; so introducers
246 may be of any length. However, this rapidly becomes unwieldy.
247 unimplemented: An alternate means of specifying the debug level is:
249 ###4 This comment is smart at debug level 4.
251 Every introducer ends with a space or tab ("m/[ \t]/"); anything before
253 the first white character is considered part of the introducer.
254 unimplemented: An introducer ending in an ampersand ("&") marks raw
256 Perl code; in effect, the introducer is simply stripped off if it is at
257 an enabled debug level:
258 ###& push @zoo, $monkey # Put the monkey in the zoo at debug level 3.
260 Note that, with the exception of progress bars, a smart comment must
262 begin its line; that is, only whitespace can intervene between an
263 introducer and the preceeding newline. Trailing smart comments may be a
264 future feature.
265 Messages
267 Any smart comment not matching other patterns will be dumped as is:
269 ### Hello, World!
271 In a message, "<now>", "<time>", or "<when>" is replaced by a timestamp
273 (same timestamp for all three). Also, "<here>", "<place>", or
274 "<where>" is replaced by what Damian Conway calls a "spacestamp"
275 similar to what you see by default in "die()" or "warn()":
276 ### Here <here>
278 ### Now <now>
279 prints something like:
281 ### Here "util/demo.pl", line 71
283 ### Now Fri Aug 6 07:50:51 2010
284 Note that no colon follows 'Here' or 'Now'. Any text would do as well
286 but no text at all -- the "<now>" alone -- gets confused. This is
287 considered a bug.
288 ### <here> <now>
290 ... works fine and is an excellent way to start off a logging session.
292 Original SC documentation required that such plain text messages be
294 terminated with a simulated elipsis:
295 ### This text is printed...
297 This was not actually enforced and is not required in DC.
299 Dumps
301 Any scalar, array, hash; reference to any of these, or for that matter,
303 more complex structure can be dumped just by typing the variable:
304 ### $dump_me
306 The dump will be labeled with the variable name, including sigil. You
308 can supply your own label if you like:
309 ### Working tree: $tree
311 The automatic labeling is the real driving force behind DC, though.
313 Even dark magiks involving Pad::Walker and rooting around in symbol
314 tables has trouble getting the right name for a variable and its value.
315 The only place it is convenient to do this is in the same scope as the
316 variable itself; hence, a source filter.
317 You can dump an arbitrary expression:
319 my $index = 8;
321 ### Add five: $index + 5
322 prints:
324 ### Add five: 13
326 However, this will not work if you don't supply your own label.
328 Beware side effects:
330 my @array = ( 1, 2, 3 );
332 say @array;
333 ### Pop: pop @array
334 say @array;
335 prints:
337 123
339 ### Pop: 3
341 12
342 If you don't want the verbosity of "<here>", try:
344 #### At: __LINE__
346 Assertions
348 Seven keywords cannot be used as labels. If one of them is used to
350 label an expression, it is evaluated in boolean context and, if the
351 expression is true, nothing is output. If the expression is false, a
352 message announcing the failure is output, similar to "warn()":
353 ### check: 1 == 0
355 prints something like:
357 ### 1 == 0 was not true at util/demo.pl line 92.
359 The assertions:
361 ### check: BOOL
363 ### confirm: BOOL
364 ### verify: BOOL
365 ... simulate "warn()" on failure, although the smart output goes to the
367 chosen output file or filehandle, not necessarily STDERR.
368 ### assert: BOOL
370 ### ensure: BOOL
371 ### insist: BOOL
372 ### require: BOOL
373 ... print the same message on failure, then call "die()".
375 Note that these seven keywords are supported in the current version of
377 DC but all except "check" and "assert" are deprecated.
378 Progress Bars
380 Only in these can a smart comment appear on the same line with Perl
382 code:
383 for (@candidates) { ### Evaluating |===[%] |
385 prints, in succession:
387 Evaluating |[0%] |
389 Evaluating |=[25%] |
390 Evaluating |========[50%] |
391 Evaluating |===============[75%] |
392 Evaluating |===========================|
393 At each step, the previous bar is erased and overwritten by the next;
395 when the loop completes, the last bar is erased, too.
396 There are a great number of possible progress bar formats and they are
398 very clever indeed. There is, however, among developers polled, almost
399 no interest in them; and they are difficult to support. It's not clear
400 that they're truly useful in debugging. So, although they are supported
401 in the current DC release, they likely will be deprecated or replaced
402 by a different loop reporting function.
403 Both Vanilla and DC animate the progress bar by printing the "\r"
405 character and wiping the line with spaces. This is unchanged when smart
406 output goes to a disk file. Depending on your method of reading that
407 file, you may see multiple lines or nothing at all. But if, for some
408 reason, the loop aborts, you may see how far along it got.
409 If you want to experiment with progress bars, you may want to look at
411 the Smart::Comments documentation. If you like them, please be sure to
412 indicate your support.
413
415 Source filters are a bit dicey; the saving grace of DC (and its parent)
416 is that it can be disabled easily and completely; all specially-
417 formatted smart comments return to being plain old dumb comments,
418 guaranteed not to interfere with normal execution:
419 #use Devel::Comments; # disable in production
421 ### assert 0 == 1 # does nothing at all
422 There are other methods of disabling DC.
424 If you write:
426 use Devel::Comments -ENV; # heed environment variable
428 ... then DC will only be active if $ENV{Devel_Comments} is set,
430 possibly to some other DC use-line arguments or mererly to 1. If it is
431 set to 0 or deleted, then DC is disabled.
432 DC can be restricted to a certain span of code. If you write:
434 ### Hello, Andy!
436 use Devel::Comments;
437 ### Hello, Bob!
438 no Devel::Comments;
439 ### Hello, Cindy!
440 then Bob will be greeted but not Andy or Cindy. Note that docs for
442 Filter::Simple suggest other possible text for the statement that
443 terminates filtering; these others don't seem to work, so don't do
444 that.
445 You might load DC in the shell invocation:
447 $ perl -d:Comments myscript.pl
449 Next time, don't do that and DC won't load, of course. This loading
451 method is untested but if there are requests for it, I'll work it up.
452 Any given smart comment can be disabled by changing the introducer to a
454 level that's disabled in the use line, or to an invalid introducer:
455 use Devel::Comments '###';
457 ### grin
458 #### and
459 # ### bear
460 # ## it
461 prints:
463 ### grin
465
467 Technically, arguments present on any "use" line are presented to a
468 module's "import()" method. Devel::Comments uses Filter::Simple to do
469 the heavy lifting; FS converts a call to Filter::Simple::FILTER into
470 Devel::Comments::import().
471 All of the following code, to end of file or any "no Devel::Comments"
473 line, is filtered. All smart comments (with correct introducers) are
474 replaced by executable Perl code.
475 If you write something funky, like:
477 my $string = q{
479 bobby says
480 ### think
481 };
482 ... then you are asking for trouble and will likely get it.
484 my $string = q{\n bobby says\n ### think\n};
486 ... is perfectly safe and will be ignored by DC.
488 Dumps of complex structures are done by the venerable Data::Dumper.
490 The output is cleaned up a bit before being printed; the all-important
491 variable identifier is inserted.
492 Scope, State, Output Regimes
494 DC may be called more than once in the same program, e.g., from two
495 different loaded modules. As does vanilla SC, DC has effect until the
496 end of the file or a "no Devel::Comments" line (which must be the first
497 thing on its line). If used again, DC will parse the new use line and
498 apply it to your source code from there on out.
499 This required no special logic in Vanilla; the filter is applied once
501 per use and although multiple modules might call S::C routines from
502 within filtered code, all output went to STDERR. But multiple uses of
503 DC may choose different output regimes. So state information is stored
504 for each caller.
505 If you supply a filehandle (other than STDOUT or STDERR), your
507 (filtered) code will need that later to print smart output where you
508 want it to go. If you supply a package variable as an indirect
509 filehandle (such as $My::Module::fh), then all is well. If you supply a
510 lexical ("my") variable, DC will still work, even after it goes out of
511 scope in your package, because a reference is stored in DC's namespace.
512 But by the same token, don't expect it to be garbage-collected. You may
513 as well use a package "global" variable, since source filtering is
514 pretty much a global operation anyway.
515 If you pass a filename but no filehandle, you'll get smart output but
517 you won't have any way to write directly to the file (should you take
518 that notion). Not recommended to open the file again within your
519 script, although that might work.
520
522 Internal error: _get_outfh called with no or false arg. $!
523 Internal error: $caller_id not defined in %state_of. $!
524 Internal error: No output filehandle found in %state_of for $caller_id. $!
525 Internal error: -caller_id not passed in call to _init_state(). $!
526 Internal error: -outfh not passed in call to _init_state(). $!
527 You should never see any of these errors involving state maintenance.
529 If you do, please contact the author with as much information as
530 possible.
531 Can't open $out_filename to write.
533 You passed in a filename that couldn't be written to. Check to see that
535 all directory components of the path exist and that you have permission
536 to write to the target file.
537 Filesystem IO error: Failed to print to output filehandle for $caller_id
539 Gee, that's funny. But if DC can't write to a filehandle you supplied,
541 it's probably not something I can do anything about. Perhaps the disk
542 is full or the socket is closed? Be sure you have opened the
543 filehandle for writing in a BEGIN block prior to the "use
544 Devel::Comments;" line. Check to see you can write to it.
545 Internal error: DATA. $!
547 You should never see this error either. If you do, please contact the
549 author with as much information as possible.
550 ### $assertion was not true
552 This is not a module error but smart output you generated. See
554 "ASSERTIONS"
555
557 Devel::Comments can make use of an environment variable from your
558 shell: "Devel_Comments". This variable can be specified either with a
559 true/false value (i.e. 1 or 0) or with the same arguments as may be
560 passed on the "use" line when loading the module (see "INTERFACE").
561 The following table summarizes the behaviour:
562 Value of
564 $ENV{Devel_Comments} Equivalent Perl
565 1 use Devel::Comments;
567 0 no Devel::Comments;
568 '###:####' use Devel::Comments qw(### ####);
569 '### ####' use Devel::Comments qw(### ####);
570 To enable the "Devel_Comments" environment variable, you need to load
572 the module with the "-ENV" flag:
573 use Devel::Comments -ENV;
575 Note that you can still specify other arguments in the "use" statement:
577 use Devel::Comments -ENV, qw(### #####);
579 In this case, the contents of the environment variable replace the
581 "-ENV" in the argument list.
582
584 The module requires the following modules:
585 • Filter::Simple
587 • version.pm
589 • List::Util
591 • Data::Dumper
593 • Text::Balanced
595
597 It is known that IO::Capture::Tie_STDx 0.05 does not implement a
598 "TELL()" method. This causes trouble if smart output is directed to a
599 captured filehandle. Workaround is to install IO::Capture::Tellfix,
600 included with this distribution.
601 Not recommended to use DC is combination with other source filters.
603
605 Tellfix is ugly and causes a warning to be raised under some
606 circumstances. Intent is to move off IO::Capture::* altogether in
607 favor of Test::Trap; so this issue will not be fixed directly.
608 The current testing paradigm is flawed; it has too many dependencies,
610 including perl 5.010. We ship with a cut-down "user" test suite, which
611 should run fine under perl 5.008; this is mostly a rehash of the
612 original Smart::Comments test suite and doesn't fully exercise DC's new
613 features. Those interested may want to run the full test suite found
614 in t/all/.
615 A number of features are marked as unimplemented.
617 Bugs outstanding against SC 1.0.4 can be found at
619 <https://rt.cpan.org/Dist/Display.html?Queue=Smart-Comments> and they
620 are probably all present in this version of DC. You are welcome to
621 relist against DC any that you find; but I will be working off that
622 list, too.
623 Please report any bugs or feature requests to
625 <https://rt.cpan.org/Public/Bug/Report.html?Queue=Devel-Comments> or
626 email "<XIONG@cpan.org>". These are welcome and will be acted upon.
627
629 Argment passing will be made orthogonal, as much as possible. Arguments
630 can be passed either as one flat list or as named elements of a single
631 hashref.
632 Debug levels passed numerically and numerical introducers.
634 Invocation of client methods for dumping objects.
636 Pass-through execution of arbitrary debugging code.
638 Police up scraps of stuff currently left in caller's namespace. Store
640 all state entirely within DC.
641
643 • Mike Stok "<MIKESTOK@cpan.org>" for reporting RT#62599 and fixing
644 it.
645 • Kevin Ryde for reporting RT#69712 and reviving the project.
647
649 Xiong Changnian "<XIONG@cpan.org>"
650
652 Copyright (c) 2010, 2011, Xiong Changnian "<XIONG@cpan.org>". All
653 rights reserved.
654 Based almost entirely on Smart::Comments, Copyright (c) 2005, Damian
656 Conway "<DCONWAY@cpan.org>". All rights reserved.
657 This module is free software; you can redistribute it and/or modify it
659 under the same terms as Perl itself.
660
662 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
663 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
664 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
665 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
666 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
667 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
668 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
669 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
670 NECESSARY SERVICING, REPAIR, OR CORRECTION.
671 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
673 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
674 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
675 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
676 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
677 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
678 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
679 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
680 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
681 DAMAGES.
682perl v5.34.0 2021-07-22 Devel::Comments(3)