yard 0.9.28 → 0.9.43

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/rbs/rbs_parser.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+module YARD
+  module Parser
+    module RBS
+      # Parses RBS (Ruby type signature) files and produces a list of
+      # {Statement} objects for post-processing by handlers.
+      #
+      # RBS is Ruby's official type signature format (introduced in Ruby 3.0).
+      # This parser handles: class/module/interface declarations, method
+      # signatures, attribute accessors, mixins, and constants.
+      #
+      # No external gem dependencies are used; the parser is hand-written.
+      class RbsParser < YARD::Parser::Base
+        # @param source [String] source code to parse
+        # @param filename [String] path to the source file
+        def initialize(source, filename)
+          @source   = source
+          @filename = filename
+          @statements = nil
+        end
+
+        # Parses the source and returns self.
+        # @return [RbsParser] self
+        def parse
+          lines = @source.lines.map { |l| l.chomp }
+          @statements, = parse_body(lines, 0, false)
+          self
+        end
+
+        # Tokenization is not implemented for RBS.
+        def tokenize
+          raise NotImplementedError, "RBS parser does not support tokenization"
+        end
+
+        # @return [Array<Statement>] top-level statements for the post-processor
+        def enumerator
+          @statements
+        end
+
+        private
+
+        # Parse a sequence of lines, returning statements and the index after the last consumed line.
+        #
+        # @param lines [Array<String>] source lines
+        # @param start [Integer] index to start from (0-based)
+        # @param stop_at_end [Boolean] when true, stop parsing when we see a bare `end`
+        # @return [Array(Array<Statement>, Integer)] [statements, new_index]
+        def parse_body(lines, start, stop_at_end)
+          statements        = []
+          i                 = start
+          pending_comments  = []
+          pending_start_1   = nil  # 1-indexed line number of first pending comment
+
+          while i < lines.length
+            raw      = lines[i]
+            stripped = raw.strip
+
+            if stripped =~ /\A#(.*)/
+              # Comment line – accumulate into pending docstring.
+              # Strip at most one leading space (conventional RBS doc style).
+              pending_comments << $1.sub(/\A /, '')
+              pending_start_1 ||= i + 1
+              i += 1
+
+            elsif stripped.empty?
+              # Blank line resets pending comments.
+              pending_comments  = []
+              pending_start_1   = nil
+              i += 1
+
+            elsif stop_at_end && stripped == 'end'
+              # End of enclosing block.
+              return [statements, i + 1]
+
+            else
+              stmt, i = parse_statement(lines, i, pending_comments, pending_start_1)
+              statements << stmt if stmt
+              pending_comments  = []
+              pending_start_1   = nil
+            end
+          end
+
+          [statements, i]
+        end
+
+        def strip_inline_comment(line)
+          in_single = false
+          in_double = false
+          escaped   = false
+
+          line.each_char.with_index do |char, index|
+            if escaped
+              escaped = false
+              next
+            end
+
+            case char
+            when "\\"
+              escaped = true if in_single || in_double
+            when "'"
+              in_single = !in_single unless in_double
+            when '"'
+              in_double = !in_double unless in_single
+            when '#'
+              return line[0...index].rstrip unless in_single || in_double
+            end
+          end
+
+          line.rstrip
+        end
+
+        def sanitized_statement_lines(lines, start_index)
+          overrides = { start_index => strip_inline_comment(lines[start_index]) }
+
+          j = start_index + 1
+          while j < lines.length && lines[j].lstrip.start_with?('|')
+            overrides[j] = strip_inline_comment(lines[j])
+            j += 1
+          end
+
+          overrides
+        end
+
+        # Dispatch a single declaration line.
+        def parse_statement(lines, i, comments, comment_start_1)
+          sanitized     = sanitized_statement_lines(lines, i)
+          stripped      = sanitized.fetch(i, lines[i]).strip
+          line_num        = i + 1  # 1-indexed
+
+          docs   = comments.empty? ? nil : comments.join("\n")
+          crange = comment_start_1 ? (comment_start_1)..(line_num - 1) : nil
+
+          case stripped
+          when /\Aclass\s/
+            parse_namespace(:class, lines, i, docs, crange)
+          when /\Amodule\s/
+            parse_namespace(:module, lines, i, docs, crange)
+          when /\Ainterface\s/
+            parse_namespace(:interface, lines, i, docs, crange)
+          when /\Adef\s/
+            parse_method_def(sanitized, lines, i, docs, crange)
+          when /\Aattr_reader\s/
+            parse_attr(:attr_reader, lines, i, docs, crange)
+          when /\Aattr_writer\s/
+            parse_attr(:attr_writer, lines, i, docs, crange)
+          when /\Aattr_accessor\s/
+            parse_attr(:attr_accessor, lines, i, docs, crange)
+          when /\A(include|extend|prepend)\s+(\S+)/
+            kind = $1.to_sym
+            name = $2.delete(';')
+            stmt = Statement.new(
+              :type           => kind,
+              :name           => name,
+              :mixin_name     => name,
+              :line           => line_num,
+              :source         => stripped,
+              :comments       => docs,
+              :comments_range => crange
+            )
+            [stmt, i + 1]
+          when /\Aalias\s+(\S+)\s+(\S+)/
+            stmt = Statement.new(
+              :type           => :alias,
+              :name           => $1,
+              :line           => line_num,
+              :source         => stripped,
+              :comments       => docs,
+              :comments_range => crange
+            )
+            [stmt, i + 1]
+          when /\A(public|private|protected)\s*(\z|#)/
+            # Visibility modifier – skip silently.
+            [nil, i + 1]
+          when /\Aend\s*(\z|#)/
+            # Stray `end` – skip.
+            [nil, i + 1]
+          when /\Atype\s/
+            # Type alias declaration – nothing to document.
+            [nil, i + 1]
+          else
+            # Constant declaration: `NAME: Type`
+            if stripped =~ /\A([A-Z][a-zA-Z0-9_]*(?:::[A-Z][a-zA-Z0-9_]*)*)\s*:\s*(.+)\z/
+              stmt = Statement.new(
+                :type           => :constant,
+                :name           => $1,
+                :attr_rbs_type  => $2.strip,
+                :line           => line_num,
+                :source         => stripped,
+                :comments       => docs,
+                :comments_range => crange
+              )
+              [stmt, i + 1]
+            else
+              [nil, i + 1]
+            end
+          end
+        end
+
+        def parse_namespace(type, lines, i, docs, crange)
+          # Strip trailing inline comment from the declaration line.
+          decl     = lines[i].strip.sub(/\s*#.*\z/, '')
+          line_num = i + 1
+
+          name       = nil
+          superclass = nil
+
+          case type
+          when :class
+            # class Foo[T] < Bar[String]
+            if decl =~ /\Aclass\s+([^\s<\[]+)(\[[^\]]*\])?(?:\s*<\s*(.+))?\z/
+              name       = $1.strip
+              superclass = $3 ? $3.strip : nil
+              # Strip generic params from superclass, e.g. "Array[String]" -> "Array"
+              superclass.sub!(/\[.*\]\z/, '') if superclass
+            else
+              return [nil, i + 1]
+            end
+
+          when :module
+            # module Foo[T] : SelfType
+            if decl =~ /\Amodule\s+([^\s\[(:]+)/
+              name = $1.strip
+            else
+              return [nil, i + 1]
+            end
+
+          when :interface
+            # interface _Foo[T]
+            if decl =~ /\Ainterface\s+([^\s\[]+)/
+              name = $1.strip
+            else
+              return [nil, i + 1]
+            end
+          end
+
+          children, new_i = parse_body(lines, i + 1, true)
+          source = lines[i...new_i].join("\n")
+
+          stmt = Statement.new(
+            :type           => type,
+            :name           => name,
+            :superclass     => superclass,
+            :line           => line_num,
+            :source         => source,
+            :comments       => docs,
+            :comments_range => crange,
+            :block          => children
+          )
+
+          [stmt, new_i]
+        end
+
+        def parse_method_def(sanitized, lines, i, docs, crange)
+          stripped = sanitized.fetch(i, lines[i]).strip
+          line_num = i + 1
+
+          # def method_name: overload1
+          #                | overload2
+          # Also handles: def self.method_name: ...
+          unless stripped =~ /\Adef\s+(self\.)?(\S+?)\s*:\s*(.*)\z/
+            return [nil, i + 1]
+          end
+
+          is_class_side = !$1.nil?
+          meth_name     = $2
+          first_sig     = $3.strip
+
+          sigs = [first_sig]
+          j    = i + 1
+
+          # Collect `| overload` continuation lines.
+          while j < lines.length
+            cont = sanitized.fetch(j, lines[j]).strip
+            if cont =~ /\A\|\s*(.*)\z/
+              sigs << $1.strip
+              j += 1
+            else
+              break
+            end
+          end
+
+          stmt = Statement.new(
+            :type           => :method_def,
+            :name           => meth_name,
+            :line           => line_num,
+            :source         => lines[i...j].join("\n"),
+            :comments       => docs,
+            :comments_range => crange,
+            :signatures     => sigs,
+            :visibility     => is_class_side ? :class : :instance
+          )
+
+          [stmt, j]
+        end
+
+        def parse_attr(type, lines, i, docs, crange)
+          stripped = strip_inline_comment(lines[i]).strip
+          line_num = i + 1
+          keyword  = type.to_s
+
+          # attr_reader [self.] name : Type
+          if stripped =~ /\A#{Regexp.escape(keyword)}\s+(self\.)?(\w+)\s*:\s*(.*)\z/
+            is_class  = !$1.nil?
+            attr_name = $2
+            attr_type = $3.strip
+
+            stmt = Statement.new(
+              :type           => type,
+              :name           => attr_name,
+              :attr_rbs_type  => attr_type,
+              :line           => line_num,
+              :source         => stripped,
+              :comments       => docs,
+              :comments_range => crange,
+              :visibility     => is_class ? :class : :instance
+            )
+            [stmt, i + 1]
+          else
+            [nil, i + 1]
+          end
+        end
+      end
+    end
+  end
+end