Class: YARD::Logger

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, Logger
Instance Chain: self, Logger
Inherits:	Logger Object Logger YARD::Logger
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

PROGRESS_INDICATORS =

The list of characters displayed beside the progress bar to indicate "movement".
Since:
- 0.8.2
# File 'lib/yard/logging.rb', line 13
```
%w(⣷ ⣯ ⣟ ⡿ ⢿ ⣻ ⣽ ⣾)
```

Class Method Summary

.instance(pipe = STDOUT) ⇒ Logger

The logger instance.
.new(pipe, *args) ⇒ Logger constructor

Creates a new logger.

Instance Method Summary

#<<(msg = '')

Alias for #print.
#backtrace(exc, level_meth = :error) ⇒ void

Prints the backtrace exc to the logger as error data.
#capture(msg, nontty_log = :debug) { ... } ⇒ void

Captures the duration of a block of code for benchmark analysis.
#clear_progress ⇒ void

Clears the progress indicator in the TTY display.
#debug(*args)

Changes the debug level to DEBUG if $DEBUG is set and writes a debugging message.
#enter_level(new_level = level) { ... }

Sets the logger level for the duration of the block.
#print(msg = '') ⇒ void (also: #<<)

Displays an unformatted line to the logger output stream.
#progress(msg, nontty_log = :debug) ⇒ void

Displays a progress indicator for a given message.
#puts(msg = '') ⇒ void

Displays an unformatted line to the logger output stream, adding a newline.
#warn(*args)

Remembers when a warning occurs and writes a warning message.
#warn_no_continuations ⇒ void deprecated Deprecated.
Continuations are no longer needed by ::YARD 0.8.0+.
#add(*args) private

Override this internal Logger method to clear line.
#clear_line private
#format_log(sev, _time, _prog, msg) private

Log format (from Logger implementation).
#print_no_newline private

Constructor Details

.new(pipe, *args) ⇒ `Logger`

Creates a new logger

[ GitHub ]

# 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

Class Method Details

.instance(pipe = STDOUT) ⇒ `Logger`

The logger instance

Returns:

(Logger) —
the logger instance

[ GitHub ]

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


def self.instance(pipe = STDOUT)
  @logger ||= new(pipe)
end

Instance Attribute Details

#io ⇒ `IO` (rw)

Returns:

(IO) —
the IO object being logged to

Since:

0.8.2

[ GitHub ]

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


def io; @logdev end

#io=(pipe) (rw)

[ GitHub ]

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


def io=(pipe) @logdev = pipe end

#show_backtraces ⇒ `Boolean` (rw)

Returns:

(Boolean) —
whether backtraces should be shown (by default this is on).

[ GitHub ]

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


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

#show_backtraces=(value) (rw)

[ GitHub ]

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


attr_writer :show_backtraces

#show_progress ⇒ `Boolean` (rw)

Returns:

(Boolean) —
whether progress indicators should be shown when logging CLIs (by default this is off).

[ GitHub ]

# 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

#show_progress=(value) (rw)

[ GitHub ]

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


attr_writer :show_progress

#warned (rw)

[ GitHub ]

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


attr_accessor :warned

Instance Method Details

#<<(msg = '')

Alias for #print.

[ GitHub ]

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


alias << print

#add(*args) (private)

Override this internal Logger method to clear line

[ GitHub ]

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


def add(*args)
  clear_line
  super(*args)
end

#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

[ GitHub ]

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

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

[ GitHub ]

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


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

#clear_line (private)

[ GitHub ]

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


def clear_line
  return unless @progress_msg
  print_no_newline("\e[2K\r")
end

#clear_progress ⇒ `void`

This method returns an undefined value.

Clears the progress indicator in the TTY display.

Since:

0.8.2

[ GitHub ]

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

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

[ GitHub ]

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


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

#enter_level(new_level = level) { ... }

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

[ GitHub ]

# 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

#format_log(sev, _time, _prog, msg) (private)

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

[ GitHub ]

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


def format_log(sev, _time, _prog, msg)
  "[#{sev.downcase}]: #{msg}\n"
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

[ GitHub ]

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


def print(msg = '')
  clear_line
  print_no_newline(msg)
end

#print_no_newline (private)

[ GitHub ]

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


alias print_no_newline <<

#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

[ GitHub ]

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

Parameters:

msg (String) (defaults to: '') —
the message to display

Since:

0.8.2

[ GitHub ]

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


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

#warn(*args)

Remembers when a warning occurs and writes a warning message.

[ GitHub ]

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


def warn(*args)
  self.warned = true
  super
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.

[ GitHub ]

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


def warn_no_continuations
end

Class: YARD::Logger

Overview

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(pipe, *args) ⇒ Logger

Class Method Details

.instance(pipe = STDOUT) ⇒ Logger

Instance Attribute Details

#io ⇒ IO (rw)

#io=(pipe) (rw)

#show_backtraces ⇒ Boolean (rw)

#show_backtraces=(value) (rw)

#show_progress ⇒ Boolean (rw)

#show_progress=(value) (rw)

#warned (rw)

Instance Method Details

#<<(msg = '')

#add(*args) (private)

#backtrace(exc, level_meth = :error) ⇒ void

#capture(msg, nontty_log = :debug) { ... } ⇒ void

#clear_line (private)

#clear_progress ⇒ void

#debug(*args)

#enter_level(new_level = level) { ... }

#format_log(sev, _time, _prog, msg) (private)

#print(msg = '') ⇒ void Also known as: #<<

#print_no_newline (private)

#progress(msg, nontty_log = :debug) ⇒ void

#puts(msg = '') ⇒ void

#warn(*args)

#warn_no_continuations ⇒ void

.new(pipe, *args) ⇒ `Logger`

.instance(pipe = STDOUT) ⇒ `Logger`

#io ⇒ `IO` (rw)

#show_backtraces ⇒ `Boolean` (rw)

#show_progress ⇒ `Boolean` (rw)

#backtrace(exc, level_meth = :error) ⇒ `void`

#capture(msg, nontty_log = :debug) { ... } ⇒ `void`

#clear_progress ⇒ `void`

#print(msg = '') ⇒ `void` Also known as: #<<

#progress(msg, nontty_log = :debug) ⇒ `void`

#puts(msg = '') ⇒ `void`

#warn_no_continuations ⇒ `void`