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

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

Public Class Methods

instance(pipe = STDOUT) click to toggle source

The logger instance @return [Logger] the logger instance

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

Creates a new logger

Calls superclass method
# File lib/yard/logging.rb, line 43
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)
  self.warned = false
  @progress_indicator = 0
  @mutex = Mutex.new
  @progress_msg = nil
  @progress_last_update = Time.now
end

Public Instance Methods

<<(msg = '')
Also aliased as: print_no_newline
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 154
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 80
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 121
def clear_progress
  return unless show_progress
  print_no_newline("\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.

Calls superclass method
# File lib/yard/logging.rb, line 59
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 179
def enter_level(new_level = level)
  old_level = level
  self.level = new_level
  yield
ensure
  self.level = old_level
end
io() click to toggle source

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

# File lib/yard/logging.rb, line 17
def io; @logdev end
io=(pipe) click to toggle source
# File lib/yard/logging.rb, line 18
def io=(pipe) @logdev = pipe 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: <<
print_no_newline(msg = '')
Alias for: <<
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 96
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 132
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 22
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 27
def show_progress
  return false if YARD.ruby18? # threading is too ineffective for progress support
  return false if YARD.windows? # windows has poor ANSI 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(*args) click to toggle source

Remembers when a warning occurs and writes a warning message.

Calls superclass method
# File lib/yard/logging.rb, line 65
def warn(*args)
  self.warned = true
  super
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 167
def warn_no_continuations
end

Private Instance Methods

add(*args) click to toggle source

Override this internal Logger method to clear line

Calls superclass method
# File lib/yard/logging.rb, line 190
def add(*args)
  clear_line
  super(*args)
end
clear_line() click to toggle source
# File lib/yard/logging.rb, line 195
def clear_line
  return unless @progress_msg
  print_no_newline("\e[2K\r")
end
format_log(sev, _time, _prog, msg) click to toggle source

Log format (from Logger implementation). Used by Logger internally

# File lib/yard/logging.rb, line 201
def format_log(sev, _time, _prog, msg)
  "[#{sev.downcase}]: #{msg}\n"
end