class YARD::Logger

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

Constants

PROGRESS_INDICATORS

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

Attributes

io[RW]

@return [IO] the IO object being logged to @since 0.8.2

level[RW]

@return [DEBUG, INFO, WARN, ERROR, FATAL, UNKNOWN] the logging level

show_backtraces[W]
show_progress[W]
warned[RW]

@return [Boolean] whether a warn message has been emitted. Used for status tracking.

Public Class Methods

create_log_method(name) click to toggle source

@!macro [attach] logger.create_log_method

@method $1(message)
Logs a message with the $1 severity level.
@param message [String] the message to log
@see #log
@return [void]

@private

# File lib/yard/logging.rb, line 101
def self.create_log_method(name)
  severity = Severity.const_get(name.to_s.upcase)
  define_method(name) { |message| log(severity, message) }
end
instance(pipe = STDOUT) click to toggle source

The logger instance @return [Logger] the logger instance

# File lib/yard/logging.rb, line 76
def self.instance(pipe = STDOUT)
  @logger ||= new(pipe)
end
new(pipe, *args) click to toggle source

Creates a new logger @private

# File lib/yard/logging.rb, line 82
def initialize(pipe, *args)
  self.io = pipe
  self.show_backtraces = true
  self.show_progress = false
  self.level = WARN
  self.warned = false
  @progress_indicator = 0
  @mutex = Mutex.new
  @progress_msg = nil
  @progress_last_update = Time.now
end

Public Instance Methods

<<(msg = '')
Alias for: print
backtrace(exc, level_meth = :error) click to toggle source

Prints the backtrace exc to the logger as error data.

@param [Array<String>] exc the backtrace list @param [Symbol] level_meth the level to log backtrace at @return [void]

# 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) { || ... } click to toggle source

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

@todo Implement capture storage for reporting of benchmarks @param [String] msg the message to display @param [Symbol, nil] nontty_log the level to log as if the output

stream is not a TTY. Use +nil+ for no alternate logging.

@yield a block of arbitrary code to benchmark @return [void]

# File lib/yard/logging.rb, line 234
def capture(msg, nontty_log = :debug)
  progress(msg, nontty_log)
  yield
ensure
  clear_progress
end
clear_progress() click to toggle source

Clears the progress indicator in the TTY display. @return [void] @since 0.8.2

# File lib/yard/logging.rb, line 186
def clear_progress
  return unless show_progress
  io.write("\e[?25h\e[2K")
  @progress_msg = nil
end
enter_level(new_level = level) { || ... } click to toggle source

Sets the logger level for the duration of the block

@example

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

@param [Fixnum] new_level the logger level for the duration of the block.

values can be found in Ruby's Logger class.

@yield the block with the logger temporarily set to new_level

# 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
log(severity, message) click to toggle source

Logs a message with a given severity @param severity [DEBUG, INFO, WARN, ERROR, FATAL, UNKNOWN] the severity level @param message [String] the message to log

# 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 = '') click to toggle source

Displays an unformatted line to the logger output stream. @param [String] msg the message to display @return [void] @since 0.8.2

Also aliased as: <<
progress(msg, nontty_log = :debug) click to toggle source

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.

@param [String] msg the message to log @param [Symbol, nil] nontty_log the level to log as if the output

stream is not a TTY. Use +nil+ for no alternate logging.

@return [void] @since 0.8.2

# 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 = '') click to toggle source

Displays an unformatted line to the logger output stream, adding a newline. @param [String] msg the message to display @return [void] @since 0.8.2

# File lib/yard/logging.rb, line 197
def puts(msg = '')
  print("#{msg}\n")
end
show_backtraces() click to toggle source

@return [Boolean] whether backtraces should be shown (by default

this is on).
# File lib/yard/logging.rb, line 53
def show_backtraces; @show_backtraces || level == DEBUG end
show_progress() click to toggle source

@return [Boolean] whether progress indicators should be shown when

logging CLIs (by default this is off).
# 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
warn_no_continuations() click to toggle source

Warns that the Ruby environment does not support continuations. Applies to JRuby, Rubinius and MacRuby. This warning will only display once per Ruby process.

@deprecated Continuations are no longer needed by YARD 0.8.0+. @return [void] @private

# File lib/yard/logging.rb, line 250
def warn_no_continuations
end

Private Instance Methods

clear_line() click to toggle source
# File lib/yard/logging.rb, line 255
def clear_line
  return unless @progress_msg
  io.write("\e[2K\r")
end