Project

General

Profile

Bug #6738 ยป lib_logger_rdoc_typos.patch

stomar (Marcus Stollsteimer), 07/16/2012 02:19 AM

View differences:

lib/logger.rb (Arbeitskopie)
18 18
#
19 19
# The messages have associated levels, such as +INFO+ or +ERROR+ that indicate
20 20
# their importance.  You can then give the Logger a level, and only messages
21
# at that level of higher will be printed.
21
# at that level or higher will be printed.
22 22
#
23 23
# The levels are:
24 24
#
25
# +FATAL+:: an unhandleable error that results in a program crash
26
# +ERROR+:: a handleable error condition
27
# +WARN+::  a warning
28
# +INFO+::  generic (useful) information about system operation
29
# +DEBUG+:: low-level information for developers
25
# +UNKNOWN+:: An unknown message that should always be logged.
26
# +FATAL+:: An unhandleable error that results in a program crash.
27
# +ERROR+:: A handleable error condition.
28
# +WARN+::  A warning.
29
# +INFO+::  Generic (useful) information about system operation.
30
# +DEBUG+:: Low-level information for developers.
30 31
#
31 32
# For instance, in a production system, you may have your Logger set to
32
# +INFO+ or even +WARN+
33
# +INFO+ or even +WARN+.
33 34
# When you are developing the system, however, you probably
34 35
# want to know about the program's internal state, and would set the Logger to
35 36
# +DEBUG+.
......
51 52
#
52 53
# === Example
53 54
#
54
# This creates a logger to the standard output stream, with a level of +WARN+
55
# This creates a Logger to the standard output stream, with a level of +WARN+:
55 56
#
56 57
#   log = Logger.new(STDOUT)
57 58
#   log.level = Logger::WARN
58 59
#
59
#   log.debug("Created logger")
60
#   log.info("Program started")
61
#   log.warn("Nothing to do!")
60
#   log.debug('Created logger')
61
#   log.info('Program started')
62
#   log.warn('Nothing to do!')
62 63
#
63 64
#   begin
64 65
#     File.each_line(path) do |line|
......
67 68
#       end
68 69
#     end
69 70
#   rescue => err
70
#     log.fatal("Caught exception; exiting")
71
#     log.fatal('Caught exception; exiting')
71 72
#     log.fatal(err)
72 73
#   end
73 74
#
......
103 104
#
104 105
#      file = File.open('foo.log', File::WRONLY | File::APPEND)
105 106
#      # To create new (and to remove old) logfile, add File::CREAT like;
106
#      #   file = open('foo.log', File::WRONLY | File::APPEND | File::CREAT)
107
#      #   file = File.open('foo.log', File::WRONLY | File::APPEND | File::CREAT)
107 108
#      logger = Logger.new(file)
108 109
#
109
# 4. Create a logger which ages logfile once it reaches a certain size.  Leave
110
#    10 "old log files" and each file is about 1,024,000 bytes.
110
# 4. Create a logger which ages the logfile once it reaches a certain size.
111
#    Leave 10 "old" log files where each file is about 1,024,000 bytes.
111 112
#
112 113
#      logger = Logger.new('foo.log', 10, 1024000)
113 114
#
114
# 5. Create a logger which ages logfile daily/weekly/monthly.
115
# 5. Create a logger which ages the logfile daily/weekly/monthly.
115 116
#
116 117
#      logger = Logger.new('foo.log', 'daily')
117 118
#      logger = Logger.new('foo.log', 'weekly')
......
124 125
# +debug+.  +add+ is used below to log a message of an arbitrary (perhaps
125 126
# dynamic) level.
126 127
#
127
# 1. Message in block.
128
# 1. Message in a block.
128 129
#
129 130
#      logger.fatal { "Argument 'foo' not given." }
130 131
#
131 132
# 2. Message as a string.
132 133
#
133
#      logger.error "Argument #{ @foo } mismatch."
134
#      logger.error "Argument #{@foo} mismatch."
134 135
#
135 136
# 3. With progname.
136 137
#
137
#      logger.info('initialize') { "Initializing..." }
138
#      logger.info('initialize') { 'Initializing...' }
138 139
#
139 140
# 4. With severity.
140 141
#
......
144 145
# but to delay their evaluation until and unless the message is
145 146
# logged.  For example, if we have the following:
146 147
#
147
#     logger.debug { "This is a " + potentially + " expensive operation" }
148
#     logger.debug { 'This is a ' + potentially + ' expensive operation' }
148 149
#
149 150
# If the logger's level is +INFO+ or higher, no debug messages will be logged,
150 151
# and the entire block will not even be evaluated.  Compare to this:
151 152
#
152
#     logger.debug("This is a " + potentially + " expensive operation")
153
#     logger.debug('This is a ' + potentially + ' expensive operation')
153 154
#
154 155
# Here, the string concatenation is done every time, even if the log
155 156
# level is not set to show the debug message.
......
168 169
#
169 170
#      logger.level = Logger::INFO
170 171
#
171
#      DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN
172
#      # DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN
172 173
#
173 174
#
174 175
# == Format
......
177 178
# default.  The default format and a sample are shown below:
178 179
#
179 180
# Log format:
180
#   SeverityID, [Date Time mSec #pid] SeverityLabel -- ProgName: message
181
#   SeverityID, [Date Time uSec #pid] SeverityLabel -- ProgName: message
181 182
#
182 183
# Log sample:
183 184
#   I, [Wed Mar 03 02:34:24 JST 1999 895701 #19074]  INFO -- Main: info.
184 185
#
185
# You may change the date and time format via #datetime_format=
186
# You may change the date and time format via #datetime_format=.
186 187
#
187
#   logger.datetime_format = "%Y-%m-%d %H:%M:%S"
188
#   logger.datetime_format = '%Y-%m-%d %H:%M:%S'
188 189
#         # e.g. "2004-01-03 00:54:26"
189 190
#
190
# Or, you may change the overall format with #formatter= method.
191
# Or, you may change the overall format via the #formatter= method.
191 192
#
192 193
#   logger.formatter = proc do |severity, datetime, progname, msg|
193 194
#     "#{datetime}: #{msg}\n"
194 195
#   end
195
#   # e.g. "Thu Sep 22 08:51:08 GMT+9:00 2005: hello world"
196
#   # e.g. 'Thu Sep 22 08:51:08 GMT+9:00 2005: hello world'
196 197
#
197 198
class Logger
198 199
  VERSION = "1.2.7"
