rdoc 7.2.0 → 8.1.0

data/lib/rdoc/rbs_helper.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'pathname'
+require 'rbs'
+require 'rdoc/markup/formatter'
+
+##
+# RBS type signature support.
+# Loads type information from .rbs files, validates inline annotations,
+# and converts type signatures to HTML with linked type names.
+
+module RDoc
+  module RbsHelper
+    class << self
+
+      ##
+      # Returns true if +sig+ is a valid RBS method type signature.
+
+      def valid_method_type?(sig)
+        RBS::Parser.parse_method_type(sig, require_eof: true)
+        true
+      rescue RBS::ParsingError
+        false
+      end
+
+      ##
+      # Returns true if +sig+ is a valid RBS type signature.
+
+      def valid_type?(sig)
+        RBS::Parser.parse_type(sig, require_eof: true)
+        true
+      rescue RBS::ParsingError
+        false
+      end
+
+      ##
+      # Loads RBS signatures from the given directories.
+      # Returns a Hash mapping "ClassName#method_name" => ["type sig string", ...].
+
+      def load_signatures(*dirs)
+        loader = RBS::EnvironmentLoader.new
+        dirs.each { |dir| loader.add(path: Pathname(dir)) }
+
+        env = RBS::Environment.new
+        loader.load(env: env)
+
+        signatures = {}
+
+        env.class_decls.each do |type_name, entry|
+          class_name = type_name.to_s.delete_prefix('::')
+
+          entry.each_decl do |decl|
+            decl.members.each do |member|
+              case member
+              when RBS::AST::Members::MethodDefinition
+                sigs = member.overloads.map { |o| o.method_type.to_s }
+                method_keys_for(class_name, member).each do |key|
+                  signatures[key] ||= sigs
+                end
+              when RBS::AST::Members::AttrReader, RBS::AST::Members::AttrWriter, RBS::AST::Members::AttrAccessor
+                key = member.kind == :singleton ? "#{class_name}.#{member.name}" : "#{class_name}##{member.name}"
+                signatures[key] ||= [member.type.to_s]
+              end
+            end
+          end
+        end
+
+        signatures
+      end
+
+      ##
+      # Converts type signature lines to HTML with type names linked to
+      # their documentation pages. Uses the RBS parser to extract type
+      # name locations precisely.
+      #
+      # +lines+ is an Array of signature line strings.
+      # +lookup+ is a Hash mapping type names to their doc paths.
+      # +from_path+ is the current page path for generating relative URLs.
+      #
+      # Returns escaped HTML with +->+ replaced by +→+.
+
+      def signature_to_html(lines, lookup:, from_path:)
+        lines.map { |line|
+          link_type_names_in_line(line, lookup, from_path).gsub('-&gt;', '&rarr;')
+        }.join("\n")
+      end
+
+      private
+
+      # `def self?.foo: ...` produces a member whose kind is :singleton_instance —
+      # it defines both Class.foo (singleton) and a private Class#foo (instance),
+      # so we need to register the signature under both keys.
+      def method_keys_for(class_name, member)
+        case member.kind
+        when :singleton
+          ["#{class_name}.#{member.name}"]
+        when :singleton_instance
+          ["#{class_name}.#{member.name}", "#{class_name}##{member.name}"]
+        else
+          ["#{class_name}##{member.name}"]
+        end
+      end
+
+      def link_type_names_in_line(line, lookup, from_path)
+        escaped = ERB::Util.html_escape(line)
+
+        locs = collect_type_name_locations(line)
+        return escaped if locs.empty?
+
+        result = escaped.dup
+
+        # Replace type names with links, working backwards to preserve positions.
+        # HTML escaping (e.g. -> becomes -&gt;) shifts positions, so we
+        # re-escape the prefix to find the correct offset in the result.
+        locs.sort_by { |l| -l[:start] }.each do |loc|
+          name = loc[:name]
+          next unless (target_path = lookup[name])
+
+          prefix = ERB::Util.html_escape(line[0...loc[:start]])
+          escaped_name = ERB::Util.html_escape(name)
+          start_in_escaped = prefix.length
+          end_in_escaped = start_in_escaped + escaped_name.length
+
+          href = ERB::Util.html_escape(Markup::Formatter.gen_relative_url(from_path, target_path))
+          result[start_in_escaped...end_in_escaped] =
+            "<a href=\"#{href}\" class=\"rbs-type\">#{escaped_name}</a>"
+        end
+
+        result
+      end
+
+      ##
+      # Extracts type name locations from a signature line using the RBS parser.
+
+      def collect_type_name_locations(line)
+        locs = []
+
+        begin
+          mt = RBS::Parser.parse_method_type(line, require_eof: true)
+        rescue RBS::ParsingError
+          begin
+            type = RBS::Parser.parse_type(line, require_eof: true)
+            collect_from_type(type, locs)
+            return locs
+          rescue RBS::ParsingError
+            return locs
+          end
+        end
+
+        mt.type.each_param { |p| collect_from_type(p.type, locs) }
+        if mt.block
+          mt.block.type.each_param { |p| collect_from_type(p.type, locs) }
+          collect_from_type(mt.block.type.return_type, locs)
+        end
+        collect_from_type(mt.type.return_type, locs)
+
+        locs
+      end
+
+      ##
+      # Recursively collects type name locations from an RBS type AST node.
+
+      def collect_from_type(type, locs)
+        case type
+        when RBS::Types::ClassInstance
+          name = type.name.to_s.delete_prefix('::')
+          if type.location
+            name_loc = type.location[:name] || type.location
+            locs << { name: name, start: name_loc.end_pos - name.length }
+          end
+          type.args.each { |a| collect_from_type(a, locs) }
+        when RBS::Types::Union, RBS::Types::Intersection, RBS::Types::Tuple
+          type.types.each { |t| collect_from_type(t, locs) }
+        when RBS::Types::Optional
+          collect_from_type(type.type, locs)
+        when RBS::Types::Record
+          type.all_fields.each_value { |t| collect_from_type(t, locs) }
+        when RBS::Types::Proc
+          type.type.each_param { |p| collect_from_type(p.type, locs) }
+          collect_from_type(type.type.return_type, locs)
+        end
+      end
+    end
+  end
+end

