module RDF::Util::Logger

Helpers for logging errors, warnings and debug information.

Modules must provide ‘@logger`, which returns an instance of `Logger`, or something responding to `#<<`. Logger may also be specified using an `@options` hash containing a `:logger` entry. @since 2.0.0

Constants

IOWrapper

The IOWrapper class is used to store per-logger state while wrapping an IO such as $stderr.

LOGGER_COMMON_LEVELS
LOGGER_COMMON_LEVELS_REVERSE

Public Instance Methods

log_debug(*args, level: :debug, **options, &block) click to toggle source

Debug message.

@overload log_debug(*args, **options, &block)

@param [Array<String>] args
@param [Array<String>] args Messages
@param [:fatal, :error, :warn, :info, :debug] level (:debug)
@param [Hash{Symbol => Object}] options
@option options [Integer] :depth
  Recursion depth for indenting output
@option options [Integer] :lineno associated with message
@option options [Logger, #<<] :logger
@yieldreturn [String] added to message
@return [void]
# File lib/rdf/util/logger.rb, line 179
def log_debug(*args, level: :debug, **options, &block)
  logger_common(*args, level: level, **options, &block)
end
log_depth(depth: 1, **options, &block) click to toggle source

@overload log_depth(depth: 1, **options, &block)

Increase depth around a method invocation
@param [Integer] :depth Additional recursion depth
@param [Hash{Symbol}] options (@options || {})
@option options [Logger, #<<] :logger
@yield
  Yields with no arguments
@yieldreturn [Object] returns the result of yielding
@return [Object]

@overload log_depth

# Return the current log depth
@return [Integer]
# File lib/rdf/util/logger.rb, line 197
def log_depth(depth: 1, **options, &block)
  self.logger(**options).log_depth(depth: depth, &block)
end
log_error(*args, level: :error, **options, &block) click to toggle source

Used for non-fatal errors where processing can continue. If ‘logger` is not configured, it logs to `$stderr`.

As a side-effect of setting ‘@logger_in_error`, which will suppress further error messages until cleared using {#log_recover}.

@overload log_error(*args, **options, &block)

@param [Array<String>] args
@param [Array<String>] args Messages
@param [:fatal, :error, :warn, :info, :debug] level (:error)
@param [Hash{Symbol => Object}] options
@option options [Integer] :depth
  Recursion depth for indenting output
@option options [:fatal, :error, :warn, :info, :debug] level (:<<)
@option options [Integer] :lineno associated with message
@option options [Logger, #<<] :logger
@option options [Class] :exception, (StandardError)
  Exception class used for raising error
@yieldreturn [String] added to message
@return [void]
@raise Raises the provided exception class using the first element from args as the message component, if `:exception` option is provided.
# File lib/rdf/util/logger.rb, line 89
def log_error(*args, level: :error, **options, &block)
  logger = self.logger(**options)
  return if logger.recovering
  logger.recovering = true
  logger_common(*args, level: level, **options, &block)
  raise options[:exception], args.first if options[:exception]
end
log_fatal(*args, level: :fatal, **options, &block) click to toggle source

Used for fatal errors where processing cannot continue. If ‘logger` is not configured, it logs to `$stderr`.

@overload log_fatal(*args, **options, &block)

@param [Array<String>] args
@param [Array<String>] args Messages
@param [:fatal, :error, :warn, :info, :debug] level (:fatal)
@param [Hash{Symbol => Object}] options
@option options [Integer] :depth
  Recursion depth for indenting output
@option options [Integer] :lineno associated with message
@option options [Logger, #<<] :logger
@option options [Class] :exception, (StandardError)
  Exception class used for raising error
@yieldreturn [String] added to message
@return [void]
@raise Raises the provided exception class using the first element from args as the message component.
# File lib/rdf/util/logger.rb, line 64
def log_fatal(*args, level: :fatal, **options, &block)
  logger_common(*args, "Called from #{Gem.location_of_caller.join(':')}", level: level, **options, &block)
  raise options.fetch(:exception, StandardError), args.first
end
log_info(*args, level: :info, **options, &block) click to toggle source

Informational message.

@overload log_info(*args, **options, &block)

@param [Array<String>] args
@param [Array<String>] args Messages
@param [:fatal, :error, :warn, :info, :debug] level (:info)
@param [Hash{Symbol => Object}] options
@option options [Integer] :depth
  Recursion depth for indenting output
@option options [Integer] :lineno associated with message
@option options [Logger, #<<] :logger
@yieldreturn [String] added to message
@return [void]
# File lib/rdf/util/logger.rb, line 161
def log_info(*args, level: :info, **options, &block)
  logger_common(*args, level: level, **options, &block)
end
log_recover(*args, level: :info, **options, &block) click to toggle source

Recovers from an error condition. If ‘args` are passed, sent as an informational message

As a side-effect of clearing ‘@logger_in_error`.

@overload log_recover(*args, **options, &block)

@param [Array<String>] args
@param [Array<String>] args Messages
@param [:fatal, :error, :warn, :info, :debug] level (:info)
@param [Hash{Symbol => Object}] options
@option options [Integer] :depth
  Recursion depth for indenting output
@option options [Integer] :lineno associated with message
@option options [Logger, #<<] :logger
@yieldreturn [String] added to message
@return [void]
# File lib/rdf/util/logger.rb, line 140
def log_recover(*args, level: :info, **options, &block)
  logger = self.logger(**options)
  logger.recovering = false
  return if args.empty? && !block_given?
  logger_common(*args, level: level, **options, &block)
end
log_recovering?(**options) click to toggle source

In recovery mode? When ‘log_error` is called, we enter recovery mode. This is cleared when `log_recover` is called. @param [Hash{Symbol => Object}] options @option options [Logger, <<] :logger @return [Boolean]

# File lib/rdf/util/logger.rb, line 101
def log_recovering?(**options)
  self.logger(**options).recovering
end
log_statistics(**options) click to toggle source

Number of times logger has been called at each level @param [Hash{Symbol => Object}] options @option options [Logger, <<] :logger @return [Hash{Symbol => Integer}]

# File lib/rdf/util/logger.rb, line 43
def log_statistics(**options)
  logger(**options).log_statistics
end
log_warn(*args, level: :warn, **options, &block) click to toggle source

Warning message.

@overload log_warn(*args, **options, &block)

@param [Array<String>] args
@param [Array<String>] args Messages
@param [:fatal, :error, :warn, :info, :debug] level (:warn)
@param [Hash{Symbol => Object}] options
@option options [Integer] :depth
  Recursion depth for indenting output
@option options [:fatal, :error, :warn, :info, :debug] level (:<<)
@option options [Integer] :lineno associated with message
@option options [Logger, #<<] :logger
@yieldreturn [String] added to message
@return [void]
# File lib/rdf/util/logger.rb, line 120
def log_warn(*args, level: :warn, **options, &block)
  logger_common(*args, level: level, **options, &block)
end
logger(logger: nil, **options) click to toggle source

Logger instance, found using ‘options`, `@logger`, or `@options` @param [Hash{Symbol => Object}] options @option options [Logger, <<] :logger @return [Logger, write, <<]

# File lib/rdf/util/logger.rb, line 20
def logger(logger: nil, **options)
  # Guard against undefined instance variables, which may be a warning if used.
  @options = {} unless instance_variable_defined?(:@options) || frozen?
  logger ||= @logger if instance_variable_defined?(:@logger)
  logger = @options[:logger] if logger.nil? && instance_variable_defined?(:@options) && @options
  if logger.nil?
    # Unless otherwise specified, use $stderr
    logger = IOWrapper.new($stderr)

    # Reset log_statistics so that it's not inherited across different instances
    logger.log_statistics.clear if logger.respond_to?(:log_statistics)
  end
  logger = ::Logger.new(::File.open(::File::NULL, "w"))  unless logger # Incase false was used, which is frozen
  @options[:logger] ||= logger if instance_variable_defined?(:@options)
  logger.extend(LoggerBehavior) unless logger.is_a?(LoggerBehavior)
  logger
end

Private Instance Methods

logger_common(*args, level:, **options) { || ... } click to toggle source

Common method for logging messages

The call is ignored, unless ‘@logger` or `@options` is set, in which case it records tracing information as indicated.

@overload logger_common(args, options)

@param [Array<String>] args Messages
@param [:fatal, :error, :warn, :info, :debug] level
@param [Hash{Symbol => Object}] options
@option options [Integer] :depth
  Recursion depth for indenting output
@option options [:fatal, :error, :warn, :info, :debug] level (:<<)
@option options [Integer] :lineno associated with message
@option options [Logger, #<<] :logger
@yieldreturn [String] added to message
@return [void]
# File lib/rdf/util/logger.rb, line 223
def logger_common(*args, level:, **options)
  logger = self.logger(**options)
  # Some older code uses integer level numbers
  level = LOGGER_COMMON_LEVELS_REVERSE.fetch(level) if level.is_a?(Integer)
  logger.log_statistics[level] = logger.log_statistics[level].to_i + 1
  return if logger.level > LOGGER_COMMON_LEVELS.fetch(level)

  depth = options.fetch(:depth, logger.log_depth)
  args << yield if block_given?
  str = (depth > 100 ? ' ' * 100 + '+' : ' ' * depth) + args.join(": ")
  str = "[line #{options[:lineno]}] #{str}" if options[:lineno]
  logger.send(level, str)
end