NAME

Package::Debug::Object - Object oriented guts to Package::Debug

VERSION

version 0.2.2

METHODS

new

    my $object = Package::Debug::Object->new(%args);

debug_style

set_debug_style

env_key_aliases

set_env_key_aliases

env_key_prefix_style

set_env_key_prefix_style

env_key_style

set_env_key_style

into

set_into

into_level

set_into_level

sub_name

set_sub_name

value_name

set_value_name

env_key

set_env_key

env_key_prefix

set_env_key_prefix

debug_sub

set_debug_sub

log_prefix_style

set_log_prefix_style

log_prefix

set_log_prefix

is_env_debugging

set_is_env_debugging

into_stash

set_into_stash

auto_set_into

This method any plumbing will want to call.

    $object->auto_set_into( $number_of_additional_stack_levels );

Takes a parameter to indicate the expected additional levels of stack will be need.

For instance:

    sub import {
        my ($self, %args ) = @_;
        my $object = ...->new(%args);
        $object->auto_set_into(1); # needs to be bound to the caller to import->()
    }

Or

    sub import {
        my ($self, %args ) = @_;
        my $object = ...->new(%args);
        __PACKAGE__->bar($object);

    }
    sub bar {
        $_[1]->auto_set_into(2); # skip up to caller of bar, then to caller of import
    }

And in both these cases, the end user just does:

    package::bar->import( into_level =>  0 ); # inject at this level

debug_prefixed_lines

    my $code = $object->debug_prefixed_lines;
    $code->( $message );

This Debug implementation returns a DEBUG sub that treats all arguments as lines of message, and formats them as such:

    [SomePrefix::Goes::Here] this is your messages first line\n
    [SomePrefix::Goes::Here] this is your messages second line\n

The exact prefix used is determined by log_prefix, and the prefix will be omitted if log_prefix is not defined.

( Note: this will likely require explicit passing of

    log_prefix => undef

)

debug_verbatim

This Debug implementation returns a DEBUG sub that simply passes all parameters to *STDERR->print, as long as debugging is turned on.

    my $code = $object->debug_verbatim;
    $code->( $message );

env_key_from_package

This env_key_style simply appends _DEBUG to the env_key_prefix

    my $key = $object->env_key_from_package;

env_key_prefix_from_package

This env_key_prefix_style converts into to a useful %ENV name.

    Hello::World::Bar -> HELLO_WORLD_BAR

Usage:

    my $prefix = $object->env_key_prefix_from_package;

log_prefix_from_package_short

This log_prefix_style determines a short name by mutating into.

When the name is <10 chars it is passed unmodified.

Otherwise, it is tokenised, and all tokens bar the last are reduced to either

a - groups of upper case only characters

b - failing case a, single lower case characters.

    Hello -> H
    HELLO -> HELLO
    DistZilla -> DZ
    mutant -> m

And then regrouped and the last attached

    This::Is::A::Test -> T:I:A::Test
    NationalTerrorismStrikeForce::SanDiego::SportsUtilityVehicle -> NTSF:SD::SportsUtilityVehicle

Usage:

    my $prefix = $object->log_prefix_from_package_short;

log_prefix_from_package_long

This log_prefix_style simply returns into as-is.

Usage:

    my $prefix = $object->log_prefix_from_package_long;

inject_debug_value

Optimistically injects the desired $DEBUG symbol into the package determined by value_name.

Preserves the existing value if such a symbol already exists.

    $object->inject_debug_value();

inject_debug_sub

Injects the desired code reference DEBUG symbol into the package determined by sub_name

    $object->inject_debug_sub();

ATTRIBUTES

debug_style

The debug printing style to use.

    'prefixed_lines'

See debug_styles

env_key_aliases

A [] of %ENV keys that also should trigger debugging on this package.

    []

env_key_prefix_style

The mechanism for determining the prefix for the %ENV key.

    'default'

See env_key_prefix_styles

env_key_style

The mechanism for determining the final %ENV key for turning on debug.

    'default'

See env_key_styles

into

The package we're injecting into.

IMPORTANT: This field cannot vivify itself and be expected to work.

Because much code in this module depends on this field, if this field is NOT populated explicitly by the user, its likely to increase the stack depth, invalidating any value if into_level that was specified.

See auto_set_into

into_level

The number of levels up to look for into

Note, that this value is expected to be provided by a consuming class somewhere, and is expected to be simply passed down from a user.

See auto_set_into for how to set into sanely.

sub_name

The name of the CODEREF that will be installed into into

    'DEBUG'

value_name

The name of the $SCALAR that will be installed into into

    'DEBUG' ## $DEBUG

env_key

The name of the primary %ENV key that controls debugging of this package.

If unspecified, will be determined by the env_key_style

Usually, this will be something like

    <env_key_prefix>_DEBUG

And where env_key_prefix is factory,

    <magictranslation(uc(into))>_DEBUG

Aka:

    SOME_PACKAGE_NAME_DEBUG

env_key_prefix

The name of the PREFIX to use for %ENV keys for this package.

If unspecified, will be determined by the env_key_prefix_style

Usually, this will be something like

    <magictranslation(uc(into))>

Aka:

    SOME_PACKAGE_NAME

debug_sub

The actual code ref to install to do the real debugging work.

This is mostly an implementation detail, but if you were truly insane, you could pass a custom coderef to construction, and it would install the coderef you passed instead of the one we generate.

Generated using debug_style

log_prefix_style

The default style to use for log_prefix.

If not set, defaults to the value of $ENV{PACKAGE_DEBUG_LOG_PREFIX_STYLE} if it exists, or simply 'short' if it does not.

See log_prefix_styles

log_prefix

The string to prefix to log messages for debug implementations which use prefixes.

If not specified, will be generated from the style specified by log_prefix_style

Which will be usually something like

    Foo::Package::Bar # 'long'
    F:P::Bar          # 'short'

is_env_debugging

The determination as to whether or not the %ENV indicates debugging should be enabled.

Will always be true if $ENV{PACKAGE_DEBUG_ALL}

And will be true if either env_key or one of env_key_aliases is true.

NOTE: This value BINDS the first time it is evaluated, so for granular control of debugging at run-time, you should not be lexically changing %ENV.

Instead, you should be modifying the value of $My::Package::Name::DEBUG

into_stash

Contains a Package::Stash object for the target package.

STYLES

env_key_styles

default

Uses env_key_from_package

env_key_prefix_styles

default

Uses env_key_prefix_from_package

log_prefix_styles

short

Uses log_prefix_from_package_short

long

Uses log_prefix_from_package_long

debug_styles

prefixed_lines

Uses debug_prefixed_lines

verbatim

Uses debug_verbatim

AUTHOR

Kent Fredric <kentfredric@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Kent Fredric <kentfredric@gmail.com>.

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

cpanm Package::Debug

perl -MCPAN -e shell
install Package::Debug