data/lib/rdoc/rd/inline.rb

@@ -1,71 +1,75 @@
 # frozen_string_literal: true
-##
-# Inline keeps track of markup and labels to create proper links.
+module RDoc
+  class RD
+    ##
+    # Inline keeps track of markup and labels to create proper links.
 
-class RDoc::RD::Inline
+    class Inline
 
-  ##
-  # The text of the reference
+      ##
+      # The text of the reference
 
-  attr_reader :reference
+      attr_reader :reference
 
-  ##
-  # The markup of this reference in RDoc format
+      ##
+      # The markup of this reference in RDoc format
 
-  attr_reader :rdoc
+      attr_reader :rdoc
 
-  ##
-  # Creates a new Inline for +rdoc+ and +reference+.
-  #
-  # +rdoc+ may be another Inline or a String.  If +reference+ is not given it
-  # will use the text from +rdoc+.
+      ##
+      # Creates a new Inline for +rdoc+ and +reference+.
+      #
+      # +rdoc+ may be another Inline or a String.  If +reference+ is not given it
+      # will use the text from +rdoc+.
 
-  def self.new(rdoc, reference = rdoc)
-    if self === rdoc and reference.equal? rdoc then
-      rdoc
-    else
-      super
-    end
-  end
+      def self.new(rdoc, reference = rdoc)
+        if self === rdoc and reference.equal? rdoc
+          rdoc
+        else
+          super
+        end
+      end
 
-  ##
-  # Initializes the Inline with +rdoc+ and +inline+
+      ##
+      # Initializes the Inline with +rdoc+ and +inline+
 
-  def initialize(rdoc, reference) # :not-new:
-    @reference = reference.equal?(rdoc) ? reference.dup : reference
+      def initialize(rdoc, reference) # :not-new:
+        @reference = reference.equal?(rdoc) ? reference.dup : reference
 
-    # unpack
-    @reference = @reference.reference if self.class === @reference
-    @rdoc      = rdoc
-  end
+        # unpack
+        @reference = @reference.reference if self.class === @reference
+        @rdoc      = rdoc
+      end
 
