The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
POE-Component-SimpleLog-1.02
River stage one • 1 direct dependent • 1 total dependent
++
/ POE::Component::SimpleLog

NAME

POE::Component::SimpleLog - Perl extension to manage a simple logging system for POE.

SYNOPSIS

        use POE;
        use POE::Component::SimpleLog;

        # We don't want Time::HiRes
        POE::Component::SimpleLog->new(
                ALIAS           => 'MyLog',
                PRECISION       => undef,
        ) or die 'Unable to create the Logger';

        # Create our own session to communicate with SimpleLog
        POE::Session->create(
                inline_states => {
                        _start => sub {
                                # Register for various logs
                                $_[KERNEL]->post( 'MyLog', 'REGISTER',
                                        LOGNAME => 'FOO',
                                        SESSION => $_[SESSION],
                                        EVENT => 'GotFOOlog',
                                );

                                $_[KERNEL]->post( 'MyLog', 'REGISTER',
                                        LOGNAME => 'BAZ',
                                        SESSION => $_[SESSION],
                                        EVENT => 'GotBAZlog',
                                );

                                # Log something!
                                $_[KERNEL]->post( 'MyLog', 'LOG', 'FOO', 'Wow, what a FOO!' );

                                # This will be silently discarded -> nobody registered for it
                                $_[KERNEL]->post( 'MyLog', 'LOG', 'BOO', 'Wow, what a BAZ!' );

                                # OK, enough logging!
                                $_[KERNEL]->post( 'MyLog', 'UNREGISTER',
                                        LOGNAME => 'FOO',
                                        SESSION => $_[SESSION],
                                        EVENT => 'GotFOOlog',
                                );

                                # Now, this log will go nowhere as we just unregistered for it
                                $_[KERNEL]->post( 'MyLog', 'LOG', 'FOO', 'Wow, what a FOO!' );

                                # Completely remove all registrations!
                                $_[KERNEL]->post( 'MyLog', 'UNREGISTERSESSION', $_[SESSION] );

                                # Now, this log will go nowhere as we just removed all logs pertaining to our session
                                $_[KERNEL]->post( 'MyLog', 'LOG', 'BAZ', 'Wow, what a BAZ!' );

                                # We want to eat all we can!
                                $_[KERNEL]->post( 'MyLog', 'REGISTER',
                                        LOGNAME => 'ALL',
                                        SESSION => $_[SESSION],
                                        EVENT => 'GotLOG',
                                );

                                # Now, *ANY* log issued to SimpleLog will go to GotLOG
                                $_[KERNEL]->post( 'MyLog', 'LOG', 'LAF', 'Wow, what a LAF!' );

                                # We are done!
                                $_[KERNEL]->post( 'MyLog', 'shutdown' );
                        },

                        'GotFOOlog' => \&gotFOO,
                },
        );

        sub gotFOO {
                # Get the arguments
                my( $file, $line, $time, $name, $message ) = @_[ ARG0 .. ARG4 ];

                # Assumes PRECISION is undef ( regular time() )
                print STDERR "$time ${name}-> $file : $line = $message\n";
        }

ABSTRACT

        Very simple, and flexible logging system tailored for POE.

CHANGES

1.02

        Caught minor typo when loading Time::HiRes

1.01

        Initial Revision

DESCRIPTION

This module is a vastly simplified logging system that can do nice stuff. Think of this module as a dispatcher for various logs.

This module *DOES NOT* do anything significant with logs, it simply routes them to the appropriate place ( Events )

You register a log that you are interested in, by telling SimpleLog the target session and target event. Once that is done, any log messages your program generates ( sent to SimpleLog of course ) will be massaged, then sent to the target session / target event for processing.

This enables an interesting logging system that can be changed during runtime and allow pluggable interpretation of messages.

One nifty idea you can do with this is:

Your program generally creates logs with the name of 'DEBUG'. You DCC Chat your IRC bot, then tell it to show all debug messages to you. All the irc bot have to do is register itself for all 'DEBUG' messages, and once you disconnect from the bot, it can unregister itself.

