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

%w(       )

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(pipe, *args) ⇒ Logger

Creates a new logger


43
44
45
46
47
48
49
50
51
52
53
54
55
# 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

Instance Attribute Details

#show_backtracesBoolean


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

def show_backtraces; @show_backtraces || level == DEBUG end

#show_progressBoolean


27
28
29
30
31
32
33
# 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

#warnedObject

Returns the value of attribute warned


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

def warned
  @warned
end

Class Method Details

.instance(pipe = STDOUT) ⇒ Logger

The logger instance


38
39
40
# File 'lib/yard/logging.rb', line 38

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.


154
155
156
157
158
159
# 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) { ... } ⇒ 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.

Yields:

  • a block of arbitrary code to benchmark


80
81
82
83
84
85
# File 'lib/yard/logging.rb', line 80

def capture(msg, nontty_log = :debug)
  progress(msg, nontty_log)
  yield
ensure
  clear_progress
end

#clear_progressvoid

This method returns an undefined value.

Clears the progress indicator in the TTY display.

Since:

  • 0.8.2


121
122
123
124
125
# 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) ⇒ Object

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


59
60
61
62
# File 'lib/yard/logging.rb', line 59

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

Yields:

  • the block with the logger temporarily set to new_level


179
180
181
182
183
184
185
# 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

#ioIO

Returns the IO object being logged to

Since:

  • 0.8.2


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

def io; @logdev end

#io=(pipe) ⇒ Object


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

def io=(pipe) @logdev = pipe end

This method returns an undefined value.

Displays an unformatted line to the logger output stream.

Since:

  • 0.8.2


143
144
145
146
# File 'lib/yard/logging.rb', line 143

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.

Since:

  • 0.8.2


96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
# 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 = '') ⇒ void

This method returns an undefined value.

Displays an unformatted line to the logger output stream, adding a newline.

Since:

  • 0.8.2


132
133
134
# File 'lib/yard/logging.rb', line 132

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

#warn(*args) ⇒ Object

Remembers when a warning occurs and writes a warning message.


65
66
67
68
# File 'lib/yard/logging.rb', line 65

def warn(*args)
  self.warned = true
  super
end

#warn_no_continuationsvoid

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.


167
168
# File 'lib/yard/logging.rb', line 167

def warn_no_continuations
end