-  def ==(other) # :nodoc:
-    self.class === other and
-      @reference == other.reference and @rdoc == other.rdoc
-  end
+      def ==(other) # :nodoc:
+        self.class === other and
+          @reference == other.reference and @rdoc == other.rdoc
+      end
 
-  ##
-  # Appends +more+ to this inline.  +more+ may be a String or another Inline.
-
-  def append(more)
-    case more
-    when String then
-      @reference += more
-      @rdoc      += more
-    when RDoc::RD::Inline then
-      @reference += more.reference
-      @rdoc      += more.rdoc
-    else
-      raise "unknown thingy #{more}"
-    end
+      ##
+      # Appends +more+ to this inline.  +more+ may be a String or another Inline.
 
-    self
-  end
+      def append(more)
+        case more
+        when String
+          @reference += more
+          @rdoc      += more
+        when RD::Inline
+          @reference += more.reference
+          @rdoc      += more.rdoc
+        else
+          raise "unknown thingy #{more}"
+        end
 
-  def inspect # :nodoc:
-    "(inline: #{self})"
-  end
+        self
+      end
+
+      def inspect # :nodoc:
+        "(inline: #{self})"
+      end
 
-  alias to_s rdoc # :nodoc:
+      alias to_s rdoc # :nodoc:
 
+    end
+  end
 end

data/lib/rdoc/rd.rb

@@ -1,99 +1,101 @@
 # frozen_string_literal: true
-##
-# RDoc::RD implements the RD format from the rdtool gem.
-#
-# To choose RD as your only default format see
-# RDoc::Options@Saved+Options for instructions on setting up a
-# <code>.doc_options</code> file to store your project default.
-#
-# == LICENSE
-#
-# The grammar that produces RDoc::RD::BlockParser and RDoc::RD::InlineParser
-# is included in RDoc under the Ruby License.
-#
-# You can find the original source for rdtool at
-# https://github.com/uwabami/rdtool/
-#
-# You can use, re-distribute or change these files under Ruby's License or GPL.
-#
-# 1. You may make and give away verbatim copies of the source form of the
-#    software without restriction, provided that you duplicate all of the
-#    original copyright notices and associated disclaimers.
-#
-# 2. You may modify your copy of the software in any way, provided that
-#    you do at least ONE of the following:
-#
-#    a. place your modifications in the Public Domain or otherwise
-#       make them Freely Available, such as by posting said
-#       modifications to Usenet or an equivalent medium, or by allowing
-#       the author to include your modifications in the software.
-#
-#    b. use the modified software only within your corporation or
-#       organization.
-#
-#    c. give non-standard binaries non-standard names, with
-#       instructions on where to get the original software distribution.
-#
-#    d. make other distribution arrangements with the author.
-#
-# 3. You may distribute the software in object code or binary form,
-#    provided that you do at least ONE of the following:
-#
-#    a. distribute the binaries and library files of the software,
-#       together with instructions (in the manual page or equivalent)
-#       on where to get the original distribution.
-#
-#    b. accompany the distribution with the machine-readable source of
-#       the software.
-#
-#    c. give non-standard binaries non-standard names, with
-#       instructions on where to get the original software distribution.
-#
-#    d. make other distribution arrangements with the author.
-#
-# 4. You may modify and include the part of the software into any other
-#    software (possibly commercial).  But some files in the distribution
-#    are not written by the author, so that they are not under these terms.
-#
-#    For the list of those files and their copying conditions, see the
-#    file LEGAL.
-#
-# 5. The scripts and library files supplied as input to or produced as
-#    output from the software do not automatically fall under the
-#    copyright of the software, but belong to whomever generated them,
-#    and may be sold commercially, and may be aggregated with this
-#    software.
-#
-# 6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
-#    IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
-#    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-#    PURPOSE.
+module RDoc
+  ##
+  # RDoc::RD implements the RD format from the rdtool gem.
+  #
+  # To choose RD as your only default format see
+  # RDoc::Options@Saved+Options for instructions on setting up a
+  # <code>.doc_options</code> file to store your project default.
+  #
+  # == LICENSE
+  #
+  # The grammar that produces RDoc::RD::BlockParser and RDoc::RD::InlineParser
+  # is included in RDoc under the Ruby License.
+  #
+  # You can find the original source for rdtool at
+  # https://github.com/uwabami/rdtool/
+  #
+  # You can use, re-distribute or change these files under Ruby's License or GPL.
+  #
+  # 1. You may make and give away verbatim copies of the source form of the
+  #    software without restriction, provided that you duplicate all of the
+  #    original copyright notices and associated disclaimers.
+  #
+  # 2. You may modify your copy of the software in any way, provided that
+  #    you do at least ONE of the following:
+  #
+  #    a. place your modifications in the Public Domain or otherwise
+  #       make them Freely Available, such as by posting said
+  #       modifications to Usenet or an equivalent medium, or by allowing
+  #       the author to include your modifications in the software.
+  #
+  #    b. use the modified software only within your corporation or
+  #       organization.
+  #
+  #    c. give non-standard binaries non-standard names, with
+  #       instructions on where to get the original software distribution.
+  #
+  #    d. make other distribution arrangements with the author.
+  #
+  # 3. You may distribute the software in object code or binary form,
+  #    provided that you do at least ONE of the following:
+  #
+  #    a. distribute the binaries and library files of the software,
+  #       together with instructions (in the manual page or equivalent)
+  #       on where to get the original distribution.
+  #
+  #    b. accompany the distribution with the machine-readable source of
+  #       the software.
+  #
+  #    c. give non-standard binaries non-standard names, with
+  #       instructions on where to get the original software distribution.
+  #
+  #    d. make other distribution arrangements with the author.
+  #
+  # 4. You may modify and include the part of the software into any other
+  #    software (possibly commercial).  But some files in the distribution
+  #    are not written by the author, so that they are not under these terms.
+  #
+  #    For the list of those files and their copying conditions, see the
+  #    file LEGAL.
+  #
+  # 5. The scripts and library files supplied as input to or produced as
+  #    output from the software do not automatically fall under the
+  #    copyright of the software, but belong to whomever generated them,
+  #    and may be sold commercially, and may be aggregated with this
+  #    software.
+  #
+  # 6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+  #    IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+  #    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+  #    PURPOSE.
 