NOTE: There is no pre-determined log levels ( Like Log4j's DEBUG / INFO / FATAL / etc ) Arbitrary names can be used, to great effect. Logs with the names 'CONNECT', 'DB_QUERY', etc can be created.

The standard way to use this module is to do this:

        use POE;
        use POE::Component::SimpleLog;

        POE::Component::SimpleLog->new( ... );

        POE::Session->create( ... );

        POE::Kernel->run();

Starting SimpleLog

To start SimpleLog, just call it's new method:

        POE::Component::SimpleLog->new(
                'ALIAS'         =>      'MyLogger',
                'PRECISION'     =>      1,
        );

This method will die on error or return success.

This constructor accepts only 2 options.

ALIAS

This will set the alias SimpleLog uses in the POE Kernel. This will default TO "SimpleLog"

PRECISION

If this value is defined, SimpleLog will use Time::HiRes to get the timestamps.

Events

SimpleLog is so simple, there are only 5 events available.

REGISTER
        This event accepts 3 arguments:

        LOGNAME ->      The name of the log to register for
        SESSION ->      The session where the log will go ( Also accepts Session ID's )
        EVENT   ->      The event that will be called

        The act of registering for a log can fail if one of the above values are undefined.

        If the LOGNAME eq 'ALL', then that registration will get *ALL* the logs SimpleLog processes

        There is no such thing as an "non-existant" log, registration just makes sure that you will get this log *WHEN* it comes.

        Events that receive the logs will get these:
                ARG0 -> CALLER_FILE
                ARG1 -> CALLER_LINE
                ARG2 -> Time::HiRes [ gettimeofday ] or time()
                ARG3 -> LOGNAME
                ARG4 -> Message

        Here's an example:

        $_[KERNEL]->post( 'SimpleLog', 'REGISTER',
                LOGNAME => 'CONNECTION',
                SESSION => $_[SESSION],
                EVENT => 'GotLOG',
        );

        This is the subroutine that will get the GotLOG event
        sub gotlog {
                # Get the arguments
                my( $file, $line, $time, $name, $message ) = @_[ ARG0 .. ARG4 ];

                # Assumes PRECISION is undef ( regular time() )
                print STDERR "$time ${name}-> $file : $line = $message\n";

                # PRECISION = true ( Time::HiRes )
                print STDERR "$time->[0].$time->[1] ${name}-> $file : $line = $message\n";
        }
UNREGISTER
        This event accepts 3 arguments:

        LOGNAME ->      The name of the log to unregister for
        SESSION ->      The session where the log will go ( Also accepts Session ID's )
        EVENT   ->      The event that will be called

        Unregistering for a log will fail if the exact 3 arguments were not found in our registry.

        The act of unregistering will mean the session/event no longer receives any log messages.

        NOTE: There might be some logs still traversing POE's queue...

        Here's an example:

        $_[KERNEL]->post( 'SimpleLog', 'UNREGISTER',
                LOGNAME => 'CONNECTION',
                SESSION => $_[SESSION]->ID,
                EVENT => 'GotLOG',
        );
UNREGISTERSESSION
        This event accepts 1 argument:

        ARG0    ->      The session ( Also accepts Session ID's )

        This is useful for removing all the registrations for a specific session.

        Here's an example:

        $_[KERNEL]->post( 'SimpleLog', 'UNREGISTERSESSION', $_[SESSION] );
LOG
        This event accepts 2 arguments:

        ARG0    ->      Logname
        ARG1    ->      Message

        This is where SimpleLog does it's work, sending the log to the proper events.

        The Logname can be anything, if there is no events registered for it, the message will simply be discarded.

        Here's an example:

        $_[KERNEL]->post( 'SimpleLog', 'LOG', 'CONNECTION', 'A Client just connected!' );
shutdown
        This is the generic shutdown routine, it will stop all logging.

        Here's an example:

        $_[KERNEL]->post( 'SimpleLog', 'shutdown' );

SimpleLog Notes

This module is very picky about capitalization!

All of the options are uppercase, to avoid confusion.

You can enable debugging mode by doing this:

        sub POE::Component::SimpleLog::DEBUG () { 1 }
        use POE::Component::SimpleLog;

EXPORT

Nothing.

SEE ALSO

POE

AUTHOR

Apocalypse <apocal@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2004 by Apocalypse

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