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

SEE ALSO

255       POE
256

AUTHOR

258       Apocalypse <apocal@cpan.org>
259

261       Copyright 2008 by Apocalypse
262
263       This library is free software; you can redistribute it and/or modify it
264       under the same terms as Perl itself.
265
266
267
268perl v5.28.0                      2008-06-11      POE::Component::SimpleLog(3)
Impressum