Package::Debug::Object - Object oriented guts to Package::Debug
version 0.1.0
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
full_sub_name
set_full_sub_name
full_value_name
set_full_value_name
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
set_runtime_switchable
runtime_switchable
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:
DEBUG
[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.
*STDERR->print
my $code = $object->debug_verbatim; $code->( $message );
env_key_from_package
This env_key_style simply appends _DEBUG to the env_key_prefix
_DEBUG
my $key = $object->env_key_from_package;
env_key_prefix_from_package
This env_key_prefix_style converts into to a useful %ENV name.
%ENV
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.
short
When the name is <10 chars it is passed unmodified.
<10 chars
Otherwise, it is tokenised, and all tokens bar the last are reduced to either
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
my $prefix = $object->log_prefix_from_package_short;
log_prefix_from_package_long
This log_prefix_style simply returns into as-is.
my $prefix = $object->log_prefix_from_package_long;
get_debug_value
Returns the "are we debugging right now" value.
if ( $object->get_debug_value ) { print "DEBUGGING IS ON!" }
inject_debug_value
Optimistically injects the desired $DEBUG symbol into the package determined by full_value_name.
$DEBUG
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 full_sub_name
$object->inject_debug_sub();
The debug printing style to use.
'prefixed_lines'
See debug_styles
debug_styles
A [] of %ENV keys that also should trigger debugging on this package.
[]
The mechanism for determining the prefix for the %ENV key.
prefix
'default'
See env_key_prefix_styles
env_key_prefix_styles
The mechanism for determining the final %ENV key for turning on debug.
See env_key_styles
env_key_styles
Fully qualified name of the sub that will be injected to implement debugging.
sub
Default is:
<into> . '::' . <sub_name>
undef
If sub_name is undef
See into and sub_name
Fully qualified name of the value that will be injected to implement debugging control.
value
<into> . '::' . <value_name>
If value_name is undef
See into and value_name
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
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.
The name of the CODEREF that will be installed into into
CODEREF
'DEBUG'
The name of the $SCALAR that will be installed into into
$SCALAR
'DEBUG' ## $DEBUG
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
The name of the PREFIX to use for %ENV keys for this package.
If unspecified, will be determined by the env_key_prefix_style
<magictranslation(uc(into))>
SOME_PACKAGE_NAME
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.
coderef
Generated using debug_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.
$ENV{PACKAGE_DEBUG_LOG_PREFIX_STYLE}
'short'
See log_prefix_styles
log_prefix_styles
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'
The determination as to whether or not the %ENV indicates debugging should be enabled.
Will always be true if $ENV{PACKAGE_DEBUG_ALL}
true
$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
$My::Package::Name::DEBUG
This controls whether or not
$YourPackage::DEBUG
Should be modifiable at run-time.
If it is true, then a performance penalty will occur, because the DEBUG sub can no longer be a complete no-op, due to needing to check the value of this variable every time it is called.
no-op
default
Uses env_key_from_package
Uses env_key_prefix_from_package
Uses log_prefix_from_package_short
long
Uses log_prefix_from_package_long
prefixed_lines
Uses debug_prefixed_lines
verbatim
Uses debug_verbatim
_has
Internal minimalist lazy-build w/setter generator
_has $name => $coderef;
is roughly equivalent to Moo's
Moo
has $name => ( is => ro =>, lazy => 1, writer => "set_$name", builder => $coderef );
$coderef can be a string, in which case it will be bolted on slightly more efficiently, using
$coderef
string
sub Package::Debug::Object::namehere { the_actual_code_here }
Instead of
*Package::Debug::Object::namehere = $builder
_has_value
Internal function shredded from guts of Package::Stash::PP, for the purpose of determining if a given package already has a specific value defined or not.
Package::Stash::PP
This is mostly to facilitate this:
BEGIN { $Some::Package::DEBUG = 1; } use Some::Package;
This way, we don't stomp over that value.
if ( _has_value( $package, $variable_name ) ) { ... }
Kent Fredric <kentfredric@gmail.com>
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.
To install Package::Debug, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Package::Debug
CPAN shell
perl -MCPAN -e shell install Package::Debug
For more information on module installation, please visit the detailed CPAN module installation guide.