yard 0.9.26 → 0.9.37

data/lib/yard/logging.rb

@@ -1,12 +1,44 @@
 # 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
+  class Logger
+    # Log severity levels
+    module Severity
+      # Debugging log level
+      DEBUG = 0
+
+      # Information log level
+      INFO = 1
+
+      # Warning log level
+      WARN = 2
+
+      # Error log level
+      ERROR = 3
+
+      # Fatal log level
+      FATAL = 4
+
+      # Unknown log level
+      UNKNOWN = 5
+
+      # @private
+      SEVERITIES = {
+        DEBUG => :debug,
+        INFO => :info,
+        WARN => :warn,
+        ERROR => :error,
+        FATAL => :fatal,
+        UNKNOWN => :unknown
+      }
+    end
+
+    include Severity
+
     # The list of characters displayed beside the progress bar to indicate
     # "movement".
     # @since 0.8.2
@@ -14,25 +46,31 @@ module YARD
 
     # @return [IO] the IO object being logged to
     # @since 0.8.2
-    def io; @logdev end
-    def io=(pipe) @logdev = pipe end
+    attr_accessor :io
 
     # @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 [DEBUG, INFO, WARN, ERROR, FATAL, UNKNOWN] the logging level
+    attr_accessor :level
+
+    # @return [Boolean] whether a warn message has been emitted. Used for status tracking.
+    attr_accessor :warned
+
     # @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
 
+    # @!group Constructor Methods
+
     # The logger instance
     # @return [Logger] the logger instance
     def self.instance(pipe = STDOUT)
@@ -40,13 +78,12 @@ module YARD
     end
 
     # Creates a new logger
+    # @private
     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
@@ -54,36 +91,64 @@ module YARD
       @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
+    # @!macro [attach] logger.create_log_method
+    #   @method $1(message)
+    #   Logs a message with the $1 severity level.
+    #   @param message [String] the message to log
+    #   @see #log
+    #   @return [void]
+    # @private
+    def self.create_log_method(name)
+      severity = Severity.const_get(name.to_s.upcase)
+      define_method(name) { |message| log(severity, message) }
     end
 
+    # @!group Logging Methods
+
+    create_log_method :info
+    create_log_method :error
+    create_log_method :fatal
+    create_log_method :unknown
+
+    # Changes the debug level to DEBUG if $DEBUG is set and writes a debugging message.
+    create_log_method :debug
+
     # Remembers when a warning occurs and writes a warning message.
-    def warn(*args)
-      self.warned = true
-      super
+    create_log_method :warn
+
+    # Logs a message with a given severity
+    # @param severity [DEBUG, INFO, WARN, ERROR, FATAL, UNKNOWN] the severity level
+    # @param message [String] the message to log
+    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
-    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.
+    # @!group Level Control Methods
+
+    # Sets the logger level for the duration of the block
     #
-    # @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)
+    # @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
-      clear_progress
+      self.level = old_level
     end
 
+    # @!group Utility Printing Methods
+
     # 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.
@@ -120,7 +185,7 @@ module YARD
     # @since 0.8.2
     def clear_progress
       return unless show_progress
-      print_no_newline("\e[?25h\e[2K")
+      io.write("\e[?25h\e[2K")
       @progress_msg = nil
     end
 
@@ -133,16 +198,13 @@ module YARD
       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)
+      io.write(msg)
     end
     alias << print
 
@@ -158,48 +220,41 @@ module YARD
         exc.backtrace[0..5].map {|x| "\n\t#{x}" }.join + "\n")
     end
 
+    # @!group Benchmarking Methods
+
+    # 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
+
+    # @!endgroup
+
     # 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]
+    # @private
     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"
+      io.write("\e[2K\r")
     end
   end
 end

data/lib/yard/open_struct.rb

