The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Log-Shiras-v0.48.0
River stage one • 1 direct dependent • 1 total dependent
1 ++
/ Log::Shiras::Unhide

NAME

Log::Shiras::Unhide - Unhides Log::Shiras hidden comments in @ISA

SYNOPSIS

        #!perl
        # Note this example uses the demonstration package Level1.pm Level2.pm, and Level3.pm
        use     lib     '../lib',;

        BEGIN{
                $ENV{hide_warn} = 1;
        }
        use Log::Shiras::Unhide qw( :debug :Meditation  :Health :Family );
        my      $basic = 'Nothing';
        ###LogSD        $basic = 'Something';
        warn 'Found ' . $basic;
        my      $health = 'Sick';
        ###Health       $health = 'Healthy';
        warn 'I am ' . $health;
        my      $wealth = 'Broke';
        ###Wealth       $wealth = 'Rich';
        warn 'I am ' . $wealth;
        use Level1; # Which uses Level2 which uses Level3
        warn Level1->check_return;

        #######################################################################################
        # Synopsis Screen Output for the following conditions
        # $ENV{hide_warn} = 1;# In a BEGIN block
        # 'use Log::Shiras::Unhide qw( :debug :Meditation  :Health :Family :InternalSwitchboarD );'
        # 01: Using Log::Shiras::Unhide-v0.29_1 strip_match string: (LogSD|Meditation|Health|Family) at ../lib/Log/Shiras/Unhide.pm line 88.
        # 02: Found Something at log_shiras_unhide.pl line 8.
        # 03: I am Healthy at log_shiras_unhide.pl line 11.
        # 04: I am Broke at log_shiras_unhide.pl line 14.
        # 05: Level3 Peace uncovered - Level2 Healing uncovered - Level1 Joy uncovered at log_shiras_unhide.pl line 16.
        #######################################################################################

        #######################################################################################
        # Synopsis Screen Output for the following conditions
        # $ENV{hide_warn} = 0;
        # 'use Log::Shiras::Unhide( :debug );
        # 01: Found Something at log_shiras_unhide.pl line 8.
        # 02: I am Sick at log_shiras_unhide.pl line 11.
        # 03: I am Broke at log_shiras_unhide.pl line 14.
        # 04: Level3 LogSD uncovered - No Level2 uncovering occured - No Level1 uncovering occured at log_shiras_unhide.pl line 16.
        #######################################################################################

DESCRIPTION

This package will strip '###SomeKey' tags from your script after the 'use Log::Shiras::Unhide;' statement. It will also recursivly parse down through any included lower level modules as well. If Log::Shiras::Unhide is called in some lower place it's import settings there will be overridden by the top level call.

Since this module implements a source filter and source filters are not universally loved the module will generally emit a warning statement when it implements the source filter. To turn that off you need to set $ENV{hide_warn} = 1 in a BEGIN block prior to 'use'ing Log::Shiras::Unhide. The SYNOPSIS includes examples of various tags that are stripped at compile time with some examples of tags in the code that are not stripped since they are not passed to import. It is important to note that both the synopsis and supporting modules are all stored in the 'examples' folder of this distribution. You can inspect the specific implemenation for Level1.pm which uses Level2.pm which uses Level3.pm. This demonstrates that the source filter is implemented accross the full depth of used packages.

When Moose uses a role with the word 'with' the Unhide process is not called. You can get around this by calling 'use My::Role' prior to 'with My::Role'. The role will then be consumed (implemented) by 'with' in it's stripped state.

This class takes unashamedly from Log::Log4perl::Resurrector. Any mistakes are my own and the genius is from there. Log::Log4perl::Resurrector also credits the Acme::Incorporated CPAN module, written by chromatic. Of course none of it would be possible without Filter::Util::Call. Long live CPAN!

The point of using this module is to add lines that are only exposed some time. However, this makes it difficult to troubleshoot syntax errors in those lines using your favorite editor or debuger when implementing the lines to begin with. One way to resolve this is to place two lines at the top of your code that will unhide those lines temporarily when you are testing it and then either delelete or comment out the first line when releasing. The purpose of the first line is to unhide your lines for testing and the second will issue a warning so you don't forget you are in dev mode. An example is;

    #~ use Log::Shiras::Unhide qw( :MyCoolUnhideStrinG );
    ###MyCoolUnhideStrinG       warn "You uncovered internal logging statements for My::Cool::Package-$VERSION";

