NAME

Padre::Log - Simple logger for Padre

SYNOPSIS

While working inside Padre, what you probably want is:

        my $main = Padre->wx->ide->main; # you most likely already have
                                   # one of those in your sub

        my $log = $main->log;

        $log->debug('now *there* is your problem!');
        $log->info('here I am');
        $log->warn('Danger! Danger!');
        $log->error('This shouldn't have happened');
        $log->fatal("Argh, I'm dead");

        if ( $log->is_debug() ) {
                $log->debug("add expensive @debugging over here")
        }

DESCRIPTION

This module provides a simple mechanism to log messages within Padre. Padre developers are encouraged to use this along the code.

HOW TO USE IT

The Padre logging system is set via Padre's configuration file, config.yml:

        log: 1
        log_level: 'debug'
        log_trace: 0
        log_filename: undef

But you should select these options directly via the 'Padre Developer Tools' Plugin that comes bundled with Padre.

Log Levels

There are five predefined log levels: debug, info, warn, error, and fatal, in descending priority. This means that, if your configured logging level is warn, then messages sent with debug and info methods will be supressed, while warn, error and fatal messages will make their way through, since their priority is higher or equal than the configured setting.

Level Cheking Methods

For every log level, there is a corresponding level checking method, useful when the logging level may not be reached and we want to block unnecessary expensive parameter construction, like in:

        if ($log->is_error()) {
                $log->error("The array had: @super_long_array");
        }

If we had just written:

        $log->error("The array had: @super_long_array");

then Perl would have interpolated @super_long_array into the string via an expensive operation only to figure out shortly after that the string can be ignored entirely because the configured logging level is lower than 'error'.

The availables level checking methods are:

        $log->is_debug()    # True if debug messages would go through
        $log->is_info()     # True if info  messages would go through
        $log->is_warn()     # True if warn  messages would go through
        $log->is_error()    # True if error messages would go through
        $log->is_fatal()    # True if fatal messages would go through

The $log->is_warn() method, for example, returns true if the logger's current level is warn, error or fatal.

OTHER METHODS

Developers usually don't have to worry about these methods, except if dealing with Padre::Wx::Main, Padre::Plugin::Devel or some other related code.

new

Returns a new Padre::Log object. You can specify the following parameters:

        my $log = Padre::Log->new(
                filename => '/var/log/padre.log',
                level    => 'info',
                trace    => 1,
        );

filename

If you want to save Padre's log messages to a log file, you can specify a target filename for it. Doing this, the new() method will automatically call set_filename() for you.

level

This attribute specifies the minimum log level to use. Doing this, the new() method will automatically call set_log_level() for you.

trace

This attribute specifies whether a trace output should be issued after every log message. Doing this, the new() method will automatically call enable_trace() for you.

set_log_level

        $log->set_log_level('debug');
  

Dynamically switches the minimum log level of your logging object. The name is specified as a case insensitive string. If you specify anything other than a valid log level (see "Log Levels" above), or don't pass anything at all, the default minimum log level will be set to 'warn'.

Disabling the logger

There is a special log level called 'off' which is higher than any other level and is never used for logging. So, if you do:

        $log->set_log_level('off');

You will supress all logging.

set_filename

        $log->set_filename('/var/log/padre.log');

Makes the logging object record its received messages into the specified file. If it exists, the output will be appended. If it doesn't exist, the logger will automatically create it. If it can't create it, an error will be issued to STDERR everytime the logger tries to log something. If you set the filename value to an empty string, undef or 0, STDERR will be used.

enable_trace, disable_trace

  $log->enable_trace();   # trace output is on
  $log->disable_trace();  # trace output is off

Enables and disables tracing. The trace output is done with Carp::longmess.

SEE ALSO

Padre::Manual::Hacking, Padre, Padre::Plugin::Devel, Carp.

This modules's functionallity was heavily based on Log::Dispatch and Log::Log4perl.

COPYRIGHT & LICENSE

Copyright 2008-2009 The Padre development team as listed in Padre.pm.

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

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

cpanm Padre

perl -MCPAN -e shell
install Padre