@@ -0,0 +1,67 @@
+module YARD
+  # An OpenStruct compatible struct class that allows for basic access of attributes
+  # via +struct.attr_name+ and +struct.attr_name = value+.
+  class OpenStruct
+    def initialize(hash = {})
+      @table = hash.each_pair { |k, v| [k.to_sym, v] }
+    end
+
+    # @private
+    def method_missing(name, *args)
+      if name.to_s.end_with?('=')
+        varname = name.to_s[0..-2].to_sym
+        __cache_lookup__(varname)
+        send(name, args.first)
+      else
+        __cache_lookup__(name)
+        send(name)
+      end
+    end
+
+    def to_h
+      @table.dup
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && to_h == other.to_h
+    end
+
+    def hash
+      @table.hash
+    end
+
+    def dig(*keys)
+      @table.dig(*keys)
+    end
+
+    def []=(key, value)
+      @table[key.to_sym] = value
+    end
+
+    def [](key)
+      @table[key.to_sym]
+    end
+
+    def each_pair(&block)
+      @table.each_pair(&block)
+    end
+
+    def marshal_dump
+      @table
+    end
+
+    def marshal_load(data)
+      @table = data
+    end
+
+    private
+
+    def __cache_lookup__(name)
+      key = name.to_sym.inspect
+      instance_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{name}; @table[#{key}]; end
+        def #{name.to_s.sub('?','_')}=(v); @table[#{key}] = v; end unless #{key}.to_s.include?('?')
+      RUBY
+    end
+  end
+end

data/lib/yard/options.rb

@@ -94,7 +94,7 @@ module YARD
     #
     # @example Setting an option with Hash syntax
     #   options[:format] = :html # equivalent to: options.format = :html
-    # @param [Symbol, String] key the optin to set
+    # @param [Symbol, String] key the option to set
     # @param [Object] value the value to set for the option
     # @return [Object] the value being set
     def []=(key, value) send("#{key}=", value) end

data/lib/yard/parser/ruby/ast_node.rb

@@ -426,6 +426,13 @@ module YARD
         def block_param
           self[-1] ? self[-1][0] : nil
         end
+
+        def args_forward
+          # shape is (required, optional, rest, more, keyword, keyword_rest, block)
+          # Ruby 3.1 moves :args_forward from rest to keyword_rest
+          args_index = YARD.ruby31? ? -2 : 2
+          self[args_index].type == :args_forward if self[args_index]
+        end
       end
 
       class MethodCallNode < AstNode
@@ -480,7 +487,7 @@ module YARD
         end
 
         def parameters(include_block_param = true)
-          params = self[1 + index_adjust]
+          return unless params = self[1 + index_adjust]
           params = params[0] if params.type == :paren
           include_block_param ? params : params[0...-1]
         end
@@ -488,7 +495,7 @@ module YARD
         def signature
           params_src = ''
           params = self[1 + index_adjust]
-          if params.first
+          if params and params.first
             params_src = params.type == :paren ? '' : ' '
             params_src += params.source.gsub(/\s+(\s|\))/m, '\1')
           end

data/lib/yard/parser/ruby/legacy/ruby_lex.rb

@@ -656,7 +656,7 @@ module YARD
           if @lex_state != EXPR_END && @lex_state != EXPR_CLASS &&
              (@lex_state != EXPR_ARG || @space_seen)
             c = peek(0)
