123456789_123456789_123456789_123456789_123456789_

Class: YARD::Logger

Relationships & Source Files
Namespace Children
Modules:
Severity
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, Severity
Inherits: Object
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 45 
    %w(⣷ ⣯ ⣟ ⡿ ⢿ ⣻ ⣽ ⣾)

Severity - Included

DEBUG, ERROR, FATAL, INFO, SEVERITIES, UNKNOWN, WARN

Constructor Methods

Logging Methods

Level Control Methods

Utility Printing Methods

Benchmarking Methods

Instance Attribute Summary

Instance Method Summary

Class Method Details

.create_log_method(name)

This method is for internal use only.
[ GitHub ] 

  


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



def self.create_log_method(name)
  severity = Severity.const_get(name.to_s.upcase)
  define_method(name) { |message| log(severity, message) }
end


  








  

    .instance(pipe = STDOUT)  ⇒ Logger 
  



  

    
The logger instance


  





  
Returns:


    
  
  • 
    (Logger)
—    
    the logger instance
    

    
  
    • 





  [ GitHub ]


  

  


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



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 49



attr_accessor :io


  








  

    #level  ⇒ DEBUG, ...  (rw)
  



  

    
  





  
Returns:


    
  
  • 
    (DEBUG, INFO, WARN, ERROR, FATAL, UNKNOWN)
—    
    the logging level
    

    
  
    • 





  [ GitHub ]


  

  


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



attr_accessor :level


  








  

    #show_backtraces  ⇒ Boolean  (rw)
  



  

    
  





  
Returns:


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

    
  
    • 





  [ GitHub ]


  

  


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



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


  








  

    #show_backtraces=(value)   (rw)
  

  [ GitHub ]


  

  


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



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 64



def show_progress
  return false if YARD.ruby18? # threading is too ineffective for progress 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 70



attr_writer :show_progress


  








  

    #warned  ⇒ Boolean  (rw)
  



  

    
  





  
Returns:


    
  
  • 
    (Boolean)
—    
    whether a warn message has been emitted. Used for status tracking.
    

    
  
    • 





  [ GitHub ]


  

  


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



attr_accessor :warned


  







Instance Method Details



  

    #<<(msg = '')  
  



  

    
Alias for #print.


  



  [ GitHub ]


  

  


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



alias << print


  








  

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



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 234



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 255



def clear_line
  return unless @progress_msg
  io.write("\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 186



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


  








  

    #debug(message)  ⇒ void 
  



  

    
This method returns an undefined value.
Changes the debug level to DEBUG if $DEBUG is set and writes a debugging message.
Logs a message with the debug severity level.


  





  
Parameters:


    
  
  • 
    message
    (String)
—    
    the message to log
    

    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


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



create_log_method :debug


  








  

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



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


  








  

    #error(message)  ⇒ void 
  



  

    
This method returns an undefined value.
Logs a message with the error severity level.


  





  
Parameters:


    
  
  • 
    message
    (String)
—    
    the message to log
    

    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


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



create_log_method :error


  








  

    #fatal(message)  ⇒ void 
  



  

    
This method returns an undefined value.
Logs a message with the fatal severity level.


  





  
Parameters:


    
  
  • 
    message
    (String)
—    
    the message to log
    

    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


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



create_log_method :fatal


  








  

    #info(message)  ⇒ void 
  



  

    
This method returns an undefined value.
Logs a message with the info severity level.


  





  
Parameters:


    
  
  • 
    message
    (String)
—    
    the message to log
    

    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


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



create_log_method :info


  








  

    #log(severity, message)  
  



  

    
Logs a message with a given severity


  





  
Parameters:


    
  
  • 
    severity
    (DEBUG, INFO, WARN, ERROR, FATAL, UNKNOWN)
—    
    the severity level
    

    
  
    • 
  
  • 
    message
    (String)
—    
    the message to log
    

    
  
    • 





  [ GitHub ]


  

  


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



def log(severity, message)
  self.level = DEBUG if $DEBUG
  return unless severity >= level

  self.warned = true if severity == WARN
  clear_line
  puts "[#{SEVERITIES[severity].to_s.downcase}]: #{message}"
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
    

    
  
    • 





  [ GitHub ]


  

  


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



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 197



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


  








  

    #unknown(message)  ⇒ void 
  



  

    
This method returns an undefined value.
Logs a message with the unknown severity level.


  





  
Parameters:


    
  
  • 
    message
    (String)
—    
    the message to log
    

    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


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



create_log_method :unknown


  








  

    #warn(message)  ⇒ void 
  



  

    
This method returns an undefined value.
Remembers when a warning occurs and writes a warning message.
Logs a message with the warn severity level.


  





  
Parameters:


    
  
  • 
    message
    (String)
—    
    the message to log
    

    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


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



create_log_method :warn


  








  

    #warn_no_continuations  ⇒ void 
  

  

    This method is for internal use only.
  



  

    
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 250



def warn_no_continuations
end