view release on metacpan or  search on metacpan

lib/Log/Shiras/LogSpace.pm  view on Meta::CPAN

use utf8;
use lib '../../';
use Moose::Role;
use MooseX::Types::Moose qw( Str );

#########1 Public Attributes  3#########4#########5#########6#########7#########8#########9

has log_space =>(
		isa		=> Str,
		reader	=> 'get_log_space',
		writer	=> 'set_log_space',
		predicate	=> 'has_log_space',
		default	=> sub{
			my( $self ) = @_;
			my $ref = ref $self ? ref( $self ) : $self;
			if( $self->can( 'get_class_space' ) ){# avoid duplicating class space at the end
				my $class_space = $self->get_class_space;
				if( $ref =~ /(.*)(::$class_space)/ ){
					$ref = $1;
				}
			}
			return $ref;
		}
	);

#########1 Public Methods     3#########4#########5#########6#########7#########8#########9

sub get_all_space{
	my ( $self, $add_string ) = @_;
	my	$all_space = $self->get_log_space;
	if( $self->can( 'get_class_space' ) and length( $self->get_class_space ) > 0 ){
		$all_space .= '::' . $self->get_class_space;
	}
	if( $add_string and length( $add_string ) > 0 ){
		$all_space .= '::' . $add_string;
	}
	return $all_space;
}

#########1 Private Attributes 3#########4#########5#########6#########7#########8#########9

#########1 Private Methods    3#########4#########5#########6#########7#########8#########9

#########1 Phinish            3#########4#########5#########6#########7#########8#########9

no Moose::Role;

1;
# The preceding line will help the module return a true value

#########1 main POD docs      3#########4#########5#########6#########7#########8#########9

__END__

=head1 NAME

Log::Shiras::LogSpace - Log::Shiras Role for runtime name-spaces

=head1 SYNOPSIS

	use Modern::Perl;
	use MooseX::ShortCut::BuildInstance qw( build_class );
	use Log::Shiras::LogSpace;
	my $test_instance = build_class(
			package => 'Generic',
			roles =>[ 'Log::Shiras::LogSpace' ],
			add_methods =>{
				get_class_space => sub{ 'ExchangeStudent' },
				i_am => sub{
					my( $self )= @_;
					print "I identify as a: " . $self->get_all_space( 'individual' ) . "\n";
				}
			},
		);
	my $Generic = $test_instance->new;
	my $French = $test_instance->new( log_space => 'French' );
	my $Spanish = $test_instance->new( log_space => 'Spanish' );
	$Generic->i_am;
	$French->i_am;
	$Spanish->i_am;

	#######################################################################################
	# Synopsis Screen Output
	# 01: I identify as a: Generic::ExchangeStudent::individual
	# 02: I identify as a: French::ExchangeStudent::individual
	# 03: I identify as a: Spanish::ExchangeStudent::individual
	#######################################################################################

=head1 DESCRIPTION

This attribute is useful to manage runtime L<Log::Shiras> caller namespace.  In the case
where MyCoolPackage with Log::Shiras lines is used in more than one context then it is
possible to pass a context sensitive name to the attribute log_space on intantiation of the
instance and have the namespace bounds only activate the desired context of the package
rather than have it report everywhere it is used.  The telephone call in this case would
look something like this;

	package MyCoolPackage

	sub get_class_space{ 'MyCoolPackage' }

	sub my_cool_sub{
		my( $self, $message ) = @_;
		my $phone = Log::Shiras::Telephone->new(
						name_space => $self->get_all_space . '::my_cool_sub',
					);
		$phone->talk( level => 'debug',
			message => "Arrived at my_cool_sub with the message: $message" );
		# Do something cool here!
	}

In this case if you used my cool package instances with the log_space set to different
values then only the namespace unblocked for 'FirstInstance::MyCoolPackage::my_cool_sub'
would report.  See the documentation for L<get_all_space|/get_all_space> for details.

As a general rule it works best if the subroutine 'get_class_space' is defined in an object 
class file (not a role file).  Each subroutine space can be identified with the $add_string 
passed to get_all_space.

=head2 Attributes