rdoc 7.2.0 → 8.1.0

data/lib/rdoc/cross_reference.rb

@@ -1,235 +1,217 @@
 # frozen_string_literal: true
 
-##
-# RDoc::CrossReference is a reusable way to create cross references for names.
-
-class RDoc::CrossReference
-
-  ##
-  # Regular expression to match class references
-  #
-  # 1. There can be a '\\' in front of text to suppress the cross-reference
-  # 2. There can be a '::' in front of class names to reference from the
-  #    top-level namespace.
-  # 3. The method can be followed by parenthesis (not recommended)
-
-  CLASS_REGEXP_STR = '\\\\?((?:\:{2})?[A-Z]\w*(?:\:\:\w+)*)'
-
-  ##
-  # Regular expression to match a single method argument.
-
-  METHOD_ARG_REGEXP_STR = '[\w.+*/=<>-]+'
-
-  ##
-  # Regular expression to match method arguments.
-
-  METHOD_ARGS_REGEXP_STR = /(?:\((?:#{METHOD_ARG_REGEXP_STR}(?:,\s*#{METHOD_ARG_REGEXP_STR})*)?\))?/.source
-
-  ##
-  # Regular expression to match method references.
-  #
-  # See CLASS_REGEXP_STR
-
-  METHOD_REGEXP_STR = /(
-    (?!\d)[\w]+[!?=]?|
-    %|=(?:==?|~)|![=~]|\[\]=?|<(?:<|=>?)?|>[>=]?|[-+!]@?|\*\*?|[\/%\`|&^~]
-  )#{METHOD_ARGS_REGEXP_STR}/.source.delete("\n ").freeze
-
+module RDoc
   ##
-  # Regular expressions matching text that should potentially have
-  # cross-reference links generated are passed to add_regexp_handling. Note
-  # that these expressions are meant to pick up text for which cross-references
-  # have been suppressed, since the suppression characters are removed by the
-  # code that is triggered.
-
-  CROSSREF_REGEXP = /(?:^|[\s()])
-                     (
-                      (?:
-                       # A::B::C.meth
-                       #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
-
-                       # A::B::C
-                       # The stuff after CLASS_REGEXP_STR is a
-                       # nasty hack.  CLASS_REGEXP_STR unfortunately matches
-                       # words like dog and cat (these are legal "class"
-                       # names in Fortran 95).  When a word is flagged as a
-                       # potential cross-reference, limitations in the markup
-                       # engine suppress other processing, such as typesetting.
-                       # This is particularly noticeable for contractions.
-                       # In order that words like "can't" not
-                       # be flagged as potential cross-references, only
-                       # flag potential class cross-references if the character
-                       # after the cross-reference is a space, sentence
-                       # punctuation, tag start character, or attribute
-                       # marker.
-                       | #{CLASS_REGEXP_STR}(?=[@\s).?!,;<\000]|\z)
-
-                       # Stand-alone method (preceded by a #)
-                       | \\?\##{METHOD_REGEXP_STR}
-
-                       # Stand-alone method (preceded by ::)
-                       | ::#{METHOD_REGEXP_STR}
-
-                       # Things that look like filenames
-                       # The key thing is that there must be at least
-                       # one special character (period, slash, or
-                       # underscore).
-                       | (?:\.\.\/)*[-\/\w]+[_\/.][-\w\/.]+
-
-                       # Things that have markup suppressed
-                       # Don't process things like '\<' in \<tt>, though.
-                       # TODO: including < is a hack, not very satisfying.
-                       | \\[^\s<]
-                      )
-
-                      # labels for headings
-                      (?:@[\w+%-]+(?:\.[\w|%-]+)?)?
-                     )/x
-
-  ##
-  # Version of CROSSREF_REGEXP used when <tt>--hyperlink-all</tt> is specified.
-
-  ALL_CROSSREF_REGEXP = /
-                     (?:^|[\s()])
-                     (
-                      (?:
-                       # A::B::C.meth
-                       #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
-
-                       # A::B::C
-                       | #{CLASS_REGEXP_STR}(?=[@\s).?!,;<\000]|\z)
-
-                       # Stand-alone method
-                       | \\?#{METHOD_REGEXP_STR}
-
-                       # Things that look like filenames
-                       | (?:\.\.\/)*[-\/\w]+[_\/.][-\w\/.]+
-
-                       # Things that have markup suppressed
-                       | \\[^\s<]
-                      )
-
-                      # labels for headings
-                      (?:@[\w+%-]+)?
-                     )/x
-
-  ##
-  # Hash of references that have been looked-up to their replacements
-
-  attr_accessor :seen
-
-  ##
-  # Allows cross-references to be created based on the given +context+
-  # (RDoc::Context).
-
-  def initialize(context)
-    @context = context
-    @store   = context.store
-
-    @seen = {}
-  end
+  # RDoc::CrossReference is a reusable way to create cross references for names.
+
+  class CrossReference
+
+    ##
+    # Regular expression to match class references
+    #
+    # 1. There can be a '\\' in front of text to suppress the cross-reference
+    # 2. There can be a '::' in front of class names to reference from the
+    #    top-level namespace.
+    # 3. The method can be followed by parenthesis (not recommended)
+
+    CLASS_REGEXP_STR = '\\\\?((?:\:{2})?[A-Z]\w*(?:\:\:\w+)*)'
+
+    ##
+    # Regular expression to match a single method argument.
+
+    METHOD_ARG_REGEXP_STR = '[\w.+*/=<>-]+'
+
+    ##
+    # Regular expression to match method arguments.
+
+    METHOD_ARGS_REGEXP_STR = /(?:\((?:#{METHOD_ARG_REGEXP_STR}(?:,\s*#{METHOD_ARG_REGEXP_STR})*)?\))?/.source
+
+    ##
+    # Regular expression to match method references.
+    #
+    # See CLASS_REGEXP_STR
+
+    METHOD_REGEXP_STR = /(
+      (?!\d)[\w]+[!?=]?|
+      %|=(?:==?|~)|![=~]|\[\]=?|<(?:<|=>?)?|>[>=]?|[-+!]@?|\*\*?|[\/%\`|&^~]
+    )#{METHOD_ARGS_REGEXP_STR}/.source.delete("\n ").freeze
+
+    ##
+    # Regular expressions matching text that should potentially have
+    # cross-reference links generated are passed to add_regexp_handling. Note
+    # that these expressions are meant to pick up text for which cross-references
+    # have been suppressed, since the suppression characters are removed by the
+    # code that is triggered.
+
+    CROSSREF_REGEXP = /(?:^|[\s()])
+                       (
+                        (?:
+                         # A::B::C.meth
+                         #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
+
+                         # A::B::C
+                         # The stuff after CLASS_REGEXP_STR is a
+                         # nasty hack.  CLASS_REGEXP_STR unfortunately matches
+                         # words like dog and cat (these are legal "class"
+                         # names in Fortran 95).  When a word is flagged as a
+                         # potential cross-reference, limitations in the markup
+                         # engine suppress other processing, such as typesetting.
+                         # This is particularly noticeable for contractions.
+                         # In order that words like "can't" not
+                         # be flagged as potential cross-references, only
+                         # flag potential class cross-references if the character
+                         # after the cross-reference is a space, sentence
+                         # punctuation, tag start character, or attribute
+                         # marker.
+                         | #{CLASS_REGEXP_STR}(?=[@\s).?!,;<\000]|\z)
+
+                         # Stand-alone method (preceded by a #)
+                         | \\?\##{METHOD_REGEXP_STR}
+
+                         # Stand-alone method (preceded by ::)
+                         | ::#{METHOD_REGEXP_STR}
+
+                         # Things that look like filenames
+                         # The key thing is that there must be at least
+                         # one special character (period, slash, or
+                         # underscore).
+                         | (?:\.\.\/)*[-\/\w]+[_\/.][-\w\/.]+
+
+                         # Things that have markup suppressed
+                         # Don't process things like '\<' in \<tt>, though.
+                         # TODO: including < is a hack, not very satisfying.
+                         | \\[^\s<]
+                        )
+
+                        # labels for headings
+                        (?:@[\w+%-]+(?:\.[\w|%-]+)?)?
+                       )/x
+
+    ##
+    # Version of CROSSREF_REGEXP used when <tt>--hyperlink-all</tt> is specified.
+
+    ALL_CROSSREF_REGEXP = /
+                       (?:^|[\s()])
+                       (
+                        (?:
+                         # A::B::C.meth
+                         #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
+
+                         # A::B::C
+                         | #{CLASS_REGEXP_STR}(?=[@\s).?!,;<\000]|\z)
+
+                         # Stand-alone method
+                         | \\?#{METHOD_REGEXP_STR}
+
+                         # Things that look like filenames
+                         | (?:\.\.\/)*[-\/\w]+[_\/.][-\w\/.]+
+
+                         # Things that have markup suppressed
+                         | \\[^\s<]
+                        )
+
+                        # labels for headings
+                        (?:@[\w+%-]+)?
+                       )/x
+
+    ##
+    # Hash of references that have been looked-up to their replacements
+
+    attr_accessor :seen
+
+    ##
+    # Allows cross-references to be created based on the given +context+
+    # (RDoc::Context).
+
+    def initialize(context)
+      @context = context
+      @store   = context.store
+
+      @seen = {}
+    end
 
-  ##
-  # Returns a method, attribute or constant reference to +name+
-  # if it exists in the containing context object. It returns
-  # nil otherwise.
-  #
-  # For example, this method would decompose name = 'A::CONSTANT' into a
-  # container object A and a symbol 'CONSTANT', and it would try to find
-  # 'CONSTANT' in A.
-
-  def resolve_local_symbol(name)
-    ref = nil
-    type = nil
-    container = nil
-
-    case name
-    when /#{CLASS_REGEXP_STR}::([A-Z]\w*)\z/o then
-      symbol = $2
-      container = @context.find_symbol_module($1)
-    when /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/o then
-      type = $2
-      if '.' == type # will find either #method or ::method
-        symbol = $3
-      else
-        symbol = "#{type}#{$3}"
-      end
-      container = @context.find_symbol_module($1)
-    when /^([.#]|::)#{METHOD_REGEXP_STR}/o then
-      type = $1
-      if '.' == type
+    ##
+    # Returns a method, attribute or constant reference to +name+
+    # if it exists in the containing context object. It returns
+    # nil otherwise.
+    #
+    # For example, this method would decompose name = 'A::CONSTANT' into a
+    # container object A and a symbol 'CONSTANT', and it would try to find
+    # 'CONSTANT' in A.
+
+    def resolve_local_symbol(name)
+      ref = nil
+      type = nil
+      container = nil
+
+      case name
+      when /#{CLASS_REGEXP_STR}::([A-Z]\w*)\z/o
         symbol = $2
-      else
-        symbol = "#{type}#{$2}"
+        container = @context.find_symbol_module($1)
+      when /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/o
+        type = $2
+        if '.' == type # will find either #method or ::method
+          symbol = $3
+        else
+          symbol = "#{type}#{$3}"
+        end
+        container = @context.find_symbol_module($1)
+      when /^([.#]|::)#{METHOD_REGEXP_STR}/o
+        type = $1
+        if '.' == type
+          symbol = $2
+        else
+          symbol = "#{type}#{$2}"
+        end
+        container = @context
       end
-      container = @context
-    end
 
-    if container then
-      unless RDoc::TopLevel === container then
-        if '.' == type then
-          if 'new' == symbol then # AnyClassName.new will be class method
+      if container
+        unless TopLevel === container
+          if '.' == type
+            if 'new' == symbol # AnyClassName.new will be class method
+              ref = container.find_local_symbol symbol
+              ref = container.find_ancestor_local_symbol symbol unless ref
+            else
+              ref = container.find_local_symbol "::#{symbol}"
+              ref = container.find_ancestor_local_symbol "::#{symbol}" unless ref
+              ref = container.find_local_symbol "##{symbol}" unless ref
+              ref = container.find_ancestor_local_symbol "##{symbol}" unless ref
+            end
+          else
             ref = container.find_local_symbol symbol
             ref = container.find_ancestor_local_symbol symbol unless ref
-          else
-            ref = container.find_local_symbol "::#{symbol}"
-            ref = container.find_ancestor_local_symbol "::#{symbol}" unless ref
-            ref = container.find_local_symbol "##{symbol}" unless ref
-            ref = container.find_ancestor_local_symbol "##{symbol}" unless ref
           end
-        else
-          ref = container.find_local_symbol symbol
-          ref = container.find_ancestor_local_symbol symbol unless ref
         end
       end
+
+      ref
     end
 
-    ref
-  end
+    ##
+    # Returns a reference to +name+.
+    #
+    # If the reference is found and +name+ is not documented +nil+ will be
+    # returned.  If +name+ is not found +nil+ is returned.
 
-  ##
-  # Returns a reference to +name+.
-  #
-  # If the reference is found and +name+ is not documented +text+ will be
-  # returned.  If +name+ is escaped +name+ is returned.  If +name+ is not
-  # found +text+ is returned.
-
-  def resolve(name, text)
-    return @seen[name] if @seen.include? name
-
-    ref = case name
-          when /^\\(#{CLASS_REGEXP_STR})$/o then
-            @context.find_symbol $1
-          else
-            @context.find_symbol name
-          end
+    def resolve(name)
+      return @seen[name] if @seen.include? name
 
-    ref = resolve_local_symbol name unless ref
+      ref = @context.find_symbol name
 
-    # Try a page name
-    ref = @store.page name if not ref and name =~ /^[\w.\/]+$/
+      ref = resolve_local_symbol name unless ref
 
-    ref = nil if RDoc::Alias === ref # external alias, can't link to it
+      # Try a page name
+      ref = @store.page name if not ref and name =~ /^[\w.\/]+$/
 
-    out = if name == '\\' then
-            name
-          elsif name =~ /^\\/ then
-            # we remove the \ only in front of what we know:
-            # other backslashes are treated later, only outside of <tt>
-            ref ? $' : name
-          elsif ref then
-            if ref.display? then
-              ref
-            else
-              text
-            end
-          else
-            text
-          end
+      ref = nil if Alias === ref # external alias, can't link to it
 
-    @seen[name] = out
+      ref = nil unless ref&.display?
 
-    out
-  end
+      @seen[name] = ref
 
+      ref
+    end
+
+  end
 end

data/lib/rdoc/encoding.rb

@@ -1,120 +1,122 @@
 # coding: US-ASCII
 # frozen_string_literal: true
 
-##
-# This class is a wrapper around File IO and Encoding that helps RDoc load
-# files and convert them to the correct encoding.
-
-module RDoc::Encoding
-
-  HEADER_REGEXP = /^
-    (?:
-      \A\#!.*\n
-      |
-      ^\#\s+frozen[-_]string[-_]literal[=:].+\n
-      |
-      ^\#[^\n]+\b(?:en)?coding[=:]\s*(?<name>[^\s;]+).*\n
-      |
-      <\?xml[^?]*encoding=(?<quote>["'])(?<name>.*?)\k<quote>.*\n
-    )+
-  /xi # :nodoc:
-
+module RDoc
   ##
-  # Reads the contents of +filename+ and handles any encoding directives in
-  # the file.
-  #
-  # The content will be converted to the +encoding+.  If the file cannot be
-  # converted a warning will be printed and nil will be returned.
-  #
-  # If +force_transcode+ is true the document will be transcoded and any
-  # unknown character in the target encoding will be replaced with '?'
-
-  def self.read_file(filename, encoding, force_transcode = false)
-    content = File.open filename, "rb" do |f| f.read end
-    content.gsub!("\r\n", "\n") if RUBY_PLATFORM =~ /mswin|mingw/
-
-    utf8 = content.sub!(/\A\xef\xbb\xbf/, '')
-
-    enc = RDoc::Encoding.detect_encoding content
-    content = RDoc::Encoding.change_encoding content, enc if enc
-
-    begin
-      encoding ||= Encoding.default_external
-      orig_encoding = content.encoding
-
-      if not orig_encoding.ascii_compatible? then
-        content = content.encode encoding
-      elsif utf8 then
-        content = RDoc::Encoding.change_encoding content, Encoding::UTF_8
-        content = content.encode encoding
-      else
-        # assume the content is in our output encoding
-        content = RDoc::Encoding.change_encoding content, encoding
-      end
-
-      unless content.valid_encoding? then
-        # revert and try to transcode
-        content = RDoc::Encoding.change_encoding content, orig_encoding
-        content = content.encode encoding
+  # This class is a wrapper around File IO and Encoding that helps RDoc load
+  # files and convert them to the correct encoding.
+
+  module Encoding
+
+    HEADER_REGEXP = /\A
+      (?:
+        \#!.*\n
+        |
+        ^\#\s+frozen[-_]string[-_]literal[=:].+\n
+        |
+        ^\#\s*(?:-\*-\s*(?:[^;\n]*;\s*)*)?(?:en)?coding[=:]\s*(?<name>[^:\s;]+).*\n
+        |
+        <\?xml[^?]*encoding=(?<quote>["'])(?<name>.*?)\k<quote>.*\n
+      )+
+    /xi # :nodoc:
+
+    ##
+    # Reads the contents of +filename+ and handles any encoding directives in
+    # the file.
+    #
+    # The content will be converted to the +encoding+.  If the file cannot be
+    # converted a warning will be printed and nil will be returned.
+    #
+    # If +force_transcode+ is true the document will be transcoded and any
+    # unknown character in the target encoding will be replaced with '?'
+
+    def self.read_file(filename, encoding, force_transcode = false)
+      content = File.open filename, "rb" do |f| f.read end
+      content.gsub!("\r\n", "\n") if RUBY_PLATFORM =~ /mswin|mingw/
+
+      utf8 = content.sub!(/\A\xef\xbb\xbf/, '')
+
+      enc = Encoding.detect_encoding content
+      content = Encoding.change_encoding content, enc if enc
+
+      begin
+        encoding ||= ::Encoding.default_external
+        orig_encoding = content.encoding
+
+        if not orig_encoding.ascii_compatible?
+          content = content.encode encoding
+        elsif utf8
+          content = Encoding.change_encoding content, ::Encoding::UTF_8
+          content = content.encode encoding
+        else
+          # assume the content is in our output encoding
+          content = Encoding.change_encoding content, encoding
+        end
+
+        unless content.valid_encoding?
+          # revert and try to transcode
+          content = Encoding.change_encoding content, orig_encoding
+          content = content.encode encoding
+        end
+
+        unless content.valid_encoding?
+          warn "unable to convert #{filename} to #{encoding}, skipping"
+          content = nil
+        end
+      rescue ::Encoding::InvalidByteSequenceError,
+             ::Encoding::UndefinedConversionError => e
+        if force_transcode
+          content = Encoding.change_encoding content, orig_encoding
+          content = content.encode(encoding,
+                                   :invalid => :replace,
+                                   :undef => :replace,
+                                   :replace => '?')
+          return content
+        else
+          warn "unable to convert #{e.message} for #{filename}, skipping"
+          return nil
+        end
       end
 
-      unless content.valid_encoding? then
-        warn "unable to convert #{filename} to #{encoding}, skipping"
-        content = nil
-      end
-    rescue Encoding::InvalidByteSequenceError,
-           Encoding::UndefinedConversionError => e
-      if force_transcode then
-        content = RDoc::Encoding.change_encoding content, orig_encoding
-        content = content.encode(encoding,
-                                 :invalid => :replace,
-                                 :undef => :replace,
-                                 :replace => '?')
-        return content
-      else
-        warn "unable to convert #{e.message} for #{filename}, skipping"
-        return nil
-      end
+      content
+    rescue ArgumentError => e
+      raise unless e.message =~ /unknown encoding name - (.*)/
+      warn "unknown encoding name \"#{$1}\" for #{filename}, skipping"
+      nil
+    rescue Errno::EISDIR, Errno::ENOENT
+      nil
     end
 
-    content
-  rescue ArgumentError => e
-    raise unless e.message =~ /unknown encoding name - (.*)/
-    warn "unknown encoding name \"#{$1}\" for #{filename}, skipping"
-    nil
-  rescue Errno::EISDIR, Errno::ENOENT
-    nil
-  end
+    ##
+    # Detects the encoding of +string+ based on the magic comment
 
-  ##
-  # Detects the encoding of +string+ based on the magic comment
+    def self.detect_encoding(string)
+      result = HEADER_REGEXP.match string
+      name = result && result[:name]
 
-  def self.detect_encoding(string)
-    result = HEADER_REGEXP.match string
-    name = result && result[:name]
-
-    name ? Encoding.find(name) : nil
-  end
+      name ? ::Encoding.find(name) : nil
+    end
 
-  ##
-  # Removes magic comments and shebang
+    ##
+    # Removes magic comments and shebang
 
-  def self.remove_magic_comment(string)
-    string.sub HEADER_REGEXP do |s|
-      s.gsub(/[^\n]/, '')
+    def self.remove_magic_comment(string)
+      string.sub HEADER_REGEXP do |s|
+        s.gsub(/[^\n]/, '')
+      end
     end
-  end
 
-  ##
-  # Changes encoding based on +encoding+ without converting and returns new
-  # string
-
-  def self.change_encoding(text, encoding)
-    if text.kind_of? RDoc::Comment
-      text.encode! encoding
-    else
-      String.new text, encoding: encoding
+    ##
+    # Changes encoding based on +encoding+ without converting and returns new
+    # string
+
+    def self.change_encoding(text, encoding)
+      if text.kind_of? Comment
+        text.encode! encoding
+      else
+        String.new text, encoding: encoding
+      end
     end
-  end
 
+  end
 end