local-lib5/man/man3/Catalyst::Log.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Catalyst::Log 3"
 132 .TH Catalyst::Log 3 "2009-06-17" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Catalyst::Log \- Catalyst Log Class
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 6
 138 \&    $log = $c\->log;
 139 \&    $log\->debug($message);
 140 \&    $log\->info($message);
 141 \&    $log\->warn($message);
 142 \&    $log\->error($message);
 143 \&    $log\->fatal($message);
 144 .Ve
 145 .PP
 146 .Vb 3
 147 \&    if ( $log\->is_debug ) {
 148 \&         # expensive debugging
 149 \&    }
 150 .Ve
 151 .PP
 152 See Catalyst.
 153 .SH "DESCRIPTION"
 154 .IX Header "DESCRIPTION"
 155 This module provides the default, simple logging functionality for Catalyst.
 156 If you want something different set \f(CW\*(C`$c\->log\*(C'\fR in your application module,
 157 e.g.:
 158 .PP
 159 .Vb 1
 160 \&    $c\->log( MyLogger\->new );
 161 .Ve
 162 .PP
 163 Your logging object is expected to provide the interface described here.
 164 Good alternatives to consider are Log::Log4Perl and Log::Dispatch.
 165 .PP
 166 If you want to be able to log arbitrary warnings, you can do something along
 167 the lines of
 168 .PP
 169 .Vb 1
 170 \&    $SIG{__WARN__} = sub { MyApp\->log\->warn(@_); };
 171 .Ve
 172 .PP
 173 however this is (a) global, (b) hairy and (c) may have unexpected side effects.
 174 Don't say we didn't warn you.
 175 .SH "LOG LEVELS"
 176 .IX Header "LOG LEVELS"
 177 .Sh "debug"
 178 .IX Subsection "debug"
 179 .Vb 2
 180 \&    $log\->is_debug;
 181 \&    $log\->debug($message);
 182 .Ve
 183 .Sh "info"
 184 .IX Subsection "info"
 185 .Vb 2
 186 \&    $log\->is_info;
 187 \&    $log\->info($message);
 188 .Ve
 189 .Sh "warn"
 190 .IX Subsection "warn"
 191 .Vb 2
 192 \&    $log\->is_warn;
 193 \&    $log\->warn($message);
 194 .Ve
 195 .Sh "error"
 196 .IX Subsection "error"
 197 .Vb 2
 198 \&    $log\->is_error;
 199 \&    $log\->error($message);
 200 .Ve
 201 .Sh "fatal"
 202 .IX Subsection "fatal"
 203 .Vb 2
 204 \&    $log\->is_fatal;
 205 \&    $log\->fatal($message);
 206 .Ve
 207 .SH "METHODS"
 208 .IX Header "METHODS"
 209 .Sh "new"
 210 .IX Subsection "new"
 211 Constructor. Defaults to enable all levels unless levels are provided in
 212 arguments.
 213 .PP
 214 .Vb 2
 215 \&    $log = Catalyst::Log\->new;
 216 \&    $log = Catalyst::Log\->new( 'warn', 'error' );
 217 .Ve
 218 .Sh "level"
 219 .IX Subsection "level"
 220 Contains a bitmask of the currently set log levels.
 221 .Sh "levels"
 222 .IX Subsection "levels"
 223 Set log levels
 224 .PP
 225 .Vb 1
 226 \&    $log\->levels( 'warn', 'error', 'fatal' );
 227 .Ve
 228 .Sh "enable"
 229 .IX Subsection "enable"
 230 Enable log levels
 231 .PP
 232 .Vb 1
 233 \&    $log\->enable( 'warn', 'error' );
 234 .Ve
 235 .Sh "disable"
 236 .IX Subsection "disable"
 237 Disable log levels
 238 .PP
 239 .Vb 1
 240 \&    $log\->disable( 'warn', 'error' );
 241 .Ve
 242 .Sh "is_debug"
 243 .IX Subsection "is_debug"
 244 .Sh "is_error"
 245 .IX Subsection "is_error"
 246 .Sh "is_fatal"
 247 .IX Subsection "is_fatal"
 248 .Sh "is_info"
 249 .IX Subsection "is_info"
 250 .Sh "is_warn"
 251 .IX Subsection "is_warn"
 252 Is the log level active?
 253 .Sh "abort"
 254 .IX Subsection "abort"
 255 Should Catalyst emit logs for this request? Will be reset at the end of
 256 each request.
 257 .PP
 258 *NOTE* This method is not compatible with other log apis, so if you plan
 259 to use Log4Perl or another logger, you should call it like this:
 260 .PP
 261 .Vb 1
 262 \&    $c\->log\->abort(1) if $c\->log\->can('abort');
 263 .Ve
 264 .Sh "_send_to_log"
 265 .IX Subsection "_send_to_log"
 266 .Vb 1
 267 \& $log\->_send_to_log( @messages );
 268 .Ve
 269 .PP
 270 This protected method is what actually sends the log information to \s-1STDERR\s0.
 271 You may subclass this module and override this method to get finer control
 272 over the log output.
 273 .Sh "meta"
 274 .IX Subsection "meta"
 275 .SH "SEE ALSO"
 276 .IX Header "SEE ALSO"
 277 Catalyst.
 278 .SH "AUTHORS"
 279 .IX Header "AUTHORS"
 280 Catalyst Contributors, see Catalyst.pm
 281 .SH "COPYRIGHT"
 282 .IX Header "COPYRIGHT"
 283 This library is free software. You can redistribute it and/or modify
 284 it under the same terms as Perl itself.