-            tk = identify_here_document if /[-\w\"\'\`]/ =~ c
+            tk = identify_here_document if /[-~\w\"\'\`]/ =~ c
           end
           if !tk
             @lex_state = EXPR_BEG
@@ -1063,6 +1063,8 @@ module YARD
         ch = getc
         if ch == "-"
           ch = getc
+        elsif ch == "~"
+          ch = getc
           indent = true
         end
         if /['"`]/ =~ ch # '
@@ -1096,9 +1098,12 @@ module YARD
         str = String.new
         while (l = gets)
           l.chomp!
-          l.strip! if indent
-          break if l == quoted
-          str << l.chomp << "\n"
+          if l == quoted
+            str = dedent(str) if indent
+            break
+          else
+            str << l.chomp << "\n"
+          end
         end
 
         @reader.divert_read_from(reserve)
@@ -1108,6 +1113,16 @@ module YARD
         Token(Ltype2Token[lt], str).set_text(str.dump)
       end
 
+      def dedent(str)
+        lines = str.split("\n", -1)
+        dedent_amt = lines.map do |line|
+          line =~ /\S/ ? line.match(/^ */).offset(0)[1] : nil
+        end.compact.min || 0
+        return str if dedent_amt.zero?
+
+        lines.map { |line| line =~ /\S/ ? line.gsub(/^ {#{dedent_amt}}/, "") : line }.join("\n")
+      end
+
       def identify_quotation(initial_char)
         ch = getc
         if lt = PERCENT_LTYPE[ch]

data/lib/yard/parser/ruby/ruby_parser.rb

@@ -133,6 +133,12 @@ module YARD
         AST_TOKENS = [:CHAR, :backref, :const, :cvar, :gvar, :heredoc_end, :ident,
           :int, :float, :ivar, :label, :period, :regexp_end, :tstring_content, :backtick]
 
+        COMMENT_SKIP_NODE_TYPES = [
+          :comment,
+          :void_stmt,
+          :list
+        ].freeze
+
         MAPPINGS.each do |k, v|
           if Array === v
             v.each {|vv| (REV_MAPPINGS[vv] ||= []) << k }
@@ -144,7 +150,7 @@ module YARD
         PARSER_EVENT_TABLE.each do |event, arity|
           node_class = AstNode.node_class_for(event)
 
-          if /_new\z/ =~ event.to_s && arity == 0
+          if arity == 0 && /_new\z/ =~ event.to_s
             module_eval(<<-eof, __FILE__, __LINE__ + 1)
               def on_#{event}(*args)
                 #{node_class}.new(:list, args, :listchar => charno...charno, :listline => lineno..lineno)
@@ -370,7 +376,7 @@ module YARD
 
         def on_aref(*args)
           @map[:lbracket].pop
-          ll, lc = *@map[:aref].pop
+          ll, lc = *@map[:aref].shift
           sr = args.first.source_range.first..lc
           lr = args.first.line_range.first..ll
           AstNode.new(:aref, args, :char => sr, :line => lr)
@@ -613,7 +619,7 @@ module YARD
 
         def insert_comments
           root.traverse do |node|
-            next if [:comment, :void_stmt, :list].include?(node.type) || node.parent.type != :list
+            next if COMMENT_SKIP_NODE_TYPES.include?(node.type) || node.parent.type != :list
 
             # never attach comments to if/unless mod nodes
             if node.type == :if_mod || node.type == :unless_mod

data/lib/yard/parser/source_parser.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 require 'stringio'
-require 'ostruct'
 
 module YARD
   module Parser
@@ -108,7 +107,8 @@ module YARD
           files = [paths].flatten.
             map {|p| File.directory?(p) ? "#{p}/**/*.{rb,c,cc,cxx,cpp}" : p }.
             map {|p| p.include?("*") ? Dir[p].sort_by {|d| [d.length, d] } : p }.flatten.
-            reject {|p| !File.file?(p) || excluded.any? {|re| p =~ re } }
+            reject {|p| !File.file?(p) || excluded.any? {|re| p =~ re } }.
+            map {|p| p.encoding == Encoding.default_external ? p : p.dup.force_encoding(Encoding.default_external) }
 
           log.enter_level(level) do
             parse_in_order(*files.uniq)
@@ -476,9 +476,8 @@ module YARD
           content.force_encoding('binary')
           ENCODING_BYTE_ORDER_MARKS.each do |encoding, bom|
             bom.force_encoding('binary')
-            if content[0, bom.size] == bom
-              content.force_encoding(encoding)
-              return content
+            if content.start_with?(bom)
+              return content.sub(bom, '').force_encoding(encoding)
             end
           end
           content.force_encoding('utf-8') # UTF-8 is default encoding

data/lib/yard/registry_resolver.rb

@@ -132,7 +132,8 @@ module YARD
 
       path.scan(split_on_separators_match).each do |part, sep|
         cur_obj = nil
-        pos += "#{part}#{sep}".length
+        pos += part.length
+        pos += sep.length
         parsed_end = pos == path.length
 
         if !last_obj || (!parsed_end && !last_obj.is_a?(CodeObjects::NamespaceObject))

data/lib/yard/server/commands/base.rb

@@ -119,7 +119,7 @@ module YARD
         #     def run
         #       self.body = 'ERROR! The System is down!'
         #       self.status = 500
-        #       self.headers['Conten-Type'] = 'text/plain'
+        #       self.headers['Content-Type'] = 'text/plain'
         #     end
         #   end
         #

data/lib/yard/server/commands/library_command.rb

@@ -31,7 +31,7 @@ module YARD
       # @abstract
       class LibraryCommand < Base
         begin
-          Process.fork { exit 0 }
+          Process.fork { }
           CAN_FORK = true
         rescue Exception # rubocop:disable Lint/RescueException
           CAN_FORK = false
@@ -94,16 +94,16 @@ module YARD
         end
 
         def call_with_fork(request, &block)
-          reader, writer = IO.pipe
+          IO.pipe(:binmode => true) do |reader, writer|
+            fork do
+              log.debug "[pid=#{Process.pid}] fork serving: #{request.path}"
+              reader.close
+              writer.print(Marshal.dump(call_without_fork(request, &block)))
+            end
 
-          fork do
-            log.debug "[pid=#{Process.pid}] fork serving: #{request.path}"
-            reader.close
-            writer.print(Marshal.dump(call_without_fork(request, &block)))
+            writer.close
+            Marshal.load(reader.read)
           end
-
-          writer.close
-          Marshal.load(reader.read)
         end
 
         def can_fork?

data/lib/yard/server/commands/static_file_helpers.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-require 'webrick/httputils'
 
 module YARD
   module Server
@@ -7,7 +6,7 @@ module YARD
       # Include this module to get access to {#static_template_file?}
       # and {favicon?} helpers.
       module StaticFileHelpers
-        include WEBrick::HTTPUtils
+        include Server::HTTPUtils
 
         # Serves an empty favicon.
         # @raise [FinishRequest] finalizes an empty body if the path matches