......
213 214

  
214 215
  # Logging severity.
215 216
  module Severity
216
    # Low-level information, mostly for developers
217
    # Low-level information, mostly for developers.
217 218
    DEBUG = 0
218
    # generic, useful information about system operation
219
    # Generic (useful) information about system operation.
219 220
    INFO = 1
220
    # a warning
221
    # A warning.
221 222
    WARN = 2
222
    # a handleable error condition
223
    # A handleable error condition.
223 224
    ERROR = 3
224
    # an unhandleable error that results in a program crash
225
    # An unhandleable error that results in a program crash.
225 226
    FATAL = 4
226
    # an unknown message that should always be logged
227
    # An unknown message that should always be logged.
227 228
    UNKNOWN = 5
228 229
  end
229 230
  include Severity
......
231 232
  # Logging severity threshold (e.g. <tt>Logger::INFO</tt>).
232 233
  attr_accessor :level
233 234

  
234
  # program name to include in log messages.
235
  # Program name to include in log messages.
235 236
  attr_accessor :progname
236 237

  
237 238
  # Set date-time format.
......
249 250
  # Logging formatter, as a +Proc+ that will take four arguments and
250 251
  # return the formatted message. The arguments are:
251 252
  #
252
  # +severity+:: The Severity of the log message
253
  # +time+:: A Time instance representing when the message was logged
