File Coverage

blib/lib/Log/Fine/Levels.pm

Criterion	Covered	Total	%
statement	44	44	100.0
branch	1	2	50.0
condition	1	2	50.0
subroutine	12	12	100.0
pod	7	7	100.0
total	65	67	97.0

=head1 NAME

Log::Fine::Levels - Define variable logging levels

=head1 SYNOPSIS

Provides logging translations

    use Log::Fine::Levels;

    # Instantiate the levels object using the default translations
    my $levels = Log::Fine::Levels->new();

    # Instantiate the levels object using customized translations
    my $levels = Log::Fine::Levels->new("Java");

    # Supported methods
    my @l = $levels->logLevels();   # grab list of levels
    my @m = $levels->logMasks();    # grab list of masks

    # Translation methods
    my $val     = $levels->levelToValue("INFO");
    my $bitmask = $levels->maskToValue("LOGMASK_INFO");
    my $lvl     = $levels->valueToLevel(3);

=head1 DESCRIPTION

Log::Fine::Levels is used by the L framework to translate
customizable log levels (such as INFO, DEBUG, WARNING, etc) to and
from an associated value as well as convenience methods for
interacting with log levels (such as grabbing a list of levels).

In addition, the L framework supports the notion of a
I, which is used for customizing output.  See
L for more details as to how masks are used.

=head2 Customization

Log::Fine::Levels only provides methods for interacting with log
levels and associated log masks.  In order to define levels and masks,
it I be overridden.  Note that, by default, the
L class is used to define log levels.

=head2 Independence

Finally, Log::Fine::Levels is written to be independant of the
L framework and, as such, does not inherit any methods from
L.  This allows developers to use Log::Fine::Levels by
itself for defining customizable level packages for use in their own
programs.

=cut

use strict;
use warnings;

package Log::Fine::Levels;

use Carp;
use Log::Fine;

our $VERSION = $Log::Fine::VERSION;

# Constants
# --------------------------------------------------------------------

use constant DEFAULT_LEVELMAP => "Syslog";

# --------------------------------------------------------------------

=head1 METHODS

The following methods are provided:

=head2 new

Creates a new Log::Fine::Levels object

=head3 Parameters

=over

=item  * levelmap

The name of the level map to use (e.g., C, C, etc)

=back

=head3 Returns

an L object

=cut

sub new
{

        my $class = shift;
        my $lvlmap = shift || DEFAULT_LEVELMAP;

        # Construct the string containing name of sub-class
        my $levelClass = join("::", $class, $lvlmap);

        # Validate levelclass and return if successful
        eval "require $levelClass";

        confess "Error : Level Class $levelClass does not exist : $@"
            if $@;

        return $levelClass->new();

}          # new()

=head2 bitmaskAll

Getter for a bitmask representing B possible values

=head2 Returns

Bitmask representing all possible mask values

=cut

sub bitmaskAll
{

        my $self = shift;
        my $mask = 0;             # bitmask

        # bitor all the mask values together
        $mask |= $self->MASK_MAP->{$_} foreach (keys %{ $self->MASK_MAP });

        return $mask;

}          # bitmaskAll()

=head2 levelToValue

Level name to numeric value

=head3 Parameters

=over

=item  * level name

The name of the level

=back

=head3 Returns

The numeric value representing the given level name.  Undef if name is
not defined

=cut

sub levelToValue { return $_[0]->LVLTOVAL_MAP->{ $_[1] }; }

=head2 logLevels

Getter for all log levels

=head3 Returns

An array representing all level names, sorted by ascending numeric
value

=cut

sub logLevels
{

        my $self = shift;
        my @lvls;

        # Construct array sorted by level value (ascending) and return
        push @lvls, $self->VALTOLVL_MAP->{$_}
            foreach (sort { $a <=> $b } (keys %{ $self->VALTOLVL_MAP }));

        return @lvls;

}          # logLevels()

=head2 logMasks

Getter for all log masks

=head3 Returns

An array representing all mask names, sorted by ascending numeric
value

=cut

sub logMasks
{

        my $self = shift;
        my $vtom = {};
        my @masks;

        # Build hash of mask values to mask names
        $vtom->{ $self->MASK_MAP->{$_} } = $_
            foreach (keys %{ $self->MASK_MAP });

        # Construct array sorted by mask value (ascending) and return
        push @masks, $vtom->{$_} foreach (sort { $a <=> $b } (keys %{$vtom}));

        return @masks;

}          # logMasks()

=head2 maskToValue

Mask name to numeric value

=head3 Parameters

=over

=item  * mask name

The name of the mask

=back

=head3 Returns

The numeric value representing the given mask name.  Undef if name is
not defined

=cut

sub maskToValue { return $_[0]->MASK_MAP->{ $_[1] }; }

=head2 valueToLevel

Level value to level name

=head3 Parameters

=over

=item  * numeric value

The numeric value representing a level

=back

=head3 Returns

The level name associated with the given numeric value.  Undef if the
value is not defined

=cut

sub valueToLevel { return $_[0]->VALTOLVL_MAP->{ $_[1] }; }

=head1 BUGS

Please report any bugs or feature requests to
C, or through the web interface at
L.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.

=head1 SUPPORT

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

    perldoc Log::Fine::Levels

You can also look for information at:

=over 4

=item * AnnoCPAN: Annotated CPAN documentation

L

=item * CPAN Ratings

L

=item * RT: CPAN's request tracker

L

=item * Search CPAN

L

=back

=head1 AUTHOR

Christopher M. Fuhrman, C<<  >>

=head1 SEE ALSO

L, L, L, L

=head1 COPYRIGHT & LICENSE

Copyright (c) 2009, 2010, 2013 Christopher M. Fuhrman,
All rights reserved.

This program is free software licensed under the...

	The BSD License

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

=cut

1;          # End of Log::Fine::Levels