1POE::Component::SimpleLUosge(r3)Contributed Perl DocumenPtOaEt:i:oCnomponent::SimpleLog(3)
2
3
4

NAME

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

SYNOPSIS

10               use POE;
11               use POE::Component::SimpleLog;
12
13               # We don't want Time::HiRes
14               POE::Component::SimpleLog->new(
15                       ALIAS           => 'MyLog',
16                       PRECISION       => undef,
17               ) or die 'Unable to create the Logger';
18
19               # Create our own session to communicate with SimpleLog
20               POE::Session->create(
21                       inline_states => {
22                               _start => sub {
23                                       # Register for various logs
24                                       $_[KERNEL]->post( 'MyLog', 'REGISTER',
25                                               LOGNAME => 'FOO',
26                                               SESSION => $_[SESSION],
27                                               EVENT => 'GotFOOlog',
28                                       );
29
30                                       $_[KERNEL]->post( 'MyLog', 'REGISTER',
31                                               LOGNAME => 'BAZ',
32                                               SESSION => $_[SESSION],
33                                               EVENT => 'GotBAZlog',
34                                       );
35
36                                       # Log something!
37                                       $_[KERNEL]->post( 'MyLog', 'LOG', 'FOO', 'Wow, what a FOO!' );
38
39                                       # This will be silently discarded -> nobody registered for it
40                                       $_[KERNEL]->post( 'MyLog', 'LOG', 'BOO', 'Wow, what a BAZ!' );
41
42                                       # OK, enough logging!
43                                       $_[KERNEL]->post( 'MyLog', 'UNREGISTER',
44                                               LOGNAME => 'FOO',
45                                               SESSION => $_[SESSION],
46                                               EVENT => 'GotFOOlog',
47                                       );
48
49                                       # Now, this log will go nowhere as we just unregistered for it
50                                       $_[KERNEL]->post( 'MyLog', 'LOG', 'FOO', 'Wow, what a FOO!' );
51
52                                       # Completely remove all registrations!
53                                       $_[KERNEL]->post( 'MyLog', 'UNREGISTERSESSION', $_[SESSION] );
54
55                                       # Now, this log will go nowhere as we just removed all logs pertaining to our session
56                                       $_[KERNEL]->post( 'MyLog', 'LOG', 'BAZ', 'Wow, what a BAZ!' );
57
58                                       # We want to eat all we can!
59                                       $_[KERNEL]->post( 'MyLog', 'REGISTER',
60                                               LOGNAME => 'ALL',
61                                               SESSION => $_[SESSION],
62                                               EVENT => 'GotLOG',
63                                       );
64
65                                       # Now, *ANY* log issued to SimpleLog will go to GotLOG
66                                       $_[KERNEL]->post( 'MyLog', 'LOG', 'LAF', 'Wow, what a LAF!' );
67
68                                       # We are done!
69                                       $_[KERNEL]->post( 'MyLog', 'SHUTDOWN' );
70                               },
71
72                               'GotFOOlog' => \&gotFOO,
73                       },
74               );
75
76               sub gotFOO {
77                       # Get the arguments
78                       my( $file, $line, $time, $name, $message ) = @_[ ARG0 .. ARG4 ];
79
80                       # Assumes PRECISION is undef ( regular time() )
81                       print STDERR "$time ${name}-> $file : $line = $message\n";
82               }
83

ABSTRACT

85               Very simple, and flexible logging system tailored for POE.
86

DESCRIPTION

