root/Log-Dispatch-Config/trunk/README

Revision 361 (checked in by miyagawa, 19 years ago)

update doc

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1 NAME
2     Log::Dispatch::Config - Log4j for Perl
3
4 SYNOPSIS
5       use Log::Dispatch::Config;
6       Log::Dispatch::Config->configure('/path/to/config');
7
8       my $dispatcher = Log::Dispatch::Config->instance;
9
10       # or the same (may be deprecated)
11       my $dispatcher = Log::Dispatch->instance;
12
13 DESCRIPTION
14     Log::Dispatch::Config is a subclass of Log::Dispatch and provides a way
15     to configure Log::Dispatch object with configulation file (in AppConfig
16     format). I mean, this is log4j for Perl, not with all API compatibility
17     though.
18
19 METHOD
20     This module has a class method `configure' which parses config file for
21     later creation of the Log::Dispatch::Config singleton instance. (Actual
22     construction of the object is done in the first `instance' call).
23
24     So, what you should do is call `configure' method once in somewhere
25     (like `startup.pl' in mod_perl), then you can get configured dispatcher
26     instance via `Log::Dispatch::Config->instance'.
27
28     Formerly, `configure' method declares `instance' method in Log::Dispatch
29     namespace. Now it inherits from Log::Dispatch, so the namespace
30     pollution is not necessary. Currrent version still defines one-liner
31     shortcut:
32
33       sub Log::Dispatch::instance { Log::Dispatch::Config->instance }
34
35     so still you can call `Log::Dispatch->instance', if you prefer, or for
36     backward compatibility.
37
38 CONFIGURATION
39     Here is an example of the config file:
40
41       dispatchers = file screen
42
43       file.class = Log::Dispatch::File
44       file.min_level = debug
45       file.filename = /path/to/log
46       file.mode = append
47       file.format = [%d] [%p] %m at %F line %L%n
48
49       screen.class = Log::Dispatch::Screen
50       screen.min_level = info
51       screen.stderr = 1
52       screen.format = %m
53
54     Config file is parsed with AppConfig module, see the AppConfig manpage
55     when you face configuration parsing error.
56
57   GLOBAL PARAMETERS
58
59     dispatchers
60           dispatchers = file screen
61
62         `dispatchers' defines logger names, which will be splitted by
63         spaces. If this parameter is unset, no logging is done.
64
65     format
66           format = [%d] [%p] %m at %F line %L%n
67           format = [${datetime}] [${prioity}] ${message} at ${filename} line ${line}\n
68
69         `format' defines log format. `%X' style and `${XXX}' style are both
70         supported. Possible conversions format are
71
72           %d ${datetime}        datetime string
73           %p ${priority}        priority (debug, info, warning ...)
74           %m ${message}         message string
75           %F ${filename}        filename
76           %L ${line}            line number
77           %P ${package}         package
78           %n                    newline (\n)
79
80         `format' defined here would apply to all the log messages to
81         dispatchers. This parameter is optional.
82
83   PARAMETERS FOR EACH DISPATCHER
84
85     Parameters for each dispatcher should be prefixed with "name.", where
86     "name" is the name of each one, defined in global `dispatchers'
87     parameter.
88
89     class
90           screen.class = Log::Dispatch::Screen
91
92         `class' defines class name of Log::Dispatch subclasses. This
93         parameter is essential.
94
95     format
96           screen.format = -- %m --
97
98         `format' defines log format which would be applied only to the
99         dispatcher. Note that if you define global `format' also, `%m' is
100         double formated (first global one, next each dispatcher one). This
101         parameter is optional.
102
103     (others)
104           screen.min_level = info
105           screen.stderr = 1
106
107         Other parameters would be passed to the each dispatcher
108         construction. See Log::Dispatch::* manpage for the details.
109
110 SINGLETON
111     Declared `instance' method would make `Log::Dispatch::Config' class
112     singleton, so multiple calls of `instance' will all result in returning
113     same object.
114
115       my $one = Log::Dispatch::Config->instance;
116       my $two = Log::Dispatch::Config->instance; # same as $one
117
118     See GoF Design Pattern book for Singleton Pattern.
119
120     But in practice, in persistent environment like mod_perl, Singleton
121     instance is not so useful. Log::Dispatch::Config defines `instance'
122     method so that the object reloads itself when configuration file is
123     modified since its last object creation time.
124
125 TODO
126     *   LogLevel configuration depending on caller package like log4j?
127
128 AUTHOR
129     Tatsuhiko Miyagawa <miyagawa@bulknews.net>
130
131     This library is free software; you can redistribute it and/or modify it
132     under the same terms as Perl itself.
133
134 SEE ALSO
135     the Log::Dispatch manpage, the AppConfig manpage
136
Note: See TracBrowser for help on using the browser.