logger 1.5.1 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55dfc9db8783f8e0bce997c8f6c162b10e4602bcbe968354bb8f4a0f3a6c1764
-  data.tar.gz: '08e336951520fc4cc5ab2553ec563509a769a20fb461f47d4e0f2b561745783e'
+  metadata.gz: b70d947261ec2e9d94145b13c4831a54fa6c49864aa208e63d4151fd494de443
+  data.tar.gz: cda09e37794e00a0c56e66e7ade628f2acdf10312af790d0e2fd1d5c32bf30f1
 SHA512:
-  metadata.gz: 001ea8a77429868cfe3e438b41a1d100ee0d5c1bba2d74685fd031add97efae2bb0f31b4d889a84a954f01dfcc96624512e488bb08da4703e33bc38432c3e606
-  data.tar.gz: 747d62f6bf313cb3a120afcae4179feb47bbe816d40895793ccc719ca87bb4c1798c0cb72ac39862dbcbacc6468e59606d2d5600e395607562f0c0a58bbf3f6f
+  metadata.gz: b26008735ad28617a11e8db99db0c5aa5abd5253f3950182da45d342d2bf360d6ef48da6cf1a87c11282ff242f59ee4b731093cb6e738b0464f2a78ceb4df7d1
+  data.tar.gz: 5aba8135b1e8322f1038b5bdff1d5ff7472edc3aa71a88f8798e944ea0fb1fad4884c2e6281c9e0691ded78fc9cf0ae75cf6a1d56b3fa23c33fc5e90b30aaa4e

data/lib/logger/errors.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# not used after 1.2.7. just for compat.
 class Logger
+  # not used after 1.2.7. just for compat.
   class Error < RuntimeError # :nodoc:
   end
   class ShiftingError < Error # :nodoc:

data/lib/logger/formatter.rb

@@ -13,7 +13,7 @@ class Logger
     end
 
     def call(severity, time, progname, msg)
