Class: YARD::Logger

Inherits:
Object
  • Object
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

Constructor Methods collapse

Logging Methods collapse

Level Control Methods collapse

Utility Printing Methods collapse

Benchmarking Methods collapse

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:



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:



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:



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:



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:



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

create_log_method :info

#log(severity, message) ⇒ Object

Logs a message with a given severity

Parameters:



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:



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:



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

create_log_method :warn