254
  # +progname+:: The #progname configured, or passed to the logger method
253
  # +severity+:: The Severity of the log message.
254
  # +time+:: A Time instance representing when the message was logged.
255
  # +progname+:: The #progname configured, or passed to the logger method.
255 256
  # +msg+:: The _Object_ the user passed to the log message; not necessarily a
256 257
  #         String.
257 258
  #
......
338 339
  #
339 340
  # +true+ if successful, +false+ otherwise.
340 341
  #
341
  # When the given severity is not high enough (for this particular logger), log
342
  # no message, and return +true+.
342
  # When the given severity is not high enough (for this particular logger),
343
  # log no message, and return +true+.
343 344
  #
344 345
  # === Description
345 346
  #
......
358 359
  #
359 360
  # * Logfile is not locked.
360 361
  # * Append open does not need to lock file.
361
  # * If the OS which supports multi I/O, records possibly be mixed.
362
  # * If the OS supports multi I/O, records possibly may be mixed.
362 363
  #
363 364
  def add(severity, message = nil, progname = nil, &block)
364 365
    severity ||= UNKNOWN
......
402 403
  #
403 404
  # :call-seq:
404 405
  #   info(message)
405
  #   info(progname,&block)
406
  #   info(progname, &block)
406 407
  #
407 408
  # Log an +INFO+ message.
408 409
  #
409
  # +message+:: the message to log; does not need to be a String
410
  # +progname+:: in the block form, this is the #progname to use in the
411
  #              the log message.  The default can be set with #progname=
412
  # <tt>&block</tt>:: evaluates to the message to log.  This is not evaluated
410
  # +message+:: The message to log; does not need to be a String.
411
  # +progname+:: In the block form, this is the #progname to use in the
412
  #              log message.  The default can be set with #progname=.
413
  # <tt>&block</tt>:: Evaluates to the message to log.  This is not evaluated
413 414
  #                   unless the logger's level is sufficient
414 415
  #                   to log the message.  This allows you to create
415 416
  #                   potentially expensive logging messages that are
......
417 418
  #
418 419
  # === Examples
419 420
  #
420
  #   logger.info("MainApp") { "Received connection from #{ip}" }
421
  #   logger.info('MainApp') { "Received connection from #{ip}" }
421 422
  #   # ...
422
  #   logger.info "Waiting for input from user"
423
  #   logger.info 'Waiting for input from user'
423 424
  #   # ...
424 425
  #   logger.info { "User typed #{input}" }
425 426
  #
......
463 464

  
464 465
  #
465 466
  # Log an +UNKNOWN+ message.  This will be printed no matter what the logger's
466
  # level.
467
  # level is.
467 468
  #
468 469
  # See #info for more information.
469 470
  #
......
480 481

  
481 482
private
482 483

  
483
  # Severity label for logging. (max 5 char)
484
  # Severity label for logging (max 5 chars).
484 485
  SEV_LABEL = %w(DEBUG INFO WARN ERROR FATAL ANY)
485 486

  
486 487
  def format_severity(severity)
......
492 493
  end
493 494

  
494 495

  
495
  # Default formatter for log messages
496
  # Default formatter for log messages.
496 497
  class Formatter
497 498
    Format = "%s, [%s#%d] %5s -- %s: %s\n"
498 499

  
......
678 679
  #
679 680
  # == Description
680 681
  #
681
  # Application -- Add logging support to your application.
682
  # Application --- Add logging support to your application.
682 683
  #
683 684
  # == Usage
684 685
  #
685 686
  # 1. Define your application class as a sub-class of this class.
686
  # 2. Override 'run' method in your class to do many things.
687
  # 3. Instantiate it and invoke 'start'.
687
  # 2. Override the +run+ method in your class to do many things.
688
  # 3. Instantiate it and invoke #start.
688 689
  #
689 690
  # == Example
690 691
  #