If you choose to leave line two in then you also have an indication if the module was implemented in a stripped fashion whenever you call it.

TL;DR

This package definitly falls in the dark magic catagory and will only slow your code down. Don't use it if you arn't willing to pay the price. The value is all the interesting information you receive from the exposed code. While this does use Filter::Util::Call to handle scrubbing the top level script. The included modules are scrubbed with a hook into @INC search for hook on that page The scrubbed modules are built and loaded via temporary files built with File::Temp. In general this is a good think since File::Temp does a good job of garbage collection the garbage collection fails when the code 'dies' or 'confesses.. If your code regularly dies or fails while ~::Unhide is active it will leave a lot of orphaned files in the temp directory.

This module also adds a startup hit to any processing where filtering is turned on and as such should be used with caution, however, an attempt has been made to mitigate that by excluding Module names matching the following regex;

        qr/(
                ^Archive.Zip|           ^attributes|            ^AutoLoader|            ^B\.pm|
                ^B.(Op_|Deparse)|       ^B.(Hooks)|                     ^Carp|                          ^Class|
                ^Clone|                         ^common|                        ^Compress.Raw|          ^Cwd|
                ^Data.OptList|          ^DateTime(?!X)|         ^Devel|                         ^Encode|
                ^Eval|                          ^Exporter|                      ^feature|                       ^File|
                ^Filter|                        ^if\.pm|                        ^integer|                       ^IO.File|
                ^JSON|                          ^List|                          ^Log.Shiras.Unhide|     ^metaclass|
                ^Module|                        ^Moose(?!X)|            ^MooseX.Has|            ^MooseX.Non|
                ^MooseX.Singleton|      ^MooseX.Strict|         ^MooseX.Type|           ^MRO|
                ^namespace|                     ^Package|                       ^Params|                        ^parent|
                ^PerlIO|                        ^POSIX|                         ^re\.pm|                        ^SelfLoader|
                ^SetDual|                       ^Smart|                         ^Sub|                           ^Test2|
                ^Tie|                           ^Text|                          ^Time.Local|            ^Try|
                ^Type|                          ^UNIVERSAL|                     ^utf8|                          ^Variable|
                ^Win32|                         ^XML|                           ^YAML
        )/x;

Methods

This module does not provide any methods for the user other than what is called during 'use'. (import) Private methods will not be documented.

import

    Definition: perl auto calls import anytime the module is 'use'd. In this case the import statement will accept (first only and optional) a minimum version requirement in either v-string or decimal input. It will also accept any number of text strings matched to the regex [A-Za-z]+ prepended with ':'. These strings will be treated as case sensitive targets for this module to find and expose the line behind them using a source filter. It will look in 'use'd modules and strip those lines as well. The flags are transposed to include three '#'s without the colon. There can be more than one passed flag and all will be implemented. An example of the stripping implementation of imported flags are;

            qw(:FooBar :Baz) -> $line =~ s/^(\s*)###(FooBar|Baz)\s/$1/mg;

    There is one special flag that is transposed

            :debug -> strips '###LogSD' (for Log Shiras Debug)

    The overall package eats its own dogfood and uses module specific flags starting with 'InternaL'. See the source for each module to understand which flag is used.

    Accepts: $VERSION and colon prepended strip flags

    Returns: nothing, but it transforms files prior to use

Tags Available in CPAN

This is a list (not comprehensive) of tags embedded in packages I have released to CPAN. Since they require a source filter to uncover there should be minimal impact to using these packages unless this class is used.

SUPPORT

GLOBAL VARIABLES

$ENV{hide_warn}

The module will warn when tags are passed to it so you have visibility to Unhide actions. In the case where the you don't want these notifications set this environmental variable to true.

TODO

AUTHOR

Jed Lund
jandrew@cpan.org

COPYRIGHT

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

The full text of the license can be found in the LICENSE file included with this module.

This software is copyrighted (c) 2014 - 2016 by Jed Lund

DEPENDENCIES

SEE ALSO