Class: YARD::Logger

Inherits:
Logger
  • Object
show all
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.

Constant Summary collapse

PROGRESS_INDICATORS =

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

Since:

  • 0.8.2

["\u230C", "\u230D", "\u230E", "\u230F"]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(pipe, *args) ⇒ Logger

Creates a new logger



41
42
43
44
45
46
47
48
49
50
 
# File 'lib/yard/logging.rb', line 41

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

Instance Attribute Details

#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).



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

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).



25
26
27
28
29
30
31
 
# File 'lib/yard/logging.rb', line 25

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

Class Method Details

.instance(pipe = STDOUT) ⇒ Logger

The logger instance

Returns:

  • (Logger) —

    the logger instance



36
37
38
 
# File 'lib/yard/logging.rb', line 36

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



139
140
141
142
143
144
 
# File 'lib/yard/logging.rb', line 139

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



68
69
70
71
72
73
 
# File 'lib/yard/logging.rb', line 68

def capture(msg, nontty_log = :debug, &block)
  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



106
107
108
109
110
 
# File 'lib/yard/logging.rb', line 106

def clear_progress
  return unless show_progress
  print_no_newline("\e[?25h\e[2K")
  @progress_msg = nil
end

#debug(*args) ⇒ Object

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



54
55
56
57
 
# File 'lib/yard/logging.rb', line 54

def debug(*args)
  self.level = DEBUG if $DEBUG
  super
end

#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



164
165
166
167
168
169
 
# File 'lib/yard/logging.rb', line 164

def enter_level(new_level = level, &block)
  old_level, self.level = level, new_level
  yield
ensure
  self.level = old_level
end

#io ⇒ IO

Returns the IO object being logged to.

Returns:

  • (IO) —

    the IO object being logged to

Since:

  • 0.8.2



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

def io; @logdev end

#io=(pipe) ⇒ Object 



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

def io=(pipe) @logdev = pipe 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



128
129
130
131
 
# File 'lib/yard/logging.rb', line 128

def print(msg = '')
  clear_line
  print_no_newline(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



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/yard/logging.rb', line 84

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
    @progress_indicator += 1
    @progress_indicator %= PROGRESS_INDICATORS.size
  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



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

def puts(msg = '')
  print("#{msg}\n")
end

#warn_no_continuations ⇒ void

Deprecated.

Continuations are no longer needed by YARD 0.8.0+.

This method returns an undefined value.

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



152
153
 
# File 'lib/yard/logging.rb', line 152

def warn_no_continuations
end