yard 0.9.18 → 0.9.23

data/lib/yard/i18n/text.rb

@@ -1,173 +1,173 @@
-# frozen_string_literal: true
-module YARD
-  module I18n
-    # Provides some convenient features for translating a text.
-    class Text
-      # Creates a text object that has translation related features for
-      # the input text.
-      #
-      # @param [#each_line] input a text to be translated.
-      # @option options [Boolean] :have_header (false) whether the
-      #   input text has header or not.
-      def initialize(input, options = {})
-        @input = input
-        @options = options
-      end
-
-      # Extracts translation target messages from +@input+.
-      #
-      # @yield [:attribute, name, value, line_no] the block that
-      #   receives extracted an attribute in header. It may called many
-      #   times.
-      # @yieldparam [String] name the name of extracted attribute.
-      # @yieldparam [String] value the value of extracted attribute.
-      # @yieldparam [Integer] line_no the defined line number of extracted
-      #   attribute.
-      # @yield [:paragraph, text, start_line_no] the block that
-      #   receives extracted a paragraph in body. Paragraph is a text
-      #   block separated by one or more empty lines. Empty line is a
-      #   line that contains only zero or more whitespaces. It may
-      #   called many times.
-      # @yieldparam [String] text the text of extracted paragraph.
-      # @yieldparam [Integer] start_line_no the start line number of
-      #   extracted paragraph.
-      # @return [void]
-      def extract_messages
-        parse do |part|
-          case part[:type]
-          when :markup, :empty_line
-            # ignore
-          when :attribute
-            yield(:attribute, part[:name], part[:value], part[:line_no])
-          when :paragraph
-            yield(:paragraph, part[:paragraph], part[:line_no])
-          end
-        end
-      end
-
-      # Translates into +locale+.
-      #
-      # @param [Locale] locale the translation target locale.
-      # @return [String] translated text.
-      def translate(locale)
-        translated_text = String.new("")
-        parse do |part|
-          case part[:type]
-          when :markup
-            translated_text << part[:line]
-          when :attribute
-            prefix = "#{part[:prefix]}#{part[:name]}#{part[:infix]}"
-            value = locale.translate(part[:value])
-            suffix = part[:suffix]
-            translated_text << "#{prefix}#{value}#{suffix}"
-          when :paragraph
-            translated_text << locale.translate(part[:paragraph])
-          when :empty_line
-            translated_text << part[:line]
-          else
-            raise "should not reach here: unexpected type: #{type}"
-          end
-        end
-        translated_text
-      end
-
-      private
-
-      def parse(&block)
-        paragraph = String.new("")
-        paragraph_start_line = 0
-        line_no = 0
-        in_header = @options[:have_header]
-
-        @input.each_line do |line|
-          line_no += 1
-          if in_header
-            case line
-            when /^#!\S+\s*$/
-              if line_no == 1
-                emit_markup_event(line, line_no, &block)
-              else
-                in_header = false
-              end
-            when /^(\s*#\s*@)(\S+)(\s*)(.+?)(\s*)$/
-              emit_attribute_event(Regexp.last_match, line_no, &block)
-            else
-              in_header = false
-              if line.strip.empty?
-                emit_empty_line_event(line, line_no, &block)
-                next
-              end
-            end
-            next if in_header
-          end
-
-          case line
-          when /^\s*$/
-            if paragraph.empty?
-              emit_empty_line_event(line, line_no, &block)
-            else
-              paragraph << line
-              emit_paragraph_event(paragraph, paragraph_start_line, line_no,
-                                   &block)
-              paragraph = String.new("")
-            end
-          else
-            paragraph_start_line = line_no if paragraph.empty?
-            paragraph << line
-          end
-        end
-
-        unless paragraph.empty?
-          emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
-        end
-      end
-
-      def emit_markup_event(line, line_no)
-        part = {
-          :type => :markup,
-          :line => line,
-          :line_no => line_no
-        }
-        yield(part)
-      end
-
-      def emit_attribute_event(match_data, line_no)
-        part = {
-          :type => :attribute,
-          :prefix => match_data[1],
-          :name => match_data[2],
-          :infix => match_data[3],
-          :value => match_data[4],
-          :suffix => match_data[5],
-          :line_no => line_no
-        }
-        yield(part)
-      end
-
-      def emit_empty_line_event(line, line_no)
-        part = {
-          :type => :empty_line,
-          :line => line,
-          :line_no => line_no
-        }
-        yield(part)
-      end
-
-      def emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
-        paragraph_part = {
-          :type => :paragraph,
-          :line_no => paragraph_start_line
-        }
-        match_data = /(\s*)\z/.match(paragraph)
-        if match_data
-          paragraph_part[:paragraph] = match_data.pre_match
-          yield(paragraph_part)
-          emit_empty_line_event(match_data[1], line_no, &block)
-        else
-          paragraph_part[:paragraph] = paragraph
-          yield(paragraph_part)
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+module YARD
+  module I18n
+    # Provides some convenient features for translating a text.
+    class Text
+      # Creates a text object that has translation related features for
+      # the input text.
+      #
+      # @param [#each_line] input a text to be translated.
+      # @option options [Boolean] :have_header (false) whether the
+      #   input text has header or not.
+      def initialize(input, options = {})
+        @input = input
+        @options = options
+      end
+
+      # Extracts translation target messages from +@input+.
+      #
+      # @yield [:attribute, name, value, line_no] the block that
+      #   receives extracted an attribute in header. It may called many
+      #   times.
+      # @yieldparam [String] name the name of extracted attribute.
+      # @yieldparam [String] value the value of extracted attribute.
+      # @yieldparam [Integer] line_no the defined line number of extracted
+      #   attribute.
+      # @yield [:paragraph, text, start_line_no] the block that
+      #   receives extracted a paragraph in body. Paragraph is a text
+      #   block separated by one or more empty lines. Empty line is a
+      #   line that contains only zero or more whitespaces. It may
+      #   called many times.
+      # @yieldparam [String] text the text of extracted paragraph.
+      # @yieldparam [Integer] start_line_no the start line number of
+      #   extracted paragraph.
+      # @return [void]
+      def extract_messages
+        parse do |part|
+          case part[:type]
+          when :markup, :empty_line
+            # ignore
+          when :attribute
+            yield(:attribute, part[:name], part[:value], part[:line_no])
+          when :paragraph
+            yield(:paragraph, part[:paragraph], part[:line_no])
+          end
+        end
+      end
+
+      # Translates into +locale+.
+      #
+      # @param [Locale] locale the translation target locale.
+      # @return [String] translated text.
+      def translate(locale)
+        translated_text = String.new("")
+        parse do |part|
+          case part[:type]
+          when :markup
+            translated_text << part[:line]
+          when :attribute
+            prefix = "#{part[:prefix]}#{part[:name]}#{part[:infix]}"
+            value = locale.translate(part[:value])
+            suffix = part[:suffix]
+            translated_text << "#{prefix}#{value}#{suffix}"
+          when :paragraph
+            translated_text << locale.translate(part[:paragraph])
+          when :empty_line
+            translated_text << part[:line]
+          else
+            raise "should not reach here: unexpected type: #{type}"
+          end
+        end
+        translated_text
+      end
+
+      private
+
+      def parse(&block)
+        paragraph = String.new("")
+        paragraph_start_line = 0
+        line_no = 0
+        in_header = @options[:have_header]
+
+        @input.each_line do |line|
+          line_no += 1
+          if in_header
+            case line
+            when /^#!\S+\s*$/
+              if line_no == 1
+                emit_markup_event(line, line_no, &block)
+              else
+                in_header = false
+              end
+            when /^(\s*#\s*@)(\S+)(\s*)(.+?)(\s*)$/
+              emit_attribute_event(Regexp.last_match, line_no, &block)
+            else
+              in_header = false
+              if line.strip.empty?
+                emit_empty_line_event(line, line_no, &block)
+                next
+              end
+            end
+            next if in_header
+          end
+
+          case line
+          when /^\s*$/
+            if paragraph.empty?
+              emit_empty_line_event(line, line_no, &block)
+            else
+              paragraph << line
+              emit_paragraph_event(paragraph, paragraph_start_line, line_no,
+                                   &block)
+              paragraph = String.new("")
+            end
+          else
+            paragraph_start_line = line_no if paragraph.empty?
+            paragraph << line
+          end
+        end
+
+        unless paragraph.empty?
+          emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
+        end
+      end
+
+      def emit_markup_event(line, line_no)
+        part = {
+          :type => :markup,
+          :line => line,
+          :line_no => line_no
+        }
+        yield(part)
+      end
+
+      def emit_attribute_event(match_data, line_no)
+        part = {
+          :type => :attribute,
+          :prefix => match_data[1],
+          :name => match_data[2],
+          :infix => match_data[3],
+          :value => match_data[4],
+          :suffix => match_data[5],
+          :line_no => line_no
+        }
+        yield(part)
+      end
+
+      def emit_empty_line_event(line, line_no)
+        part = {
+          :type => :empty_line,
+          :line => line,
+          :line_no => line_no
+        }
+        yield(part)
+      end
+
+      def emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
+        paragraph_part = {
+          :type => :paragraph,
+          :line_no => paragraph_start_line
+        }
+        match_data = /(\s*)\z/.match(paragraph)
+        if match_data
+          paragraph_part[:paragraph] = match_data.pre_match
+          yield(paragraph_part)
+          emit_empty_line_event(match_data[1], line_no, &block)
+        else
+          paragraph_part[:paragraph] = paragraph
+          yield(paragraph_part)
+        end
+      end
+    end
+  end
+end

data/lib/yard/logging.rb

@@ -1,205 +1,205 @@
-# encoding: utf-8
-# frozen_string_literal: true
-require 'logger'
-require 'thread'
-
-module YARD
-  # Handles console logging for info, warnings and errors.
-  # Uses the stdlib Logger class in Ruby for all the backend logic.
-  class Logger < ::Logger
-    # The list of characters displayed beside the progress bar to indicate
-    # "movement".
-    # @since 0.8.2
-    PROGRESS_INDICATORS = %w(⣷ ⣯ ⣟ ⡿ ⢿ ⣻ ⣽ ⣾)
-
-    # @return [IO] the IO object being logged to
-    # @since 0.8.2
-    def io; @logdev end
-    def io=(pipe) @logdev = pipe end
-
-    # @return [Boolean] whether backtraces should be shown (by default
-    #   this is on).
-    def show_backtraces; @show_backtraces || level == DEBUG end
-    attr_writer :show_backtraces
-
-    # @return [Boolean] whether progress indicators should be shown when
-    #   logging CLIs (by default this is off).
-    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
-    attr_writer :show_progress
-
-    # The logger instance
-    # @return [Logger] the logger instance
-    def self.instance(pipe = STDOUT)
-      @logger ||= new(pipe)
-    end
-
-    # Creates a new logger
-    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
-
-    # Changes the debug level to DEBUG if $DEBUG is set
-    # and writes a debugging message.
-    def debug(*args)
-      self.level = DEBUG if $DEBUG
-      super
-    end
-
-    # Remembers when a warning occurs and writes a warning message.
-    def warn(*args)
-      self.warned = true
-      super
-    end
-    attr_accessor :warned
-
-    # 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]
-    def capture(msg, nontty_log = :debug)
-      progress(msg, nontty_log)
-      yield
-    ensure
-      clear_progress
-    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
-    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
-
-    # Clears the progress indicator in the TTY display.
-    # @return [void]
-    # @since 0.8.2
-    def clear_progress
-      return unless show_progress
-      print_no_newline("\e[?25h\e[2K")
-      @progress_msg = nil
-    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
-    def puts(msg = '')
-      print("#{msg}\n")
-    end
-
-    alias print_no_newline <<
-    private :print_no_newline
-
-    # Displays an unformatted line to the logger output stream.
-    # @param [String] msg the message to display
-    # @return [void]
-    # @since 0.8.2
-    def print(msg = '')
-      clear_line
-      print_no_newline(msg)
-    end
-    alias << print
-
-    # 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]
-    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
-
-    # 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]
-    def warn_no_continuations
-    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+
-    def enter_level(new_level = level)
-      old_level = level
-      self.level = new_level
-      yield
-    ensure
-      self.level = old_level
-    end
-
-    private
-
-    # Override this internal Logger method to clear line
-    def add(*args)
-      clear_line
-      super(*args)
-    end
-
-    def clear_line
-      return unless @progress_msg
-      print_no_newline("\e[2K\r")
-    end
-
-    # Log format (from Logger implementation). Used by Logger internally
-    def format_log(sev, _time, _prog, msg)
-      "[#{sev.downcase}]: #{msg}\n"
-    end
-  end
-end
+# encoding: utf-8
+# frozen_string_literal: true
+require 'logger'
+require 'thread'
+
+module YARD
+  # Handles console logging for info, warnings and errors.
+  # Uses the stdlib Logger class in Ruby for all the backend logic.
+  class Logger < ::Logger
+    # The list of characters displayed beside the progress bar to indicate
+    # "movement".
+    # @since 0.8.2
+    PROGRESS_INDICATORS = %w(⣷ ⣯ ⣟ ⡿ ⢿ ⣻ ⣽ ⣾)
+
+    # @return [IO] the IO object being logged to
+    # @since 0.8.2
+    def io; @logdev end
+    def io=(pipe) @logdev = pipe end
+
+    # @return [Boolean] whether backtraces should be shown (by default
+    #   this is on).
+    def show_backtraces; @show_backtraces || level == DEBUG end
+    attr_writer :show_backtraces
+
+    # @return [Boolean] whether progress indicators should be shown when
+    #   logging CLIs (by default this is off).
+    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
+    attr_writer :show_progress
+
+    # The logger instance
+    # @return [Logger] the logger instance
+    def self.instance(pipe = STDOUT)
+      @logger ||= new(pipe)
+    end
+
+    # Creates a new logger
+    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
+
+    # Changes the debug level to DEBUG if $DEBUG is set
+    # and writes a debugging message.
+    def debug(*args)
+      self.level = DEBUG if $DEBUG
+      super
+    end
+
+    # Remembers when a warning occurs and writes a warning message.
+    def warn(*args)
+      self.warned = true
+      super
+    end
+    attr_accessor :warned
+
+    # 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]
+    def capture(msg, nontty_log = :debug)
+      progress(msg, nontty_log)
+      yield
+    ensure
+      clear_progress
+    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
+    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
+
+    # Clears the progress indicator in the TTY display.
+    # @return [void]
+    # @since 0.8.2
+    def clear_progress
+      return unless show_progress
+      print_no_newline("\e[?25h\e[2K")
+      @progress_msg = nil
+    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
+    def puts(msg = '')
+      print("#{msg}\n")
+    end
+
+    alias print_no_newline <<
+    private :print_no_newline
+
+    # Displays an unformatted line to the logger output stream.
+    # @param [String] msg the message to display
+    # @return [void]
+    # @since 0.8.2
+    def print(msg = '')
+      clear_line
+      print_no_newline(msg)
+    end
+    alias << print
+
+    # 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]
+    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
+
+    # 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]
+    def warn_no_continuations
+    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+
+    def enter_level(new_level = level)
+      old_level = level
+      self.level = new_level
+      yield
+    ensure
+      self.level = old_level
+    end
+
+    private
+
+    # Override this internal Logger method to clear line
+    def add(*args)
+      clear_line
+      super(*args)
+    end
+
+    def clear_line
+      return unless @progress_msg
+      print_no_newline("\e[2K\r")
+    end
+
+    # Log format (from Logger implementation). Used by Logger internally
+    def format_log(sev, _time, _prog, msg)
+      "[#{sev.downcase}]: #{msg}\n"
+    end
+  end
+end