-      Format % [severity[0..0], format_datetime(time), Process.pid, severity, progname,
+      Format % [severity[0, 1], format_datetime(time), Process.pid, severity, progname,
         msg2str(msg)]
     end
 

data/lib/logger/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Logger
-  VERSION = "1.5.1"
+  VERSION = "1.5.2"
 end

data/lib/logger.rb

@@ -19,216 +19,353 @@ require_relative 'logger/log_device'
 require_relative 'logger/severity'
 require_relative 'logger/errors'
 
-# == Description
+# \Class \Logger provides a simple but sophisticated logging utility that
+# you can use to create one or more
+# {event logs}[https://en.wikipedia.org/wiki/Logging_(software)#Event_logs]
+# for your program.
+# Each such log contains a chronological sequence of entries
+# that provides a record of the program's activities.
 #
-# The Logger class provides a simple but sophisticated logging utility that
-# you can use to output messages.
+# == About the Examples
 #
-# The messages have associated levels, such as +INFO+ or +ERROR+ that indicate
-# their importance.  You can then give the Logger a level, and only messages
-# at that level or higher will be printed.
+# All examples on this page assume that \Logger has been required:
 #
-# The levels are:
+#   require 'logger'
 #
-# +UNKNOWN+:: An unknown message that should always be logged.
-# +FATAL+:: An unhandleable error that results in a program crash.
-# +ERROR+:: A handleable error condition.
-# +WARN+::  A warning.
-# +INFO+::  Generic (useful) information about system operation.
-# +DEBUG+:: Low-level information for developers.
+# == Synopsis
 #
-# For instance, in a production system, you may have your Logger set to
-# +INFO+ or even +WARN+.
-# When you are developing the system, however, you probably
-# want to know about the program's internal state, and would set the Logger to
-# +DEBUG+.
+# Create a log with Logger.new:
 #
-# *Note*: Logger does not escape or sanitize any messages passed to it.
-# Developers should be aware of when potentially malicious data (user-input)
-# is passed to Logger, and manually escape the untrusted data:
+#   # Single log file.
+#   logger = Logger.new('t.log')
+#   # Size-based rotated logging: 3 10-megabyte files.
+#   logger = Logger.new('t.log', 3, 10485760)
+#   # Period-based rotated logging: daily (also allowed: 'weekly', 'monthly').
+#   logger = Logger.new('t.log', 'daily')
+#   # Log to an IO stream.
+#   logger = Logger.new($stdout)
 #
-#   logger.info("User-input: #{input.dump}")
-#   logger.info("User-input: %p" % input)
+# Add entries (level, message) with Logger#add:
 #
-# You can use #formatter= for escaping all data.
+#   logger.add(Logger::DEBUG, 'Maximal debugging info')
+#   logger.add(Logger::INFO, 'Non-error information')
+#   logger.add(Logger::WARN, 'Non-error warning')
+#   logger.add(Logger::ERROR, 'Non-fatal error')
+#   logger.add(Logger::FATAL, 'Fatal error')
+#   logger.add(Logger::UNKNOWN, 'Most severe')
 #
-#   original_formatter = Logger::Formatter.new
-#   logger.formatter = proc { |severity, datetime, progname, msg|
-#     original_formatter.call(severity, datetime, progname, msg.dump)
-#   }
-#   logger.info(input)
+# Close the log with Logger#close:
 #
-# === Example
+#   logger.close
 #
-# This creates a Logger that outputs to the standard output stream, with a
-# level of +WARN+:
+# == Entries
 #
-#   require 'logger'
+# You can add entries with method Logger#add:
+#
+#   logger.add(Logger::DEBUG, 'Maximal debugging info')
+#   logger.add(Logger::INFO, 'Non-error information')
+#   logger.add(Logger::WARN, 'Non-error warning')
+#   logger.add(Logger::ERROR, 'Non-fatal error')
+#   logger.add(Logger::FATAL, 'Fatal error')
+#   logger.add(Logger::UNKNOWN, 'Most severe')
+#
+# These shorthand methods also add entries:
+#
+#   logger.debug('Maximal debugging info')
+#   logger.info('Non-error information')
+#   logger.warn('Non-error warning')
+#   logger.error('Non-fatal error')
+#   logger.fatal('Fatal error')
+#   logger.unknown('Most severe')
+#
+# When you call any of these methods,
+# the entry may or may not be written to the log,
+# depending on the entry's severity and on the log level;
+# see {Log Level}[rdoc-ref:Logger@Log+Level]
+#
+# An entry always has:
+#
+# - A severity (the required argument to #add).
+# - An automatically created timestamp.
+#
+# And may also have:
+#
+# - A message.
+# - A program name.
+#
+# Example:
+#
+#   logger = Logger.new($stdout)
+#   logger.add(Logger::INFO, 'My message.', 'mung')
+#   # => I, [2022-05-07T17:21:46.536234 #20536]  INFO -- mung: My message.
+#
+# The default format for an entry is:
+#
+#   "%s, [%s #%d] %5s -- %s: %s\n"
+#
+# where the values to be formatted are:
+#
+# - \Severity (one letter).
+# - Timestamp.
+# - Process id.
+# - \Severity (word).
+# - Program name.
+# - Message.
+#
+# You can use a different entry format by:
+#
+# - Setting a custom format proc (affects following entries);
+#   see {formatter=}[Logger.html#attribute-i-formatter].
+# - Calling any of the methods above with a block
+#   (affects only the one entry).
+#   Doing so can have two benefits:
+#
+#   - Context: the block can evaluate the entire program context
+#     and create a context-dependent message.
+#   - Performance: the block is not evaluated unless the log level
+#     permits the entry actually to be written:
+#
+#       logger.error { my_slow_message_generator }
+#
+#     Contrast this with the string form, where the string is
+#     always evaluated, regardless of the log level:
+#
+#       logger.error("#{my_slow_message_generator}")
+#
+# === \Severity
+#
+# The severity of a log entry has two effects:
+#
+# - Determines whether the entry is selected for inclusion in the log;
+#   see {Log Level}[rdoc-ref:Logger@Log+Level].
+# - Indicates to any log reader (whether a person or a program)
+#   the relative importance of the entry.
+#
+# === Timestamp
 #
-#   logger = Logger.new(STDOUT)
-#   logger.level = Logger::WARN
+# The timestamp for a log entry is generated automatically
+# when the entry is created.
 #
-#   logger.debug("Created logger")
-#   logger.info("Program started")
-#   logger.warn("Nothing to do!")
+# The logged timestamp is formatted by method
+# {Time#strftime}[https://docs.ruby-lang.org/en/master/Time.html#method-i-strftime]
+# using this format string:
 #
-#   path = "a_non_existent_file"
+#   '%Y-%m-%dT%H:%M:%S.%6N'
 #
-#   begin
-#     File.foreach(path) do |line|
-#       unless line =~ /^(\w+) = (.*)$/
-#         logger.error("Line in wrong format: #{line.chomp}")
-#       end
-#     end
-#   rescue => err
-#     logger.fatal("Caught exception; exiting")
-#     logger.fatal(err)
-#   end
+# Example:
 #
-# Because the Logger's level is set to +WARN+, only the warning, error, and
-# fatal messages are recorded.  The debug and info messages are silently
-# discarded.
+#   logger = Logger.new($stdout)
+#   logger.add(Logger::INFO)
+#   # => I, [2022-05-07T17:04:32.318331 #20536]  INFO -- : nil
 #
-# === Features
+# You can set a different format using method #datetime_format=.
 #
-# There are several interesting features that Logger provides, like
-# auto-rolling of log files, setting the format of log messages, and
-# specifying a program name in conjunction with the message.  The next section
-# shows you how to achieve these things.
+# === Message
 #
+# The message is an optional argument to an entry method:
 #
-# == HOWTOs
+#   logger = Logger.new($stdout)
+#   logger.add(Logger::INFO, 'My message')
+#   # => I, [2022-05-07T18:15:37.647581 #20536]  INFO -- : My message
 #
-# === How to create a logger
+# For the default entry formatter, <tt>Logger::Formatter</tt>,
+# the message object may be:
 #
-# The options below give you various choices, in more or less increasing
-# complexity.
+# - A string: used as-is.
+# - An Exception: <tt>message.message</tt> is used.
+# - Anything else: <tt>message.inspect</tt> is used.
 #
-# 1. Create a logger which logs messages to STDERR/STDOUT.
+# *Note*: Logger::Formatter does not escape or sanitize
+# the message passed to it.
+# Developers should be aware that malicious data (user input)
+# may be in the message, and should explicitly escape untrusted data.
 #
-#      logger = Logger.new(STDERR)
-#      logger = Logger.new(STDOUT)
+# You can use a custom formatter to escape message data;
+# see the example at {formatter=}[Logger.html#attribute-i-formatter].
 #
-# 2. Create a logger for the file which has the specified name.
+# === Program Name
 #
-#      logger = Logger.new('logfile.log')
+# The program name is an optional argument to an entry method:
 #
-# 3. Create a logger for the specified file.
+#   logger = Logger.new($stdout)
+#   logger.add(Logger::INFO, 'My message', 'mung')
+#   # => I, [2022-05-07T18:17:38.084716 #20536]  INFO -- mung: My message
 #
-#      file = File.open('foo.log', File::WRONLY | File::APPEND)
-#      # To create new logfile, add File::CREAT like:
-#      # file = File.open('foo.log', File::WRONLY | File::APPEND | File::CREAT)
-#      logger = Logger.new(file)
+# The default program name for a new logger may be set in the call to
+# Logger.new via optional keyword argument +progname+:
 #
-# 4. Create a logger which ages the logfile once it reaches a certain size.
-#    Leave 10 "old" log files where each file is about 1,024,000 bytes.
+#   logger = Logger.new('t.log', progname: 'mung')
 #
-#      logger = Logger.new('foo.log', 10, 1024000)
+# The default program name for an existing logger may be set
+# by a call to method #progname=:
 #
-# 5. Create a logger which ages the logfile daily/weekly/monthly.
+#   logger.progname = 'mung'
 #
-#      logger = Logger.new('foo.log', 'daily')
-#      logger = Logger.new('foo.log', 'weekly')
-#      logger = Logger.new('foo.log', 'monthly')
+# The current program name may be retrieved with method
+# {progname}[Logger.html#attribute-i-progname]:
 #
-# === How to log a message
+#   logger.progname # => "mung"
 #
-# Notice the different methods (+fatal+, +error+, +info+) being used to log
-# messages of various levels?  Other methods in this family are +warn+ and
-# +debug+.  +add+ is used below to log a message of an arbitrary (perhaps
-# dynamic) level.
+# == Log Level
 #
-# 1. Message in a block.
+# The log level setting determines whether an entry is actually
+# written to the log, based on the entry's severity.
 #
-#      logger.fatal { "Argument 'foo' not given." }
+# These are the defined severities (least severe to most severe):
 #
-# 2. Message as a string.
+#   logger = Logger.new($stdout)
+#   logger.add(Logger::DEBUG, 'Maximal debugging info')
+#   # => D, [2022-05-07T17:57:41.776220 #20536] DEBUG -- : Maximal debugging info
+#   logger.add(Logger::INFO, 'Non-error information')
+#   # => I, [2022-05-07T17:59:14.349167 #20536]  INFO -- : Non-error information
+#   logger.add(Logger::WARN, 'Non-error warning')
+#   # => W, [2022-05-07T18:00:45.337538 #20536]  WARN -- : Non-error warning
+#   logger.add(Logger::ERROR, 'Non-fatal error')
+#   # => E, [2022-05-07T18:02:41.592912 #20536] ERROR -- : Non-fatal error
+#   logger.add(Logger::FATAL, 'Fatal error')
+#   # => F, [2022-05-07T18:05:24.703931 #20536] FATAL -- : Fatal error
+#   logger.add(Logger::UNKNOWN, 'Most severe')
+#   # => A, [2022-05-07T18:07:54.657491 #20536]   ANY -- : Most severe
 #
-#      logger.error "Argument #{@foo} mismatch."
+# The default initial level setting is Logger::DEBUG, the lowest level,
+# which means that all entries are to be written, regardless of severity:
 #
-# 3. With progname.
+#   logger = Logger.new($stdout)
+#   logger.level # => 0
+#   logger.add(0, "My message")
+#   # => D, [2022-05-11T15:10:59.773668 #20536] DEBUG -- : My message
 #
-#      logger.info('initialize') { "Initializing..." }
+# You can specify a different setting in a new logger
+# using keyword argument +level+ with an appropriate value:
 #
-# 4. With severity.
+#   logger = Logger.new($stdout, level: Logger::ERROR)
+#   logger = Logger.new($stdout, level: 'error')
+#   logger = Logger.new($stdout, level: :error)
+#   logger.level # => 3
 #
-#      logger.add(Logger::FATAL) { 'Fatal error!' }
+# With this level, entries with severity Logger::ERROR and higher
+# are written, while those with lower severities are not written:
 #
-# The block form allows you to create potentially complex log messages,
-# but to delay their evaluation until and unless the message is
-# logged.  For example, if we have the following:
+#   logger = Logger.new($stdout, level: Logger::ERROR)
+#   logger.add(3)
+#   # => E, [2022-05-11T15:17:20.933362 #20536] ERROR -- : nil
+#   logger.add(2) # Silent.
 #
-#     logger.debug { "This is a " + potentially + " expensive operation" }
+# You can set the log level for an existing logger
+# with method #level=:
 #
-# If the logger's level is +INFO+ or higher, no debug messages will be logged,
-# and the entire block will not even be evaluated.  Compare to this:
+#   logger.level = Logger::ERROR
 #
-#     logger.debug("This is a " + potentially + " expensive operation")
+# These shorthand methods also set the level:
 #
-# Here, the string concatenation is done every time, even if the log
-# level is not set to show the debug message.
+#   logger.debug! # => 0
+#   logger.info!  # => 1
+#   logger.warn!  # => 2
+#   logger.error! # => 3
+#   logger.fatal! # => 4
 #
-# === How to close a logger
+# You can retrieve the log level with method
+# {level}[Logger.html#attribute-i-level]:
 #
-#      logger.close
+#   logger.level = Logger::ERROR
+#   logger.level # => 3
 #
-# === Setting severity threshold
+# These methods return whether a given
+# level is to be written:
 #
-# 1. Original interface.
+#   logger.level = Logger::ERROR
+#   logger.debug? # => false
+#   logger.info?  # => false
+#   logger.warn?  # => false
+#   logger.error? # => true
+#   logger.fatal? # => true
 #
-#      logger.sev_threshold = Logger::WARN
+# == Log File Rotation
 #
-# 2. Log4r (somewhat) compatible interface.
+# By default, a log file is a single file that grows indefinitely
+# (until explicitly closed); there is no file rotation.
 #
-#      logger.level = Logger::INFO
+# To keep log files to a manageable size,
+# you can use _log_ _file_ _rotation_, which uses multiple log files:
 #
-#      # DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN
+# - Each log file has entries for a non-overlapping
+#   time interval.
+# - Only the most recent log file is open and active;
+#   the others are closed and inactive.
 #
-# 3. Symbol or String (case insensitive)
+# === Size-Based Rotation
 #
-#      logger.level = :info
-#      logger.level = 'INFO'
+# For size-based log file rotation, call Logger.new with:
 #
-#      # :debug < :info < :warn < :error < :fatal < :unknown
+# - Argument +logdev+ as a file path.
+# - Argument +shift_age+ with a positive integer:
+#   the number of log files to be in the rotation.
+# - Argument +shift_size+ as a positive integer:
+#   the maximum size (in bytes) of each log file;
+#   defaults to 1048576 (1 megabyte).
 #
-# 4. Constructor
+# Examples:
 #
-#      Logger.new(logdev, level: Logger::INFO)
-#      Logger.new(logdev, level: :info)
-#      Logger.new(logdev, level: 'INFO')
+#   logger = Logger.new('t.log', 3)           # Three 1-megabyte files.
+#   logger = Logger.new('t.log', 5, 10485760) # Five 10-megabyte files.
 #
-# == Format
+# For these examples, suppose:
 #
-# Log messages are rendered in the output stream in a certain format by
-# default.  The default format and a sample are shown below:
+#   logger = Logger.new('t.log', 3)
 #
-# Log format:
-#   SeverityID, [DateTime #pid] SeverityLabel -- ProgName: message
+# Logging begins in the new log file, +t.log+;
+# the log file is "full" and ready for rotation
+# when a new entry would cause its size to exceed +shift_size+.
 #
-# Log sample:
-#   I, [1999-03-03T02:34:24.895701 #19074]  INFO -- Main: info.
+# The first time +t.log+ is full:
 #
-# You may change the date and time format via #datetime_format=.
+# - +t.log+ is closed and renamed to +t.log.0+.
+# - A new file +t.log+ is opened.
 #
-#   logger.datetime_format = '%Y-%m-%d %H:%M:%S'
-#         # e.g. "2004-01-03 00:54:26"
+# The second time +t.log+ is full:
 #
-# or via the constructor.
+# - +t.log.0 is renamed as +t.log.1+.
+# - +t.log+ is closed and renamed to +t.log.0+.
+# - A new file +t.log+ is opened.
 #
-#   Logger.new(logdev, datetime_format: '%Y-%m-%d %H:%M:%S')
+# Each subsequent time that +t.log+ is full,
+# the log files are rotated:
 #
-# Or, you may change the overall format via the #formatter= method.
+# - +t.log.1+ is removed.
+# - +t.log.0 is renamed as +t.log.1+.
+# - +t.log+ is closed and renamed to +t.log.0+.
+# - A new file +t.log+ is opened.
 #
-#   logger.formatter = proc do |severity, datetime, progname, msg|
-#     "#{datetime}: #{msg}\n"
-#   end
-#   # e.g. "2005-09-22 08:51:08 +0900: hello world"
+# === Periodic Rotation
 #
-# or via the constructor.
+# For periodic rotation, call Logger.new with:
 #
-#   Logger.new(logdev, formatter: proc {|severity, datetime, progname, msg|
-#     "#{datetime}: #{msg}\n"
-#   })
+# - Argument +logdev+ as a file path.
+# - Argument +shift_age+ as a string period indicator.
+#
+# Examples:
+#
+#   logger = Logger.new('t.log', 'daily')   # Rotate log files daily.
+#   logger = Logger.new('t.log', 'weekly')  # Rotate log files weekly.
+#   logger = Logger.new('t.log', 'monthly') # Rotate log files monthly.
+#
+# Example:
+#
+#   logger = Logger.new('t.log', 'daily')
+#
+# When the given period expires:
+#
+# - The base log file, +t.log+ is closed and renamed
+#   with a date-based suffix such as +t.log.20220509+.
+# - A new log file +t.log+ is opened.
+# - Nothing is removed.
+#
+# The default format for the suffix is <tt>'%Y%m%d'</tt>,
+# which produces a suffix similar to the one above.
+# You can set a different format using create-time option
+# +shift_period_suffix+;
+# see details and suggestions at
+# {Time#strftime}[https://docs.ruby-lang.org/en/master/Time.html#method-i-strftime].
 #
 class Logger
   _, name, rev = %w$Id$
@@ -245,9 +382,18 @@ class Logger
   # Logging severity threshold (e.g. <tt>Logger::INFO</tt>).
   attr_reader :level
 
-  # Set logging severity threshold.
+  # Sets the log level; returns +severity+.
+  # See {Log Level}[rdoc-ref:Logger@Log+Level].
+  #
+  # Argument +severity+ may be an integer, a string, or a symbol:
+  #
+  #   logger.level = Logger::ERROR # => 3
+  #   logger.level = 3             # => 3
+  #   logger.level = 'error'       # => "error"
+  #   logger.level = :error        # => :error
+  #
+  # Logger#sev_threshold= is an alias for Logger#level=.
   #
-  # +severity+:: The Severity of the log message.
   def level=(severity)
     if severity.is_a?(Integer)
       @level = severity
@@ -274,109 +420,159 @@ class Logger
   # Program name to include in log messages.
   attr_accessor :progname
 
-  # Set date-time format.
+  # Sets the date-time format.
+  #
+  # Argument +datetime_format+ should be either of these:
+  #
+  # - A string suitable for use as a format for method
+  #   {Time#strftime}[https://docs.ruby-lang.org/en/master/Time.html#method-i-strftime].
+  # - +nil+: the logger uses <tt>'%Y-%m-%dT%H:%M:%S.%6N'</tt>.
   #
-  # +datetime_format+:: A string suitable for passing to +strftime+.
   def datetime_format=(datetime_format)
     @default_formatter.datetime_format = datetime_format
   end
 
-  # Returns the date format being used.  See #datetime_format=
+  # Returns the date-time format; see #datetime_format=.
+  #
   def datetime_format
     @default_formatter.datetime_format
   end
 
-  # Logging formatter, as a +Proc+ that will take four arguments and
-  # return the formatted message. The arguments are:
+  # Sets or retrieves the logger entry formatter proc.
   #
-  # +severity+:: The Severity of the log message.
-  # +time+:: A Time instance representing when the message was logged.
-  # +progname+:: The #progname configured, or passed to the logger method.
-  # +msg+:: The _Object_ the user passed to the log message; not necessarily a
-  #         String.
+  # When +formatter+ is +nil+, the logger uses Logger::Formatter.
+  #
+  # When +formatter+ is a proc, a new entry is formatted by the proc,
+  # which is called with four arguments:
+  #
+  # - +severity+: The severity of the entry.
+  # - +time+: A Time object representing the entry's timestamp.
+  # - +progname+: The program name for the entry.
+  # - +msg+: The message for the entry (string or string-convertible object).
+  #
+  # The proc should return a string containing the formatted entry.
+  #
+  # This custom formatter uses
+  # {String#dump}[https://docs.ruby-lang.org/en/master/String.html#method-i-dump]
+  # to escape the message string:
+  #
+  #   logger = Logger.new($stdout, progname: 'mung')
+  #   original_formatter = logger.formatter || Logger::Formatter.new
+  #   logger.formatter = proc { |severity, time, progname, msg|
+  #     original_formatter.call(severity, time, progname, msg.dump)
+  #   }
+  #   logger.add(Logger::INFO, "hello \n ''")
+  #   logger.add(Logger::INFO, "\f\x00\xff\\\"")
+  #
+  # Output:
+  #
+  #   I, [2022-05-13T13:16:29.637488 #8492]  INFO -- mung: "hello \n ''"
+  #   I, [2022-05-13T13:16:29.637610 #8492]  INFO -- mung: "\f\x00\xFF\\\""
   #
-  # The block should return an Object that can be written to the logging
-  # device via +write+.  The default formatter is used when no formatter is
-  # set.
   attr_accessor :formatter
 
   alias sev_threshold level
   alias sev_threshold= level=
 
-  # Returns +true+ if and only if the current severity level allows for the printing of
-  # +DEBUG+ messages.
+  # Returns +true+ if the log level allows entries with severity
+  # Logger::DEBUG to be written, +false+ otherwise.
+  # See {Log Level}[rdoc-ref:Logger@Log+Level].
+  #
   def debug?; level <= DEBUG; end
 
-  # Sets the severity to DEBUG.
+  # Sets the log level to Logger::DEBUG.
+  # See {Log Level}[rdoc-ref:Logger@Log+Level].
+  #
   def debug!; self.level = DEBUG; end
 
-  # Returns +true+ if and only if the current severity level allows for the printing of
-  # +INFO+ messages.
+  # Returns +true+ if the log level allows entries with severity
+  # Logger::INFO to be written, +false+ otherwise.
+  # See {Log Level}[rdoc-ref:Logger@Log+Level].
+  #
   def info?; level <= INFO; end
 
-  # Sets the severity to INFO.
+  # Sets the log level to Logger::INFO.
+  # See {Log Level}[rdoc-ref:Logger@Log+Level].
+  #
   def info!; self.level = INFO; end
 
-  # Returns +true+ if and only if the current severity level allows for the printing of
-  # +WARN+ messages.
+  # Returns +true+ if the log level allows entries with severity
+  # Logger::WARN to be written, +false+ otherwise.
+  # See {Log Level}[rdoc-ref:Logger@Log+Level].
+  #
   def warn?; level <= WARN; end
 
-  # Sets the severity to WARN.
+  # Sets the log level to Logger::WARN.
+  # See {Log Level}[rdoc-ref:Logger@Log+Level].
+  #
   def warn!; self.level = WARN; end
 
-  # Returns +true+ if and only if the current severity level allows for the printing of
-  # +ERROR+ messages.
+  # Returns +true+ if the log level allows entries with severity
+  # Logger::ERROR to be written, +false+ otherwise.
+  # See {Log Level}[rdoc-ref:Logger@Log+Level].
+  #
   def error?; level <= ERROR; end
 
-  # Sets the severity to ERROR.
+  # Sets the log level to Logger::ERROR.
+  # See {Log Level}[rdoc-ref:Logger@Log+Level].
+  #
   def error!; self.level = ERROR; end
 
-  # Returns +true+ if and only if the current severity level allows for the printing of
-  # +FATAL+ messages.
+  # Returns +true+ if the log level allows entries with severity
+  # Logger::FATAL to be written, +false+ otherwise.
+  # See {Log Level}[rdoc-ref:Logger@Log+Level].
+  #
   def fatal?; level <= FATAL; end
 
-  # Sets the severity to FATAL.
+  # Sets the log level to Logger::FATAL.
+  # See {Log Level}[rdoc-ref:Logger@Log+Level].
+  #
   def fatal!; self.level = FATAL; end
 
-  #
   # :call-seq:
-  #   Logger.new(logdev, shift_age = 0, shift_size = 1048576)
-  #   Logger.new(logdev, shift_age = 'weekly')
-  #   Logger.new(logdev, level: :info)
-  #   Logger.new(logdev, progname: 'progname')
-  #   Logger.new(logdev, formatter: formatter)
-  #   Logger.new(logdev, datetime_format: '%Y-%m-%d %H:%M:%S')
-  #
-  # === Args
-  #
-  # +logdev+::
-  #   The log device.  This is a filename (String), IO object (typically
-  #   +STDOUT+, +STDERR+, or an open file), +nil+ (it writes nothing) or
-  #   +File::NULL+ (same as +nil+).
-  # +shift_age+::
-  #   Number of old log files to keep, *or* frequency of rotation (+daily+,
-  #   +weekly+ or +monthly+). Default value is 0, which disables log file
-  #   rotation.
-  # +shift_size+::
-  #   Maximum logfile size in bytes (only applies when +shift_age+ is a positive
-  #   Integer). Defaults to +1048576+ (1MB).
-  # +level+::
-  #   Logging severity threshold. Default values is Logger::DEBUG.
-  # +progname+::
-  #   Program name to include in log messages. Default value is nil.
-  # +formatter+::
-  #   Logging formatter. Default values is an instance of Logger::Formatter.
-  # +datetime_format+::
-  #   Date and time format. Default value is '%Y-%m-%d %H:%M:%S'.
-  # +binmode+::
-  #   Use binary mode on the log device. Default value is false.
-  # +shift_period_suffix+::
-  #   The log file suffix format for +daily+, +weekly+ or +monthly+ rotation.
-  #   Default is '%Y%m%d'.
-  #
-  # === Description
-  #
-  # Create an instance.
+  #    Logger.new(logdev, shift_age = 0, shift_size = 1048576, **options)
+  #
+  # With the single argument +logdev+,
+  # returns a new logger with all default options:
+  #
+  #   Logger.new('t.log') # => #<Logger:0x000001e685dc6ac8>
+  #
+  # Argument +logdev+ must be one of:
+  #
+  # - A string filepath: entries are to be written
+  #   to the file at that path; if the file at that path exists,
+  #   new entries are appended.
+  # - An IO stream (typically +$stdout+, +$stderr+. or an open file):
+  #   entries are to be written to the given stream.
+  # - +nil+ or +File::NULL+: no entries are to be written.
+  #
+  # Examples:
+  #
+  #   Logger.new('t.log')
+  #   Logger.new($stdout)
+  #
+  # The keyword options are:
+  #
+  # - +level+: sets the log level; default value is Logger::DEBUG.
+  #   See {Log Level}[rdoc-ref:Logger@Log+Level]:
+  #
+  #     Logger.new('t.log', level: Logger::ERROR)
+  #
+  # - +progname+: sets the default program name; default is +nil+.
+  #   See {Program Name}[rdoc-ref:Logger@Program+Name]:
+  #
+  #     Logger.new('t.log', progname: 'mung')
+  #
+  # - +formatter+: sets the entry formatter; default is +nil+.
+  #   See {formatter=}[Logger.html#attribute-i-formatter].
+  # - +datetime_format+: sets the format for entry timestamp;
+  #   default is +nil+.
+  #   See #datetime_format=.
+  # - +binmode+: sets whether the logger writes in binary mode;
+  #   default is +false+.
+  # - +shift_period_suffix+: sets the format for the filename suffix
+  #   for periodic log file rotation; default is <tt>'%Y%m%d'</tt>.
+  #   See {Periodic Rotation}[rdoc-ref:Logger@Periodic+Rotation].
   #
   def initialize(logdev, shift_age = 0, shift_size = 1048576, level: DEBUG,
                  progname: nil, formatter: nil, datetime_format: nil,
@@ -395,67 +591,60 @@ class Logger
     end
   end
 
-  #
-  # :call-seq:
-  #   Logger#reopen
-  #   Logger#reopen(logdev)
-  #
-  # === Args
-  #
-  # +logdev+::
-  #   The log device.  This is a filename (String) or IO object (typically
-  #   +STDOUT+, +STDERR+, or an open file).  reopen the same filename if
-  #   it is +nil+, do nothing for IO.  Default is +nil+.
-  #
-  # === Description
-  #
-  # Reopen a log device.
+  # Sets the logger's output stream:
+  #
+  # - If +logdev+ is +nil+, reopens the current output stream.
+  # - If +logdev+ is a filepath, opens the indicated file for append.
+  # - If +logdev+ is an IO stream
+  #   (usually <tt>$stdout</tt>, <tt>$stderr</tt>, or an open File object),
+  #   opens the stream for append.
+  #
+  # Example:
+  #
+  #   logger = Logger.new('t.log')
+  #   logger.add(Logger::ERROR, 'one')
+  #   logger.close
+  #   logger.add(Logger::ERROR, 'two') # Prints 'log writing failed. closed stream'
+  #   logger.reopen
+  #   logger.add(Logger::ERROR, 'three')
+  #   logger.close
+  #   File.readlines('t.log')
+  #   # =>
+  #   # ["# Logfile created on 2022-05-12 14:21:19 -0500 by logger.rb/v1.5.0\n",
+  #   #  "E, [2022-05-12T14:21:27.596726 #22428] ERROR -- : one\n",
+  #   #  "E, [2022-05-12T14:23:05.847241 #22428] ERROR -- : three\n"]
   #
   def reopen(logdev = nil)
     @logdev&.reopen(logdev)
     self
   end
 
+  # Creates a log entry, which may or may not be written to the log,
+  # depending on the entry's severity and on the log level.
+  # See {Log Level}[rdoc-ref:Logger@Log+Level]
+  # and {Entries}[rdoc-ref:Logger@Entries] for details.
   #
-  # :call-seq:
-  #   Logger#add(severity, message = nil, progname = nil) { ... }
-  #
-  # === Args
-  #
-  # +severity+::
-  #   Severity.  Constants are defined in Logger namespace: +DEBUG+, +INFO+,
-  #   +WARN+, +ERROR+, +FATAL+, or +UNKNOWN+.
-  # +message+::
-  #   The log message.  A String or Exception.
-  # +progname+::
-  #   Program name string.  Can be omitted.  Treated as a message if no
-  #   +message+ and +block+ are given.
-  # +block+::
-  #   Can be omitted.  Called to get a message string if +message+ is nil.
-  #
-  # === Return
-  #
-  # When the given severity is not high enough (for this particular logger),
-  # log no message, and return +true+.
+  # Examples:
   #
-  # === Description
+  #   logger = Logger.new($stdout, progname: 'mung')
+  #   logger.add(Logger::INFO)
+  #   logger.add(Logger::ERROR, 'No good')
+  #   logger.add(Logger::ERROR, 'No good', 'gnum')
   #
-  # Log a message if the given severity is high enough.  This is the generic
-  # logging method.  Users will be more inclined to use #debug, #info, #warn,
-  # #error, and #fatal.
+  # Output:
   #
-  # <b>Message format</b>: +message+ can be any object, but it has to be
-  # converted to a String in order to log it.  Generally, +inspect+ is used
-  # if the given object is not a String.
-  # A special case is an +Exception+ object, which will be printed in detail,
-  # including message, class, and backtrace.  See #msg2str for the
-  # implementation if required.
+  #   I, [2022-05-12T16:25:31.469726 #36328]  INFO -- mung: mung
+  #   E, [2022-05-12T16:25:55.349414 #36328] ERROR -- mung: No good
+  #   E, [2022-05-12T16:26:35.841134 #36328] ERROR -- gnum: No good
   #
-  # === Bugs
+  # These convenience methods have implicit severity:
   #
-  # * Logfile is not locked.
-  # * Append open does not need to lock file.
-  # * If the OS supports multi I/O, records possibly may be mixed.
+  # - #debug.
+  # - #info.
+  # - #warn.
+  # - #error.
+  # - #fatal.
+  # - #unknown.
   #
   def add(severity, message = nil, progname = nil)
     severity ||= UNKNOWN
@@ -479,104 +668,71 @@ class Logger
   end
   alias log add
 
+  # Writes the given +msg+ to the log with no formatting;
+  # returns the number of characters written,
+  # or +nil+ if no log device exists:
   #
-  # Dump given message to the log device without any formatting.  If no log
-  # device exists, return +nil+.
+  #   logger = Logger.new($stdout)
+  #   logger << 'My message.' # => 10
+  #
+  # Output:
+  #
+  #   My message.
   #
   def <<(msg)
     @logdev&.write(msg)
   end
 
-  #
-  # Log a +DEBUG+ message.
-  #
-  # See #info for more information.
+  # Equivalent to calling #add with severity <tt>Logger::DEBUG</tt>.
   #
   def debug(progname = nil, &block)
     add(DEBUG, nil, progname, &block)
   end
 
-  #
-  # :call-seq:
-  #   info(message)
-  #   info(progname, &block)
-  #
-  # Log an +INFO+ message.
-  #
-  # +message+:: The message to log; does not need to be a String.
-  # +progname+:: In the block form, this is the #progname to use in the
-  #              log message.  The default can be set with #progname=.
-  # +block+:: Evaluates to the message to log.  This is not evaluated unless
-  #           the logger's level is sufficient to log the message.  This
-  #           allows you to create potentially expensive logging messages that
-  #           are only called when the logger is configured to show them.
-  #
-  # === Examples
-  #
-  #   logger.info("MainApp") { "Received connection from #{ip}" }
-  #   # ...
-  #   logger.info "Waiting for input from user"
-  #   # ...
-  #   logger.info { "User typed #{input}" }
-  #
-  # You'll probably stick to the second form above, unless you want to provide a
-  # program name (which you can do with #progname= as well).
-  #
-  # === Return
-  #
-  # See #add.
+  # Equivalent to calling #add with severity <tt>Logger::INFO</tt>.
   #
   def info(progname = nil, &block)
     add(INFO, nil, progname, &block)
   end
 
-  #
-  # Log a +WARN+ message.
-  #
-  # See #info for more information.
+  # Equivalent to calling #add with severity <tt>Logger::WARN</tt>.
   #
   def warn(progname = nil, &block)
     add(WARN, nil, progname, &block)
   end
 
-  #
-  # Log an +ERROR+ message.
-  #
-  # See #info for more information.
+  # Equivalent to calling #add with severity <tt>Logger::ERROR</tt>.
   #
   def error(progname = nil, &block)
     add(ERROR, nil, progname, &block)
   end
 
-  #
-  # Log a +FATAL+ message.
-  #
-  # See #info for more information.
+  # Equivalent to calling #add with severity <tt>Logger::FATAL</tt>.
   #
   def fatal(progname = nil, &block)
     add(FATAL, nil, progname, &block)
   end
 
-  #
-  # Log an +UNKNOWN+ message.  This will be printed no matter what the logger's
-  # level is.
-  #
-  # See #info for more information.
+  # Equivalent to calling #add with severity <tt>Logger::UNKNOWN</tt>.
   #
   def unknown(progname = nil, &block)
     add(UNKNOWN, nil, progname, &block)
   end
 
+  # Closes the logger; returns +nil+:
   #
-  # Close the logging device.
+  #   logger = Logger.new('t.log')
+  #   logger.close       # => nil
+  #   logger.info('foo') # Prints "log writing failed. closed stream"
   #
+  # Related: Logger#reopen.
   def close
     @logdev&.close
   end
 
 private
 
-  # Severity label for logging (max 5 chars).
+  # \Severity label for logging (max 5 chars).
   SEV_LABEL = %w(DEBUG INFO WARN ERROR FATAL ANY).freeze
 
   def format_severity(severity)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: logger
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.5.2
 platform: ruby
 authors:
 - Naotoshi Seo
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-03-17 00:00:00.000000000 Z
+date: 2022-12-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler