# Class: YARD::Logger

Inherits:
  Object
  - Object
  - YARD::Logger
  show all

Includes:
  Severity

Defined in:
  lib/yard/logging.rb

## Overview

Handles console logging for info, warnings and errors. Uses the stdlib Logger class in Ruby for all the backend logic.

## Defined Under Namespace

Modules: Severity

## Constant Summary collapse

PROGRESS_INDICATORS =

The list of characters displayed beside the progress bar to indicate “movement”.

Since:

- 0.8.2

      %w(⣷ ⣯ ⣟ ⡿ ⢿ ⣻ ⣽ ⣾)

### Constants included from Severity

Severity::DEBUG, Severity::ERROR, Severity::FATAL, Severity::INFO, Severity::UNKNOWN, Severity::WARN

## Instance Attribute Summary collapse

- #io ⇒ IO

  The IO object being logged to.

- #level ⇒ DEBUG, ...

  The logging level.

- #show_backtraces ⇒ Boolean

  Whether backtraces should be shown (by default this is on).

- #show_progress ⇒ Boolean

  Whether progress indicators should be shown when logging CLIs (by default this is off).

- #warned ⇒ Boolean

  Whether a warn message has been emitted.

## Constructor Methods collapse

- .instance(pipe = STDOUT) ⇒ Logger

  The logger instance.

## Logging Methods collapse

- #debug(message) ⇒ void

  Changes the debug level to DEBUG if $DEBUG is set and writes a debugging message.

- #error(message) ⇒ void

  Logs a message with the error severity level.

- #fatal(message) ⇒ void

  Logs a message with the fatal severity level.

- #info(message) ⇒ void

  Logs a message with the info severity level.

- #log(severity, message) ⇒ Object

  Logs a message with a given severity.

- #unknown(message) ⇒ void

  Logs a message with the unknown severity level.

- #warn(message) ⇒ void

  Remembers when a warning occurs and writes a warning message.

## Level Control Methods collapse

- #enter_level(new_level = level) { ... } ⇒ Object

  Sets the logger level for the duration of the block.

## Utility Printing Methods collapse

- #backtrace(exc, level_meth = :error) ⇒ void

  Prints the backtrace `exc` to the logger as error data.

- #clear_progress ⇒ void

  Clears the progress indicator in the TTY display.

- #print(msg = '') ⇒ void (also: #<<)

  Displays an unformatted line to the logger output stream.

- #progress(msg, nontty_log = :debug) ⇒ void

  Displays a progress indicator for a given message.

- #puts(msg = '') ⇒ void

  Displays an unformatted line to the logger output stream, adding a newline.

## Benchmarking Methods collapse

- #capture(msg, nontty_log = :debug) { ... } ⇒ void

  Captures the duration of a block of code for benchmark analysis.

## Instance Attribute Details

### #io ⇒ `IO`

Returns the IO object being logged to.

Returns:

- (`IO`) —

  the IO object being logged to

Since:

- 0.8.2

    49
    50
    51

    # File 'lib/yard/logging.rb', line 49

    def io
      @io
    end

### #level ⇒ `DEBUG`, ...

Returns the logging level.

Returns:

- (`DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`, `UNKNOWN`) —

  the logging level

    57
    58
    59

    # File 'lib/yard/logging.rb', line 57

    def level
      @level
    end

### #show_backtraces ⇒ `Boolean`

Returns whether backtraces should be shown (by default this is on).

Returns:

- (`Boolean`) —

  whether backtraces should be shown (by default this is on).

    53

    # File 'lib/yard/logging.rb', line 53

    def show_backtraces; @show_backtraces || level == DEBUG end

### #show_progress ⇒ `Boolean`

Returns whether progress indicators should be shown when logging CLIs (by default this is off).

Returns:

- (`Boolean`) —

  whether progress indicators should be shown when logging CLIs (by default this is off).

    64
    65
    66
    67
    68
    69

    # File 'lib/yard/logging.rb', line 64

    def show_progress
      return false if YARD.ruby18? # threading is too ineffective for progress support
      return false unless io.tty? # no TTY support on IO
      return false unless level > INFO # no progress in verbose/debug modes
      @show_progress
    end

### #warned ⇒ `Boolean`

Returns whether a warn message has been emitted. Used for status tracking.

Returns:

- (`Boolean`) —

  whether a warn message has been emitted. Used for status tracking.

    60
    61
    62

    # File 'lib/yard/logging.rb', line 60

    def warned
      @warned
    end

## Class Method Details

### .instance(pipe = STDOUT) ⇒ `Logger`

The logger instance

Returns:

- (`Logger`) —

  the logger instance

    76
    77
    78

    # File 'lib/yard/logging.rb', line 76

    def self.instance(pipe = STDOUT)
      @logger ||= new(pipe)
    end

## Instance Method Details

### #backtrace(exc, level_meth = :error) ⇒ `void`

This method returns an undefined value.

Prints the backtrace `exc` to the logger as error data.

Parameters:

- exc (`Array<String>`) —

  the backtrace list

- level_meth (`Symbol`) (defaults to: `:error`) —

  the level to log backtrace at

    216
    217
    218
    219
    220
    221

    # File 'lib/yard/logging.rb', line 216

    def backtrace(exc, level_meth = :error)
      return unless show_backtraces
      send(level_meth, "#{exc.class.class_name}: #{exc.message}")
      send(level_meth, "Stack trace:" +
        exc.backtrace[0..5].map {|x| "\n\t#{x}" }.join + "\n")
    end

### #capture(msg, nontty_log = :debug) { ... } ⇒ `void`

TODO:

Implement capture storage for reporting of benchmarks

This method returns an undefined value.

Captures the duration of a block of code for benchmark analysis. Also calls #progress on the message to display it to the user.

Parameters:

- msg (`String`) —

  the message to display

- nontty_log (`Symbol`, `nil`) (defaults to: `:debug`) —

  the level to log as if the output stream is not a TTY. Use `nil` for no alternate logging.

Yields:

- a block of arbitrary code to benchmark

    234
    235
    236
    237
    238
    239

    # File 'lib/yard/logging.rb', line 234

    def capture(msg, nontty_log = :debug)
      progress(msg, nontty_log)
      yield
    ensure
      clear_progress
    end

### #clear_progress ⇒ `void`

This method returns an undefined value.

Clears the progress indicator in the TTY display.

Since:

- 0.8.2

    186
    187
    188
    189
    190

    # File 'lib/yard/logging.rb', line 186

    def clear_progress
      return unless show_progress
      io.write("\e[?25h\e[2K")
      @progress_msg = nil
    end

### #debug(message) ⇒ `void`

This method returns an undefined value.

Changes the debug level to DEBUG if $DEBUG is set and writes a debugging message. Logs a message with the debug severity level.

Parameters:

- message (`String`) —

  the message to log

See Also:

- #log

    114

    # File 'lib/yard/logging.rb', line 114

    create_log_method :debug

### #enter_level(new_level = level) { ... } ⇒ `Object`

Sets the logger level for the duration of the block

#### Examples:

    log.enter_level(Logger::ERROR) do
      YARD.parse_string "def x; end"
    end

Parameters:

- new_level (`Fixnum`) (defaults to: `level`) —

  the logger level for the duration of the block. values can be found in Ruby’s Logger class.

Yields:

- the block with the logger temporarily set to `new_level`

    142
    143
    144
    145
    146
    147
    148

    # File 'lib/yard/logging.rb', line 142

    def enter_level(new_level = level)
      old_level = level
      self.level = new_level
      yield
    ensure
      self.level = old_level
    end

### #error(message) ⇒ `void`

This method returns an undefined value.

Logs a message with the error severity level.

