Smart::Comments

Here's a quick example of Smart::Comments. I originally planned to have a Getopt::Long flag to turn smart comments on-and-off, but that doesn't work due to the way Smart::Comments uses filters and where that happens in the compile&run cycle.

This example code still serves as a nice boilerplate for Getopt::Long and Pod::Usage.

The following script shows debugging behavior if the environment variable Smart_Comments is set to a 1.

Ex: Smart_Comments=1 ./smart-comments-example.pl
### Base Smart Comments - Show variables
### $help: 0
### $man: 0
### $DEBUG: 0

### @array: [
###           1,
###           2,
###           3,
###           4,
###           5,
###           6,
###           7,
###           8,
###           9,
###           10
###         ]

Debug output of variables is neat and worth the price of admission. "### $help" in the code turns into "### $help: help_value" during output. Arrays get dumped via Dumper. And all of this code output is on STDERR and prefixed with three hashes -- so it'll get ignored by the Test Any Protocol if it gets triggered by your unit tests.

Add to that cute progress bars that are only around when people want them? Sweet.

It sure would be nice to have an explicit flag to set/unset the smart comment level, but I don't think that's possible the way it smart comments is implemented as a filter.

Fun for personal code and scripts, but I don't think I'd use it in production, without looking a bit closer under the hood to see what (if any) affect it has when used with -ENV and with the ENV variable not set.

#!/usr/bin/perl

use strict;

use warnings;

use Getopt::Long;
use Pod::Usage;
use Smart::Comments -ENV;

my $help  = 0;
my $man   = 0;

my $DEBUG = 0;

my $result = GetOptions(
 'help|?' => \$help,
 'man'    => \$man,
 'debug'  => \$DEBUG,
);
pod2usage(1) if ( $help or !$result );
pod2usage( -exitstatus => 0, -verbose => 2 ) if $man;


my $quiet = $ENV{Smart_Comments} ? 0 : 1;

#### Base Smart Comments - Show variables
### $help
### $man
### $DEBUG
my @array = ( 1 .. 10 );
### @array

print "Now running 4 runs through the slow loop\n" if $quiet;

#### <now> Slow Array 1 at <line>...
for my $num (@array) {    ### Slow array1...       done
 ### $num
 sleep 1 if $num % 4;
}


#### <now> Slow Array 2 at <loc>...
for my $num (@array) {    ### Slow array2--->       done
 sleep 1 if $num % 4;
}


#### <now> Slow Array 3 at <place>...
for my $num (@array) {    ### Slow array3 [===|   ] [%] done
 sleep 1 if $num % 4;
}


#### <now> Slow Array 4 at <where>...
for my $num (@array)
{                         ### Slow array4===[%]       done
 sleep 1 if $num % 4;
 print "$num\n";
}

__END__

=head1 NAME

smart-comment-example - Using Smart::Comments with Getopt::Long (and Pod::Usage)

=head1 SYNOPSIS

smart-comment-sample [options]
 
 Environment
  Smart_Comments  Set the environment variable Smart_Comments = 1 to enable comments.

 Options: 
  --help         brief help message
  --man          full documentation
  --DEBUG        increase debug level

=head1 OPTIONS

=over 4

=item B<--help>

Print a brief help message and exit.

=item B<--man>

Print the manual page and exit.

=item B<--DEBUG>

Affect the DEBUG/verbose level

=back

=head1 DESCRIPTION

B<This program> will demonstrate smart comments (Smart::Comments) as well as
boilerplate for setting up Getopt::Long with Pod::Usage

=cut