The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

 Filter::Uncomment - Efficiently uncomment sections of your code

SYNOPSIS

        #~ use Filter::Uncomment qw(multi single) ;
        #~ use Filter::Uncomment qw(multi) ;

        use Filter::Uncomment 
                GROUPS =>
                        {
                        multi  => ['multi_line', 'multi line with spaces'] ,
                        single => ['single_line', 'single line with spaces'] ,
                        all    => 
                                [
                                'multi_line', 'multi line with spaces',
                                'single_line', 'single line with spaces',
                                ] ,
                        };

        $> perl -MFilter::Uncomment=multi test.pl

DESCRIPTION

This module write code that you want be active in only certain circumstances.

DOCUMENTATION

Contrast:

        #example 1
        
        for my $variable (1 .. $lots)
                {
                ## debug Debug($variable) ;
                
                DoSomethingWith($value) ;
                }

with

        # example 2
        
        for my $variable (1 .. $lots)
                {
                Debug($variable) if($debug)  ;
                
                DoSomethingWith($value) ;
                }

In example #2, you will always pay for checking the $debug variable. This might be significant in a very tight loop or when you have lots of sections you comment out.

Filter::Uncomment is a source code filter that will uncomment sections of perl code only on demand. The uncommenting is done before compile time, you pay only once for it at the program load time.

Example #1 would effectively become:

        #example 1, uncommented
        
        for my $variable (1 .. $lots)
                {
                Debug($variable) ;
                
                DoSomethingWith($value) ;
                }

Filter::Uncomment can uncomment single line perl comments, or multiline perl comments.

        ## debug Debug($variable) ;
        
        =for flag
        
        PerlCode() ;
        MorePerlCode() ;
        
        =cut
        
        ## tag_can_be_a_single_word HereIsTheCode() ;
        
        ## or it can be a multiple wors separated by spaces HereIsTheCode() ;
        

Defining tags

        use Filter::Uncomment 
                GROUPS =>
                        {
                        # name    # elements for each group
                        multi  => ['multi_line', 'multi line with spaces'] ,
                        single => ['single_line', 'single line with spaces'] ,
                        } ;

Uncommenting

Uncommenting is most often done on the command line but can also be done from a module or your script.

From the command line:

        perl -MFilter::Uncomment=multi script.pl
        perl -MFilter::Uncomment=multi -MFilter::Uncomment=single script.pl
        

From a module or script;

        use Filter::Uncomment qw(multi single) ;

SUBROUTINES/METHODS

import

This is automatically called for you by Perl

FILTER

This is automatically called for you by Perl

BUGS AND LIMITATIONS

None so far.

AUTHOR

        Khemir Nadim ibn Hamouda
        CPAN ID: NKH
        mailto:nadim@khemir.net

LICENSE AND COPYRIGHT

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

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Filter::Uncomment

You can also look for information at:

SEE ALSO

The excellent Filter::Simple.