NAME
    MooseX::Role::Loggable - Extensive, yet simple, logging role using
    Log::Dispatchouli

VERSION
    version 0.112

SYNOPSIS
        package My::Object;

        use Moose; # or Moo
        with 'MooseX::Role::Loggable';

        sub do_this {
            my $self = shift;
            $self->set_prefix('[do_this] ');
            $self->log_debug('starting...');
            ...
            $self->log_debug('more stuff');
            $self->clear_prefix;
        }

DESCRIPTION
    This is a role to provide logging ability to whoever consumes it using
    Log::Dispatchouli. Once you consume this role, you have attributes and
    methods for logging defined automatically.

        package MyObject;
        use Moose # Moo works too
        with 'MooseX::Role::Loggable';

        sub run {
            my $self = shift;

            $self->log('Trying to do something');

            # this only gets written if debug flag is on
            $self->log_debug('Some debugging output');

            $self->log(
                { level => 'critical' },
                'Critical log message',
            );

            $self->log_fatal('Log and die');
        }

    This module uses Moo so it takes as little resources as it can by
    default, and can seamlessly work with both Moo or Moose.

Propagating logging definitions
    Sometimes your objects create additional object which might want to log
    using the same settings. You can simply give them the same logger
    object.

        package Parent;
        use Moose;
        with 'MooseX::Role::Loggable';

        has child => (
            is      => 'ro',
            isa     => 'Child',
            lazy    => 1,
            builder => '_build_child',
        );

        sub _build_child {
            my $self = shift;
            return Child->new( logger => $self->logger );
        }

ATTRIBUTES
  debug
    A boolean for whether you're in debugging mode or not.

    Default: no.

    Read-only.

  logger_facility
    The facility the logger would use. This is useful for syslog.

    Default: local6.

  logger_ident
    The ident the logger would use. This is useful for syslog.

    Default: calling object's class name.

    Read-only.

  log_to_file
    A boolean that determines if the logger would log to a file.

    Default location of the file is in /tmp.

    Default: no.

    Read-only.

  log_to_stdout
    A boolean that determines if the logger would log to STDOUT.

    Default: no.

  log_to_stderr
    A boolean that determines if the logger would log to STDERR.

    Default: no.

  log_file
    The leaf name for the log file.

    Default: undef

  log_path
    The path for the log file.

    Default: undef

  log_pid
    Whether to append the PID to the log filename.

    Default: yes

  log_fail_fatal
    Whether failure to log is fatal.

    Default: yes

  log_muted
    Whether only fatals are logged.

    Default: no

  log_quiet_fatal
    From Log::Dispatchouli: *'stderr' or 'stdout' or an arrayref of zero,
    one, or both fatal log messages will not be logged to these*.

    Default: stderr

  logger
    A Log::Dispatchouli object.

METHODS
    All methods here are imported from Log::Dispatchouli. You can read its
    documentation to understand them better.

  log
    Log a message.

  log_debug
    Log a message only if in debug mode.

  log_fatal
    Log a message and die.

  set_debug
    Set the debug flag.

  clear_debug
    Clear the debug flag.

  set_prefix
    Set a prefix for all next messages.

  clear_prefix
    Clears the prefix for all next messages.

  set_muted
    Sets the mute property, which makes only fatal messages logged.

  clear_muted
    Clears the mute property.

  BUILDARGS
    You shouldn't care about this. It takes care of propagating attributes
    from a given logger (if you provided one) to the attributes this role
    provides.

  log_fields
    DEPRECATED.

    Please pass the logger attribute instead:

        SomeObject->new( logger => $parent->logger );

DEBUGGING
    Occassionally you might encounter the following error:

        no ident specified when using Log::Dispatchouli at Loggable.pm line 117.

    The problem does not stem from MooseX::Role::Loggable, but from a
    builder calling a logging method before the logger is built. Since Moo
    and Moose do not assure order of building attributes, which means that
    some attributes might not exist by the time you need them.

    This specific error happens when the "ident" attribute isn't built by
    the time a builder runs. In order to avoid it, the attribute which uses
    the builder should be made lazy, and then called in the "BUILD" method.
    Here is an example:

        package Stuff;

        use Moose;
        with 'MooseX::Role::Logger';

        has db => (
            is      => 'ro',
            lazy    => 1,
            builder => '_build_db',
        }

        sub _build_db {
            my $self = shift;
            $self->log_debug('Building DB');
            ...
        }

        sub BUILD {
            my $self = shift;
            $self->db;
        }

    This makes the "db" attribute non-lazy, but during run-time. This will
    assure that all the logging attributes are created before you build the
    "db" attribute and call "log_debug".

AUTHOR
    Sawyer X <xsawyerx@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2012 by Sawyer X.

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