Module: RDF::Util::Logger

Included in:
NTriples::Reader, NTriples::Writer, Reader, Vocabulary::Writer, Writer
Defined in:
lib/rdf/util/logger.rb

Overview

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

Defined Under Namespace

Modules: LoggerBehavior

Constant Summary collapse

IOWrapper =

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

Since:

  • 2.0.0

DelegateClass(IO)

Instance Method Summary collapse

Instance Method Details

#log_debug(*args, **options, &block) ⇒ void

Debug message.

This method returns an undefined value.

Parameters:

  • args (Array<String>)
  • args (Array<String>)

    Messages

  • level (:fatal, :error, :warn, :info, :debug)

    (:debug)

  • options (Hash{Symbol => Object})

Options Hash (**options):

  • :depth (Integer)

    Recursion depth for indenting output

  • :lineno (Integer)

    associated with message

  • :logger (Logger, #<<)

Yield Returns:

  • (String)

    added to message

Since:

  • 2.0.0



179
180
181
# 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) { ... } ⇒ Object #log_depthInteger

Overloads:

  • #log_depth(depth: 1, **options) { ... } ⇒ Object

    Increase depth around a method invocation

    Parameters:

    • :depth (Integer)

      Additional recursion depth

    • options (Hash{Symbol})

      (@options || {})

    Options Hash (**options):

    Yields:

    • Yields with no arguments

    Yield Returns:

    • (Object)

      returns the result of yielding

    Returns:

    • (Object)
  • #log_depthInteger

    # Return the current log depth

    Returns:

    • (Integer)

Since:

  • 2.0.0



197
198
199
# 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, **options, &block) ⇒ void

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.

This method returns an undefined value.

Parameters:

  • args (Array<String>)
  • args (Array<String>)

    Messages

  • level (:fatal, :error, :warn, :info, :debug)

    (:error)

  • options (Hash{Symbol => Object})

Options Hash (**options):

  • :depth (Integer)

    Recursion depth for indenting output

  • level (:fatal, :error, :warn, :info, :debug) — default: :<<
  • :lineno (Integer)

    associated with message

  • :logger (Logger, #<<)
  • :exception, (Class) — default: StandardError

    Exception class used for raising error

Yield Returns:

  • (String)

    added to message

Raises:

  • Raises the provided exception class using the first element from args as the message component, if ‘:exception` option is provided.

Raises:

  • ()

Since:

  • 2.0.0



89
90
91
92
93
94
95
# 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, **options, &block) ⇒ void

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

This method returns an undefined value.

Parameters:

  • args (Array<String>)
  • args (Array<String>)

    Messages

  • level (:fatal, :error, :warn, :info, :debug)

    (:fatal)

  • options (Hash{Symbol => Object})

Options Hash (**options):

  • :depth (Integer)

    Recursion depth for indenting output

  • :lineno (Integer)

    associated with message

  • :logger (Logger, #<<)
  • :exception, (Class) — default: StandardError

    Exception class used for raising error

Yield Returns:

  • (String)

    added to message

Raises:

  • Raises the provided exception class using the first element from args as the message component.

Raises:

  • (options.fetch(:exception, StandardError))

Since:

  • 2.0.0



64
65
66
67
# 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, **options, &block) ⇒ void

Informational message.

This method returns an undefined value.

Parameters:

  • args (Array<String>)
  • args (Array<String>)

    Messages

  • level (:fatal, :error, :warn, :info, :debug)

    (:info)

  • options (Hash{Symbol => Object})

Options Hash (**options):

  • :depth (Integer)

    Recursion depth for indenting output

  • :lineno (Integer)

    associated with message

  • :logger (Logger, #<<)

Yield Returns:

  • (String)

    added to message

Since:

  • 2.0.0



161
162
163
# 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, **options, &block) ⇒ void

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

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

This method returns an undefined value.

Parameters:

  • args (Array<String>)
  • args (Array<String>)

    Messages

  • level (:fatal, :error, :warn, :info, :debug)

    (:info)

  • options (Hash{Symbol => Object})

Options Hash (**options):

  • :depth (Integer)

    Recursion depth for indenting output

  • :lineno (Integer)

    associated with message

  • :logger (Logger, #<<)

Yield Returns:

  • (String)

    added to message

Since:

  • 2.0.0



140
141
142
143
144
145
# 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) ⇒ Boolean

In recovery mode? When ‘log_error` is called, we enter recovery mode. This is cleared when `log_recover` is called.

Parameters:

  • options (Hash{Symbol => Object})

Options Hash (**options):

Returns:

  • (Boolean)

Since:

  • 2.0.0



101
102
103
# File 'lib/rdf/util/logger.rb', line 101

def log_recovering?(**options)
  self.logger(**options).recovering
end

#log_statistics(**options) ⇒ Hash{Symbol => Integer}

Number of times logger has been called at each level

Parameters:

  • options (Hash{Symbol => Object})

Options Hash (**options):

Returns:

  • (Hash{Symbol => Integer})

Since:

  • 2.0.0



43
44
45
# File 'lib/rdf/util/logger.rb', line 43

def log_statistics(**options)
  logger(**options).log_statistics
end

#log_warn(*args, **options, &block) ⇒ void

Warning message.

This method returns an undefined value.

Parameters:

  • args (Array<String>)
  • args (Array<String>)

    Messages

  • level (:fatal, :error, :warn, :info, :debug)

    (:warn)

  • options (Hash{Symbol => Object})

Options Hash (**options):

  • :depth (Integer)

    Recursion depth for indenting output

  • level (:fatal, :error, :warn, :info, :debug) — default: :<<
  • :lineno (Integer)

    associated with message

  • :logger (Logger, #<<)

Yield Returns:

  • (String)

    added to message

Since:

  • 2.0.0



120
121
122
# 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) ⇒ Logger, ...

Logger instance, found using ‘options`, `@logger`, or `@options`

Parameters:

  • options (Hash{Symbol => Object})

Options Hash (**options):

Returns:

Since:

  • 2.0.0



20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# 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