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

show_backtraces[W]
show_progress[W]

Public Class Methods

instance(pipe = STDOUT) click to toggle source

The logger instance @return [Logger] the logger instance

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

Creates a new logger

# File lib/yard/logging.rb, line 39
def initialize(pipe, *args)
  super(pipe, *args)
  self.io = pipe
  self.show_backtraces = true
  self.show_progress = false
  self.level = WARN
  self.formatter = method(:format_log)
  @progress_indicator = 0
  @mutex = Mutex.new
end

Public Instance Methods

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 126
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 66
def capture(msg, nontty_log = :debug, &block)
  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 106
def clear_progress
  return unless show_progress
  self << "\e[?25h\e[2K"
  @progress_msg = nil
end
debug(*args) click to toggle source

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

# File lib/yard/logging.rb, line 52
def debug(*args)
  self.level = DEBUG if $DEBUG
  super
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 151
def enter_level(new_level = level, &block)
  old_level, self.level = level, new_level
  yield
  self.level = old_level
end
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 82
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
  self << "\e[2K\e[?25l\e[1m#{icon}#{msg}\e[0m\r"
  @mutex.synchronize do
    @progress_msg = msg
    @progress_indicator += 1
    @progress_indicator = PROGRESS_INDICATORS.size
  end
  Thread.new do
    sleep(0.05)
    @mutex.synchronize do
      progress(msg + ".", nil) if @progress_msg == msg
    end
  end
end
puts(msg) click to toggle source

Displays an unformatted line to the logger output stream. Similar to the +#<<+ method, but adds a newline. @param [String] msg the message to display @return [void] @since 0.8.2

# File lib/yard/logging.rb, line 117
def puts(msg)
  self << "#{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 19
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 24
def show_progress
  return false if RUBY18 # threading is too ineffective for progress support
  return false unless io.tty? # no TTY support on IO
  return false if level > WARN # 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]

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