1Log::Dispatchouli::GlobUasle(r3)Contributed Perl DocumenLtoagt:i:oDnispatchouli::Global(3)
2
3
4

NAME

6       Log::Dispatchouli::Global - a system for sharing a global,
7       dynamically-scoped logger
8

VERSION

10       version 3.006
11

DESCRIPTION

13       Warning: This interface is still experimental.
14
15       Log::Dispatchouli::Global is a framework for a global logger object. In
16       your top-level programs that are actually executed, you'd add something
17       like this:
18
19         use Log::Dispatchouli::Global '$Logger' => {
20           init => {
21             ident     => 'My::Daemon',
22             facility  => 'local2',
23             to_stdout => 1,
24           },
25         };
26
27       This will import a $Logger into your program, and more importantly will
28       initialize it with a new Log::Dispatchouli object created by passing
29       the value for the "init" parameter to Log::Dispatchouli's "new" method.
30
31       Much of the rest of your program, across various libraries, can then
32       just use this:
33
34         use Log::Dispatchouli::Global '$Logger';
35
36         sub whatever {
37           ...
38
39           $Logger->log("about to do something");
40
41           local $Logger = $Logger->proxy({ proxy_prefix => "whatever: " });
42
43           for (@things) {
44             $Logger->log([ "doing thing %s", $_ ]);
45             ...
46           }
47         }
48
49       This eliminates the need to pass around what is effectively a global,
50       while still allowing it to be specialized within certain contexts of
51       your program.
52
53       Warning!  Although you could just use Log::Dispatchouli::Global as your
54       shared logging library, you almost certainly want to write a subclass
55       that will only be shared amongst your application's classes.
56       Log::Dispatchouli::Global is meant to be subclassed and shared only
57       within controlled systems.  Remember, sharing your state with code you
58       don't control is dangerous.
59

PERL VERSION

61       This library should run on perls released even a long time ago.  It
62       should work on any version of perl released in the last five years.
63
64       Although it may work on older versions of perl, no guarantee is made
65       that the minimum required version will not be increased.  The version
66       may be increased for any reason, and there is no promise that patches
67       will be accepted to lower the minimum required perl.
68

USING

70       In general, you will either be using a Log::Dispatchouli::Global class
71       to get a $Logger or to initialize it (and then get $Logger).  These are
72       both demonstrated above.  Also, when importing $Logger you may request
73       it be imported under a different name:
74
75         use Log::Dispatchouli::Global '$Logger' => { -as => 'L' };
76
77         $L->log( ... );
78
79       There is only one class method that you are likely to use:
80       "current_logger".  This provides the value of the shared logger from
81       the caller's context, initializing it to a default if needed.  Even
82       this method is unlikely to be required frequently, but it does allow
83       users to see $Logger without importing it.
84

SUBCLASSING

86       Before using Log::Dispatchouli::Global in your application, you should
87       subclass it.  When you subclass it, you should provide the following
88       methods:
89
90   logger_globref
91       This method should return a globref in which the shared logger will be
92       stored.  Subclasses will be in their own package, so barring any need
93       for cleverness, every implementation of this method can look like the
94       following:
95
96         sub logger_globref { no warnings 'once'; return \*Logger }
97
98   default_logger
99       If no logger has been initialized, but something tries to log, it gets
100       the default logger, created by calling this method.
101
102       The default implementation calls "new" on the "default_logger_class"
103       with the result of "default_logger_args" as the arguments.
104
105   default_logger_class
106       This returns the class on which "new" will be called when initializing
107       a logger, either from the "init" argument when importing or the default
108       logger.
109
110       Its default value is Log::Dispatchouli.
111
112   default_logger_args
113       If no logger has been initialized, but something tries to log, it gets
114       the default logger, created by calling "new" on the
115       "default_logger_class" and passing the results of calling this method.
116
117       Its default return value creates a sink, so that anything logged
118       without an initialized logger is lost.
119
120   default_logger_ref
121       This method returns a scalar reference in which the cached default
122       value is stored for comparison.  This is used when someone tries to
123       "init" the global.  When someone tries to initialize the global logger,
124       and it's already set, then:
125
126       •   if the current value is the same as the default, the new value is
127           set
128
129       •   if the current value is not the same as the default, we die
130
131       Since you want the default to be isolated to your application's logger,
132       the default behavior is default loggers are associated with the glob
133       reference to which the default might be assigned.  It is unlikely that
134       you will need to interact with this method.
135

COOKBOOK

137   Common Logger Recipes
138       Say you often use the same configuration for one kind of program, like
139       automated tests.  You've already written your own subclass to get your
140       own storage and defaults, maybe "MyApp::Logger".
141
142       You can't just write a subclass with a different default, because if
143       another class using the same global has set the global with its
144       default, yours won't be honored.  You don't just want this new value to
145       be the default, you want it to be the logger.  What you want to do in
146       this case is to initialize your logger normally, then reexport it, like
147       this:
148
149         package MyApp::Logger::Test;
150         use parent 'MyApp::Logger';
151
152         use MyApp::Logger '$Logger' => {
153           init => {
154             ident    => "Tester($0)",
155             to_self  => 1,
156             facility => undef,
157           },
158         };
159
160       This will set up the logger and re-export it, and will properly die if
161       anything else attempts to initialize the logger to something else.
162

AUTHOR

164       Ricardo SIGNES <cpan@semiotic.systems>
165
167       This software is copyright (c) 2023 by Ricardo SIGNES.
168
169       This is free software; you can redistribute it and/or modify it under
170       the same terms as the Perl 5 programming language system itself.
171
172
173
174perl v5.38.0                      2023-08-23      Log::Dispatchouli::Global(3)
Impressum