.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Log::Dispatchouli::Global 3pm" .TH Log::Dispatchouli::Global 3pm "2023-09-03" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Log::Dispatchouli::Global \- a system for sharing a global, dynamically\-scoped logger .SH "VERSION" .IX Header "VERSION" version 3.007 .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBWarning\fR: This interface is still experimental. .PP Log::Dispatchouli::Global is a framework for a global logger object. In your top-level programs that are actually executed, you'd add something like this: .PP .Vb 7 \& use Log::Dispatchouli::Global \*(Aq$Logger\*(Aq => { \& init => { \& ident => \*(AqMy::Daemon\*(Aq, \& facility => \*(Aqlocal2\*(Aq, \& to_stdout => 1, \& }, \& }; .Ve .PP This will import a \f(CW$Logger\fR into your program, and more importantly will initialize it with a new Log::Dispatchouli object created by passing the value for the \f(CW\*(C`init\*(C'\fR parameter to Log::Dispatchouli's \f(CW\*(C`new\*(C'\fR method. .PP Much of the rest of your program, across various libraries, can then just use this: .PP .Vb 1 \& use Log::Dispatchouli::Global \*(Aq$Logger\*(Aq; \& \& sub whatever { \& ... \& \& $Logger\->log("about to do something"); \& \& local $Logger = $Logger\->proxy({ proxy_prefix => "whatever: " }); \& \& for (@things) { \& $Logger\->log([ "doing thing %s", $_ ]); \& ... \& } \& } .Ve .PP This eliminates the need to pass around what is effectively a global, while still allowing it to be specialized within certain contexts of your program. .PP \&\fBWarning!\fR Although you \fIcould\fR just use Log::Dispatchouli::Global as your shared logging library, you almost \fIcertainly\fR want to write a subclass that will only be shared amongst your application's classes. Log::Dispatchouli::Global is meant to be subclassed and shared only within controlled systems. Remember, \fIsharing your state with code you don't control is dangerous\fR. .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "USING" .IX Header "USING" In general, you will either be using a Log::Dispatchouli::Global class to get a \f(CW$Logger\fR or to initialize it (and then get \f(CW$Logger\fR). These are both demonstrated above. Also, when importing \f(CW$Logger\fR you may request it be imported under a different name: .PP .Vb 1 \& use Log::Dispatchouli::Global \*(Aq$Logger\*(Aq => { \-as => \*(AqL\*(Aq }; \& \& $L\->log( ... ); .Ve .PP There is only one class method that you are likely to use: \f(CW\*(C`current_logger\*(C'\fR. This provides the value of the shared logger from the caller's context, initializing it to a default if needed. Even this method is unlikely to be required frequently, but it \fIdoes\fR allow users to \fIsee\fR \f(CW$Logger\fR without importing it. .SH "SUBCLASSING" .IX Header "SUBCLASSING" Before using Log::Dispatchouli::Global in your application, you should subclass it. When you subclass it, you should provide the following methods: .SS "logger_globref" .IX Subsection "logger_globref" This method should return a globref in which the shared logger will be stored. Subclasses will be in their own package, so barring any need for cleverness, every implementation of this method can look like the following: .PP .Vb 1 \& sub logger_globref { no warnings \*(Aqonce\*(Aq; return \e*Logger } .Ve .SS "default_logger" .IX Subsection "default_logger" If no logger has been initialized, but something tries to log, it gets the default logger, created by calling this method. .PP The default implementation calls \f(CW\*(C`new\*(C'\fR on the \f(CW\*(C`default_logger_class\*(C'\fR with the result of \f(CW\*(C`default_logger_args\*(C'\fR as the arguments. .SS "default_logger_class" .IX Subsection "default_logger_class" This returns the class on which \f(CW\*(C`new\*(C'\fR will be called when initializing a logger, either from the \f(CW\*(C`init\*(C'\fR argument when importing or the default logger. .PP Its default value is Log::Dispatchouli. .SS "default_logger_args" .IX Subsection "default_logger_args" If no logger has been initialized, but something tries to log, it gets the default logger, created by calling \f(CW\*(C`new\*(C'\fR on the \f(CW\*(C`default_logger_class\*(C'\fR and passing the results of calling this method. .PP Its default return value creates a sink, so that anything logged without an initialized logger is lost. .SS "default_logger_ref" .IX Subsection "default_logger_ref" This method returns a scalar reference in which the cached default value is stored for comparison. This is used when someone tries to \f(CW\*(C`init\*(C'\fR the global. When someone tries to initialize the global logger, and it's already set, then: .IP "\(bu" 4 if the current value is the same as the default, the new value is set .IP "\(bu" 4 if the current value is \fInot\fR the same as the default, we die .PP Since you want the default to be isolated to your application's logger, the default behavior is default loggers are associated with the glob reference to which the default might be assigned. It is unlikely that you will need to interact with this method. .SH "COOKBOOK" .IX Header "COOKBOOK" .SS "Common Logger Recipes" .IX Subsection "Common Logger Recipes" Say you often use the same configuration for one kind of program, like automated tests. You've already written your own subclass to get your own storage and defaults, maybe \f(CW\*(C`MyApp::Logger\*(C'\fR. .PP You can't just write a subclass with a different default, because if another class using the same global has set the global with \fIits\fR default, yours won't be honored. You don't just want this new value to be the default, you want it to be \fIthe\fR logger. What you want to do in this case is to initialize your logger normally, then reexport it, like this: .PP .Vb 2 \& package MyApp::Logger::Test; \& use parent \*(AqMyApp::Logger\*(Aq; \& \& use MyApp::Logger \*(Aq$Logger\*(Aq => { \& init => { \& ident => "Tester($0)", \& to_self => 1, \& facility => undef, \& }, \& }; .Ve .PP This will set up the logger and re-export it, and will properly die if anything else attempts to initialize the logger to something else. .SH "AUTHOR" .IX Header "AUTHOR" Ricardo \s-1SIGNES\s0 .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2023 by Ricardo \s-1SIGNES.\s0 .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.