1Smart::Comments(3) User Contributed Perl Documentation Smart::Comments(3)
2
6 Smart::Comments - Comments that do more than just sit there
7
9 This document describes Smart::Comments version 1.0.4
10
12 use Smart::Comments;
13 my $var = suspect_value();
15 ### $var
17 ### got: $var
19 ### Now computing value...
21 # and when looping:
23 for my $big_num (@big_nums) { ### Factoring... done
25 factor($big_num);
26 }
27 while ($error > $tolerance) { ### Refining---> done
29 refine_approximation()
30 }
31 for (my $i=0; $i<$MAX_INT; $i++) { ### Working===[%] done
33 do_something_expensive_with($i);
34 }
35
37 Smart comments provide an easy way to insert debugging and tracking
38 code into a program. They can report the value of a variable, track the
39 progress of a loop, and verify that particular assertions are true.
40 Best of all, when you're finished debugging, you don't have to remove
42 them. Simply commenting out the "use Smart::Comments" line turns them
43 back into regular comments. Leaving smart comments in your code is
44 smart because if you needed them once, you'll almost certainly need
45 them again later.
46
48 All smart comments start with three (or more) "#" characters. That is,
49 they are regular "#"-introduced comments whose first two (or more)
50 characters are also "#"'s.
51 Using the Module
53 The module is loaded like any other:
54 use Smart::Comments;
56 When loaded it filters the remaining code up to the next:
58 no Smart::Comments;
60 directive, replacing any smart comments with smart code that implements
62 the comments behaviour.
63 If you're debugging an application you can also invoke it with the
65 module from the command-line:
66 perl -MSmart::Comments $application.pl
68 Of course, this only enables smart comments in the application file
70 itself, not in any modules that the application loads.
71 You can also specify particular levels of smartness, by including one
73 or more markers as arguments to the "use":
74 use Smart::Comments '###', '####';
76 These arguments tell the module to filter only those comments that
78 start with the same number of "#"'s. So the above "use" statement would
79 "activate" any smart comments of the form:
80 ### Smart...
82 #### Smarter...
84 but not those of the form:
86 ##### Smartest...
88 This facility is useful for differentiating progress bars (see
90 "Progress Bars"), which should always be active, from debugging
91 comments (see "Debugging via Comments"), which should not:
92 #### Debugging here...
94 for (@values) { ### Progress: 0... 100
96 do_stuff();
97 }
98 Note that, for simplicity, all smart comments described below will be
100 written with three "#"'s; in all such cases, any number of "#"'s
101 greater than three could be used instead.
102 Debugging via Comments
104 The simplest way to use smart comments is for debugging. The module
105 supports the following forms, all of which print to "STDERR":
106 "### LABEL : EXPRESSION"
108 The LABEL is any sequence of characters up to the first colon. The
109 EXPRESSION is any valid Perl expression, including a simple
110 variable. When active, the comment prints the label, followed by
111 the value of the expression. For example:
112 ### Expected: 2 * $prediction
114 ### Got: $result
115 prints:
117 ### Expected: 42
119 ### Got: 13
120 "### EXPRESSION"
122 The EXPRESSION is any valid Perl expression, including a simple
123 variable. When active, the comment prints the expression, followed
124 by the value of the expression. For example:
125 ### 2 * $prediction
127 ### $result
128 prints:
130 ### 2 * $prediction: 42
132 ### $result: 13
133 "### TEXT..."
135 The TEXT is any sequence of characters that end in three dots.
136 When active, the comment just prints the text, including the dots.
137 For example:
138 ### Acquiring data...
140 $data = get_data();
142 ### Verifying data...
144 verify_data($data);
146 ### Assimilating data...
148 assimilate_data($data);
150 ### Tired now, having a little lie down...
152 sleep 900;
154 would print:
156 ### Acquiring data...
158 ### Verifying data...
160 ### Assimilating data...
162 ### Tired now, having a little lie down...
164 as each phase commenced. This is particularly useful for tracking
166 down precisely where a bug is occurring. It is also useful in non-
167 debugging situations, especially when batch processing, as a simple
168 progress feedback mechanism.
169 Within a textual smart comment you can use the special sequence
171 "<now>" (or "<time>" or "<when>") which is replaced with a
172 timestamp. For example:
173 ### [<now>] Acquiring data...
175 would produce something like:
177 ### [Fri Nov 18 15:11:15 EST 2005] Acquiring data...
179 There are also "spacestamps": "<here>" (or "<line>" or "<loc>" or
181 "<place>" or "<where>"):
182 ### Acquiring data at <loc>...
184 to produce something like:
186 ### Acquiring data at "demo.pl", line 7...
188 You can, of course, use both in the same comment as well.
190 Checks and Assertions via Comments
192 "### require: BOOLEAN_EXPR"
193 "### assert: BOOLEAN_EXPR"
194 "### ensure: BOOLEAN_EXPR"
195 "### insist: BOOLEAN_EXPR"
196 These four are synonyms for the same behaviour. The comment
197 evaluates the expression in a boolean context. If the result is
198 true, nothing more is done. If the result is false, the comment
199 throws an exception listing the expression, the fact that it
200 failed, and the values of any variables used in the expression.
201 For example, given the following assertion:
203 ### require: $min < $result && $result < $max
205 if the expression evaluated false, the comment would die with the
207 following message:
208 ### $min < $result && $result < $max was not true at demo.pl line 86.
210 ### $min was: 7
211 ### $result was: 1000004
212 ### $max was: 99
213 "### check: BOOLEAN_EXPR"
215 "### confirm: BOOLEAN_EXPR"
216 "### verify: BOOLEAN_EXPR"
217 These three are synonyms for the same behaviour. The comment
218 evaluates the expression in a boolean context. If the result is
219 true, nothing more is done. If the result is false, the comment
220 prints a warning message listing the expression, the fact that it
221 failed, and the values of any variables used in the expression.
222 The effect is identical to that of the four assertions listed
224 earlier, except that "warn" is used instead of "die".
225 Progress Bars
227 You can put a smart comment on the same line as any of the following
228 types of Perl loop:
229 foreach my VAR ( LIST ) { ### Progressing... done
231 for my VAR ( LIST ) { ### Progressing... done
233 foreach ( LIST ) { ### Progressing... done
235 for ( LIST ) { ### Progressing... done
237 while (CONDITION) { ### Progressing... done
239 until (CONDITION) { ### Progressing... done
241 for (INIT; CONDITION; INCR) { ### Progressing... done
243 In each case, the module animates the comment, causing the dots to
245 extend from the left text, reaching the right text on the last
246 iteration. For "open ended" loops (like "while" and C-style "for"
247 loops), the dots will never reach the right text and their progress
248 slows down as the number of iterations increases.
249 For example, a smart comment like:
251 for (@candidates) { ### Evaluating... done
253 would be animated is the following sequence (which would appear
255 sequentially on a single line, rather than on consecutive lines):
256 Evaluating done
258 Evaluating...... done
260 Evaluating............. done
262 Evaluating................... done
264 Evaluating..........................done
266 The module animates the first sequence of three identical characters in
268 the comment, provided those characters are followed by a gap of at
269 least two whitespace characters. So you can specify different types of
270 progress bars. For example:
271 for (@candidates) { ### Evaluating::: done
273 or:
275 for (@candidates) { ### Evaluating=== done
277 or:
279 for (@candidates) { ### Evaluating||| done
281 If the characters to be animated are immediately followed by other non-
283 whitespace characters before the gap, then those other non-whitespace
284 characters are used as an "arrow head" or "leader" and are pushed right
285 by the growing progress bar. For example:
286 for (@candidates) { ### Evaluating===| done
288 would animate like so:
290 Evaluating| done
292 Evaluating=====| done
294 Evaluating============| done
296 Evaluating==================| done
298 Evaluating==========================done
300 If a percentage character ("%") appears anywhere in the comment, it is
302 replaced by the percentage completion. For example:
303 for (@candidates) { ### Evaluating [===| ] % done
305 animates like so:
307 Evaluating [| ] 0% done
309 Evaluating [===| ] 25% done
311 Evaluating [========| ] 50% done
313 Evaluating [============| ] 75% done
315 Evaluating [=================] 100% done
317 If the "%" is in the "arrow head" it moves with the progress bar. For
319 example:
320 for (@candidates) { ### Evaluating |===[%] |
322 would be aninated like so:
324 Evaluating |[0%] |
326 Evaluating |=[25%] |
328 Evaluating |========[50%] |
330 Evaluating |===============[75%] |
332 Evaluating |===========================|
334 For "open-ended" loops, the percentage completion is unknown, so the
336 module replaces each "%" with the current iteration count. For example:
337 while ($next ne $target) { ### Evaluating |===[%] |
339 would animate like so:
341 Evaluating |[0] |
343 Evaluating |=[2] |
345 Evaluating |==[3] |
347 Evaluating |===[5] |
349 Evaluating |====[7] |
351 Evaluating |=====[8] |
353 Evaluating |======[11] |
355 Note that the non-sequential numbering in the above example is a result
357 of the "hurry up and slow down" algorithm that prevents open-ended
358 loops from ever reaching the right-hand side.
359 As a special case, if the progress bar is drawn as two pairs of
361 identical brackets:
362 for (@candidates) { ### Evaluating: [][]
364 for (@candidates) { ### Evaluating: {}{}
366 for (@candidates) { ### Evaluating: ()()
368 for (@candidates) { ### Evaluating: <><>
370 Then the bar grows by repeating bracket pairs:
372 Evaluating: [
374 Evaluating: []
376 Evaluating: [][
378 Evaluating: [][]
380 Evaluating: [][][
382 etc.
384 Finally, progress bars don't have to have an animated component. They
386 can just report the loop's progress numerically:
387 for (@candidates) { ### Evaluating (% done)
389 which would animate (all of the same line):
391 Evaluating (0% done)
393 Evaluating (25% done)
395 Evaluating (50% done)
397 Evaluating (75% done)
399 Evaluating (100% done)
401 Time-Remaining Estimates
403 When a progress bar is used with a "for" loop, the module tracks how
404 long each iteration is taking and makes an estimate of how much time
405 will be required to complete the entire loop.
406 Normally this estimate is not shown, unless the estimate becomes large
408 enough to warrant informing the user. Specifically, the estimate will
409 be shown if, after five seconds, the time remaining exceeds ten
410 seconds. In other words, a time-remaining estimate is shown if the
411 module detects a "for" loop that is likely to take more than 15 seconds
412 in total. For example:
413 for (@seven_samurai) { ### Fighting: [||| ]
415 fight();
416 sleep 5;
417 }
418 would be animated like so:
420 Fighting: [ ]
422 Fighting: [|||| ]
424 Fighting: [||||||||| ] (about 20 seconds remaining)
426 Fighting: [|||||||||||||| ] (about 20 seconds remaining)
428 Fighting: [|||||||||||||||||| ] (about 10 seconds remaining)
430 Fighting: [||||||||||||||||||||||| ] (less than 10 seconds remaining)
432 Fighting: [|||||||||||||||||||||||||||]
434 The precision of the reported time-remaining estimate is deliberately
436 vague, mainly to prevent it being annoyingly wrong.
437
439 In a sense, everything this module does is a diagnostic. All comments
440 that print anything, print it to "STDERR".
441 However, the module itself has only one diagnostic:
443 "Incomprehensible arguments: %s in call to 'use Smart::Comments"
445 You loaded the module and passed it an argument that wasn't
446 three-or- more "#"'s. Arguments like '###', '####', '#####', etc.
447 are the only ones that the module accepts.
448
450 Smart::Comments can make use of an environment variable from your
451 shell: "Smart_Comments". This variable can be specified either with a
452 true/false value (i.e. 1 or 0) or with the same arguments as may be
453 passed on the "use" line when loading the module (see "INTERFACE").
454 The following table summarizes the behaviour:
455 Value of
457 $ENV{Smart_Comments} Equivalent Perl
458 1 use Smart::Comments;
460 0 no Smart::Comments;
461 '###:####' use Smart::Comments qw(### ####);
462 '### ####' use Smart::Comments qw(### ####);
463 To enable the "Smart_Comments" environment variable, you need to load
465 the module with the "-ENV" flag:
466 use Smart::Comments -ENV;
468 Note that you can still specify other arguments in the "use" statement:
470 use Smart::Comments -ENV, qw(### #####);
472 In this case, the contents of the environment variable replace the
474 "-ENV" in the argument list.
475
477 The module requires the following modules:
478 · Filter::Simple
480 · version.pm
482 · List::Util
484 · Data::Dumper
486 · Text::Balanced
488
490 None reported. This module is probably even relatively safe with other
491 Filter::Simple modules since it is very specific and limited in what it
492 filters.
493
495 No bugs have been reported.
496 This module has the usual limitations of source filters (i.e. it looks
498 smarter than it is).
499 Please report any bugs or feature requests to
501 "bug-smart-comments@rt.cpan.org", or through the web interface at
502 <http://rt.cpan.org>.
503
505 Damian Conway "<DCONWAY@cpan.org>"
506
508 Copyright (c) 2005, Damian Conway "<DCONWAY@cpan.org>". All rights
509 reserved.
510 This module is free software; you can redistribute it and/or modify it
512 under the same terms as Perl itself.
513
515 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
516 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
517 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
518 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
519 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
520 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
521 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
522 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
523 NECESSARY SERVICING, REPAIR, OR CORRECTION.
524 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
526 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
527 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
528 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
529 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
530 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
531 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
532 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
533 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
534 DAMAGES.
535perl v5.12.0 2009-09-04 Smart::Comments(3)