Parameters:

- message (`String`) —

  the message to log

See Also:

- #log

    109

    # File 'lib/yard/logging.rb', line 109

    create_log_method :error

### #fatal(message) ⇒ `void`

This method returns an undefined value.

Logs a message with the fatal severity level.

Parameters:

- message (`String`) —

  the message to log

See Also:

- #log

    110

    # File 'lib/yard/logging.rb', line 110

    create_log_method :fatal

### #info(message) ⇒ `void`

This method returns an undefined value.

Logs a message with the info severity level.

Parameters:

- message (`String`) —

  the message to log

See Also:

- #log

    108

    # File 'lib/yard/logging.rb', line 108

    create_log_method :info

### #log(severity, message) ⇒ `Object`

Logs a message with a given severity

Parameters:

- severity (`DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`, `UNKNOWN`) —

  the severity level

- message (`String`) —

  the message to log

    122
    123
    124
    125
    126
    127
    128
    129

    # File 'lib/yard/logging.rb', line 122

    def log(severity, message)
      self.level = DEBUG if $DEBUG
      return unless severity >= level

      self.warned = true if severity == WARN
      clear_line
      puts "[#{SEVERITIES[severity].to_s.downcase}]: #{message}"
    end

### #print(msg = '') ⇒ `void` Also known as: <<

This method returns an undefined value.

Displays an unformatted line to the logger output stream.

Parameters:

- msg (`String`) (defaults to: `''`) —

  the message to display

Since:

- 0.8.2

    205
    206
    207
    208

    # File 'lib/yard/logging.rb', line 205

    def print(msg = '')
      clear_line
      io.write(msg)
    end

### #progress(msg, nontty_log = :debug) ⇒ `void`

This method returns an undefined value.

Displays a progress indicator for a given message. This progress report is only displayed on TTY displays, otherwise the message is passed to the `nontty_log` level.

Parameters:

- msg (`String`) —

  the message to log

- nontty_log (`Symbol`, `nil`) (defaults to: `:debug`) —

  the level to log as if the output stream is not a TTY. Use `nil` for no alternate logging.

Since:

- 0.8.2

    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181

    # File 'lib/yard/logging.rb', line 161

    def progress(msg, nontty_log = :debug)
      send(nontty_log, msg) if nontty_log
      return unless show_progress
      icon = ""
      if defined?(::Encoding)
        icon = PROGRESS_INDICATORS[@progress_indicator] + " "
      end
      @mutex.synchronize do
        print("\e[2K\e[?25l\e[1m#{icon}#{msg}\e[0m\r")
        @progress_msg = msg
        if Time.now - @progress_last_update > 0.2
          @progress_indicator += 1
          @progress_indicator %= PROGRESS_INDICATORS.size
          @progress_last_update = Time.now
        end
      end
      Thread.new do
        sleep(0.05)
        progress(msg + ".", nil) if @progress_msg == msg
      end
    end

### #puts(msg = '') ⇒ `void`

This method returns an undefined value.

Displays an unformatted line to the logger output stream, adding a newline.

Parameters:

- msg (`String`) (defaults to: `''`) —

  the message to display

Since:

- 0.8.2

    197
    198
    199

    # File 'lib/yard/logging.rb', line 197

    def puts(msg = '')
      print("#{msg}\n")
    end

### #unknown(message) ⇒ `void`

This method returns an undefined value.

Logs a message with the unknown severity level.

Parameters:

- message (`String`) —

  the message to log

See Also:

- #log

    111

    # File 'lib/yard/logging.rb', line 111

    create_log_method :unknown

### #warn(message) ⇒ `void`

This method returns an undefined value.

Remembers when a warning occurs and writes a warning message. Logs a message with the warn severity level.

Parameters:

- message (`String`) —

  the message to log

See Also:

- #log

    117

    # File 'lib/yard/logging.rb', line 117

    create_log_method :warn