Mark E. Shoulson > Filter-Unpound-1.1 > Filter::Unpound

Download:
Filter-Unpound-1.1.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1.1   Source  

NAME ^

Unpound - Simple "uncomment" debugging.

SYNOPSIS ^

    # Some code executing...
    #trace# print "Entered subroutine.\n";
    $foo=&bar();
    #debug# print "\$foo: $foo\n";
    $rv=$foo/17;    #debug# print "Inline comment: \$rv is $rv\n";
    #debug#trace# print "About to return $rv\n";

DESCRIPTION ^

An even more simplified source filter, based on Filter::Simple and somewhat like Filter::Uncomment, but with a different syntax that might be easier to work with.

Anything commented out by a comment in the form #word# can be uncommented by including this package with suitable arguments. Essentially, if you execute

    perl -MFilter::Unpound=word script.pl

then the string "#word#" is removed wherever it may appear in the code--which may then expose some previously commented-out instructions. This may make a huge difference in performance (in a tight loop) versus calling a debug function that checks if a debug variable is set. You can have several different "uncomment" tags and use them selectively. A line tagged with more than one, as above, is activated if any one is activated (any block of keywords containing #word# is removed, not just the single one). You can make it have to have all the tags this way:

   #foo#bar# print "This line prints with either foo or bar.\n";
   #foo# #bar# print "This line prints only with both.\n";

You would have to say perl -MFilter::Unpound=foo,bar to get the second line to print, whereas either perl -MFilter::Unpound=foo or perl -MFilter::Unpound=bar will suffice for the first.

Note that the #word# must be followed by whitespace, before the code that is being uncommented.

You can also uncomment multi-line pieces of code which are ordinarily commented out by wrapping them in a special "string comment" using Perl here-strings.

    ;<<'foo'
    print "This code is normally ignored, just shoved into a string.\n";
    foo
    ;

    ;my $bar=<<'BAR'
    print "Also ignored code.\n";
    print "The dummy variable is for avoiding warnings\n";
    BAR
    ;

    ;$bar=<<'BAR'
    print "Same as above... ";
    print "(except didn't declare \$bar again.)\n";
    BAR
    ;

The string comment header must appear just as shown: on its own line, with the keyword surrounded by single quotes, and the << must be preceded by a semicolon (just in case you have some code that uses a here-string that starts on its own line; the semicolon makes the string unusable for anything, so it can't be purposeful in your code. You shouldn't be using your Unpound keywords as ordinary delimiters anyway, though.) Note that this will cause "void" warnings (during ordinary, not Unpounded, execution) if you have those enabled. You can optionally assign to a variable if you want to avoid the warnings (in which case, of course, make sure that you don't use a variable with that name anywhere that could cause interference). You can also optionally declare the variable with "my" on the line as shown above. When "foo" is selected, Unpound will delete lines that look like ";<<'foo'" (optionally assigned to a variable) and lines that have only "foo" on them, so this code will be uncommented (so don't use the keywords as delimiters for anything important in the code, of course.)

One or the Other

You can even use this to set up code to be commented, so you can have code that acts one way when debugging is off and does something else (not just more things) when debugging is on. Consider:

    #debug# print "Doing debugging things.\n";
    
    #debug# ;<<'XxXxXx';
    print "Doing normal things, which will NOT be done when debugging.\n";
    #debug# XxXxXx
    #debug# ;

The "normal" code is eaten into the dummy string when debug is selected. Make sure there is no whitespace after your string terminator (Unpound will eat the whitespace before it)

Print Shorthand

Since most of the time debugging statements are print statements, you can save the hassle of typing "print" (or even "say") all the time by ending your single-line tag with '>' (the # before the > is optional). The rest of the line (after whitespace) will be taken as a double-quoted string to be printed, followed by a newline. The line is quoted as a here-string, so there shouldn't be any problems with accidental end-quoting.

This feature is not available for multi-line uncomments.

LIMITATIONS ^

BUGS ^

The keywords and CmtRE methods, which return the list of keywords and the regex constructed to detect them, respectively, only return those values set by the last importation of Unpound. If there were other keywords set either by multiple use statements in this module or by modules higher up on the "inclusion chain" using some kind of inheritance scheme, they will not be listed.

DIAGNOSTICS ^

None intended to come from Unpound itself.

SEE ALSO ^

Filter::Uncomment, Smart::Comments, Devel::Comments, Filter::cpp.

AUTHOR ^

Mark E. Shoulson <mark@shoulson.com>

COPYRIGHT AND LICENSE ^

Copyright (c) 2012, Mark Shoulson. All Rights Reserved. This module is free software. It may be used, redistributed, and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)

syntax highlighting: