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
Public Class Methods
The logger instance @return [Logger] the logger instance
# File lib/yard/logging.rb, line 38 def self.instance(pipe = STDOUT) @logger ||= new(pipe) end
Creates a new logger
# 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
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
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
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
Changes the debug level to DEBUG if $DEBUG is set and writes a debugging message.
# File lib/yard/logging.rb, line 59 def debug(*args) self.level = DEBUG if $DEBUG super end
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
@return [IO] the IO object being logged to @since 0.8.2
# File lib/yard/logging.rb, line 17 def io; @logdev end
# File lib/yard/logging.rb, line 18 def io=(pipe) @logdev = pipe end
Displays an unformatted line to the logger output stream. @param [String] msg the message to display @return [void] @since 0.8.2
# File lib/yard/logging.rb, line 143 def print(msg = '') clear_line print_no_newline(msg) end
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
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
@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
@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
Remembers when a warning occurs and writes a warning message.
# File lib/yard/logging.rb, line 65 def warn(*args) self.warned = true super end
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
Override this internal Logger
method to clear line
# File lib/yard/logging.rb, line 190 def add(*args) clear_line super(*args) end
# File lib/yard/logging.rb, line 195 def clear_line return unless @progress_msg print_no_newline("\e[2K\r") end