-class RDoc::RD
+  class RD
 
-  ##
-  # Parses +rd+ source and returns an RDoc::Markup::Document.  If the
-  # <tt>=begin</tt> or <tt>=end</tt> lines are missing they will be added.
+    ##
+    # Parses +rd+ source and returns an RDoc::Markup::Document.  If the
+    # <tt>=begin</tt> or <tt>=end</tt> lines are missing they will be added.
 
-  def self.parse(rd)
-    rd = rd.lines.to_a
+    def self.parse(rd)
+      rd = rd.lines.to_a
 
-    if rd.find { |i| /\S/ === i } and !rd.find{|i| /^=begin\b/ === i } then
-      rd.unshift("=begin\n").push("=end\n")
-    end
+      if rd.find { |i| /\S/ === i } and !rd.find{|i| /^=begin\b/ === i }
+        rd.unshift("=begin\n").push("=end\n")
+      end
 
-    parser = RDoc::RD::BlockParser.new
-    document = parser.parse rd
+      parser = RD::BlockParser.new
+      document = parser.parse rd
 
-    # isn't this always true?
-    document.parts.shift if RDoc::Markup::BlankLine === document.parts.first
-    document.parts.pop   if RDoc::Markup::BlankLine === document.parts.last
+      # isn't this always true?
+      document.parts.shift if Markup::BlankLine === document.parts.first
+      document.parts.pop   if Markup::BlankLine === document.parts.last
 
-    document
-  end
+      document
+    end
 
-  autoload :BlockParser,  "#{__dir__}/rd/block_parser"
-  autoload :InlineParser, "#{__dir__}/rd/inline_parser"
-  autoload :Inline,       "#{__dir__}/rd/inline"
+    autoload :BlockParser,  "#{__dir__}/rd/block_parser"
+    autoload :InlineParser, "#{__dir__}/rd/inline_parser"
+    autoload :Inline,       "#{__dir__}/rd/inline"
 
+  end
 end