88       This module is a vastly simplified logging system that can do nice
89       stuff.  Think of this module as a dispatcher for various logs.
90
91       This module *DOES NOT* do anything significant with logs, it simply
92       routes them to the appropriate place ( Events )
93
94       You register a log that you are interested in, by telling SimpleLog the
95       target session and target event. Once that is done, any log messages
96       your program generates ( sent to SimpleLog of course ) will be mas‐
97       saged, then sent to the target session / target event for processing.
98
99       This enables an interesting logging system that can be changed during
100       runtime and allow pluggable interpretation of messages.
101
102       One nifty idea you can do with this is:
103
104       Your program generally creates logs with the name of 'DEBUG'. You DCC
105       Chat your IRC bot, then tell it to show all debug messages to you. All
106       the irc bot have to do is register itself for all 'DEBUG' messages, and
107       once you disconnect from the bot, it can unregister itself.
108
109       NOTE: There is no pre-determined log levels ( Like Log4j's DEBUG / INFO
110       / FATAL / etc ) Arbitrary names can be used, to great effect. Logs with
111       the names 'CONNECT', 'DB_QUERY', etc can be created.
112
113       The standard way to use this module is to do this:
114
115               use POE;
116               use POE::Component::SimpleLog;
117
118               POE::Component::SimpleLog->new( ... );
119
120               POE::Session->create( ... );
121
122               POE::Kernel->run();
123
124       Starting SimpleLog
125
126       To start SimpleLog, just call it's new method:
127
128               POE::Component::SimpleLog->new(
129                       'ALIAS'         =>      'MyLogger',
130                       'PRECISION'     =>      1,
131               );
132
133       This method will die on error or return success.
134
135       This constructor accepts only 2 options.
136
137       "ALIAS"
138           This will set the alias SimpleLog uses in the POE Kernel.  This
139           will default TO "SimpleLog"
140
141       "PRECISION"
142           If this value is defined, SimpleLog will use Time::HiRes to get the
143           timestamps.
144
145       Events
146
147       SimpleLog is so simple, there are only 5 events available.
148
149       "REGISTER"
150                   This event accepts 3 arguments:
151
152                   LOGNAME ->      The name of the log to register for
153                   SESSION ->      The session where the log will go ( Also accepts Session ID's )
154                   EVENT   ->      The event that will be called
155
156                   The act of registering for a log can fail if one of the above values are undefined.
157
158                   If the LOGNAME eq 'ALL', then that registration will get *ALL* the logs SimpleLog processes
159
160                   There is no such thing as an "non-existant" log, registration just makes sure that you will get this log *WHEN* it comes.
161
162                   Events that receive the logs will get these:
163                           ARG0 -> CALLER_FILE
164                           ARG1 -> CALLER_LINE
165                           ARG2 -> Time::HiRes [ gettimeofday ] or time()
166                           ARG3 -> LOGNAME
167                           ARG4 -> Message
168
169                   Here's an example:
170
171                   $_[KERNEL]->post( 'SimpleLog', 'REGISTER',
172                           LOGNAME => 'CONNECTION',
173                           SESSION => $_[SESSION],
174                           EVENT => 'GotLOG',
175                   );
176
177                   This is the subroutine that will get the GotLOG event
178                   sub gotlog {
179                           # Get the arguments
180                           my( $file, $line, $time, $name, $message ) = @_[ ARG0 .. ARG4 ];
181
182                           # Assumes PRECISION is undef ( regular time() )
183                           print STDERR "$time ${name}-> $file : $line = $message\n";
184
185                           # PRECISION = true ( Time::HiRes )
186                           print STDERR "$time->[0].$time->[1] ${name}-> $file : $line = $message\n";
187                   }
188
189       "UNREGISTER"
190                   This event accepts 3 arguments:
191
192                   LOGNAME ->      The name of the log to unregister for
193                   SESSION ->      The session where the log will go ( Also accepts Session ID's )
194                   EVENT   ->      The event that will be called
195
196                   Unregistering for a log will fail if the exact 3 arguments were not found in our registry.
197
198                   The act of unregistering will mean the session/event no longer receives any log messages.
199
200                   NOTE: There might be some logs still traversing POE's queue...
201
202                   Here's an example:
203
204                   $_[KERNEL]->post( 'SimpleLog', 'UNREGISTER',
205                           LOGNAME => 'CONNECTION',
206                           SESSION => $_[SESSION]->ID,
207                           EVENT => 'GotLOG',
208                   );
209
210       "UNREGISTERSESSION"
211                   This event accepts 1 argument:
212
213                   ARG0    ->      The session ( Also accepts Session ID's )
214
215                   This is useful for removing all the registrations for a specific session.
216
217                   Here's an example:
218
219                   $_[KERNEL]->post( 'SimpleLog', 'UNREGISTERSESSION', $_[SESSION] );
220
221       "LOG"
222                   This event accepts 2 arguments:
223
224                   ARG0    ->      Logname
225                   ARG1    ->      Message
226
227                   This is where SimpleLog does it's work, sending the log to the proper events.
228
229                   The Logname can be anything, if there is no events registered for it, the message will simply be discarded.
230
231                   Here's an example:
232
233                   $_[KERNEL]->post( 'SimpleLog', 'LOG', 'CONNECTION', 'A Client just connected!' );
234
235       "SHUTDOWN"
236                   This is the generic SHUTDOWN routine, it will stop all logging.
237
238                   Here's an example:
239
240                   $_[KERNEL]->post( 'SimpleLog', 'SHUTDOWN' );
241
242       SimpleLog Notes
243
244       This module is very picky about capitalization!
245
246       All of the options are uppercase, to avoid confusion.
247
248       You can enable debugging mode by doing this:
249
250               sub POE::Component::SimpleLog::DEBUG () { 1 }
251               use POE::Component::SimpleLog;
252
253       EXPORT
254
255       Nothing.
256

SEE ALSO

258       POE
259

AUTHOR

261       Apocalypse <apocal@cpan.org>
262

264       Copyright 2005 by Apocalypse
265
266       This library is free software; you can redistribute it and/or modify it
267       under the same terms as Perl itself.
268
269
270
271perl v5.8.8                       2006-09-18      POE::Component::SimpleLog(3)
Impressum