rdoc 3.1 → 6.3.3

data/lib/rdoc/cross_reference.rb

@@ -0,0 +1,202 @@
+# 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 method references.
+  #
+  # See CLASS_REGEXP_STR
+
+  METHOD_REGEXP_STR = '([a-z]\w*[!?=]?|%|===|\[\]=?|<<|>>|\+@|-@|-|\+|\*)(?:\([\w.+*/=<>-]*\))?'
+
+  ##
+  # 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}
+
+                       # Stand-alone method (preceded by a #)
+                       | \\?\##{METHOD_REGEXP_STR}
+
+                       # Stand-alone method (preceded by ::)
+                       | ::#{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)
+
+                       # 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}
+
+                       # Stand-alone method
+                       | \\?#{METHOD_REGEXP_STR}
+
+                       # A::B::C
+                       | #{CLASS_REGEXP_STR}(?=[@\s).?!,;<\000]|\z)
+
+                       # 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 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
+
+    if /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
+      type = $2
+      if '.' == type # will find either #method or ::method
+        method = $3
+      else
+        method = "#{type}#{$3}"
+      end
+      container = @context.find_symbol_module($1)
+    elsif /^([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
+      type = $1
+      if '.' == type
+        method = $2
+      else
+        method = "#{type}#{$2}"
+      end
+      container = @context
+    else
+      type = nil
+      container = nil
+    end
+
+    if container then
+      unless RDoc::TopLevel === container then
+        if '.' == type then
+          if 'new' == method then # AnyClassName.new will be class method
+            ref = container.find_local_symbol method
+            ref = container.find_ancestor_local_symbol method unless ref
+          else
+            ref = container.find_local_symbol "::#{method}"
+            ref = container.find_ancestor_local_symbol "::#{method}" unless ref
+            ref = container.find_local_symbol "##{method}" unless ref
+            ref = container.find_ancestor_local_symbol "##{method}" unless ref
+          end
+        else
+          ref = container.find_local_symbol method
+          ref = container.find_ancestor_local_symbol method unless ref
+        end
+      end
+    end
+
+    ref = case name
+          when /^\\(#{CLASS_REGEXP_STR})$/o then
+            @context.find_symbol $1
+          else
+            @context.find_symbol name
+          end unless ref
+
+    # Try a page name
+    ref = @store.page name if not ref and name =~ /^[\w.]+$/
+
+    ref = nil if RDoc::Alias === ref # external alias, can't link to it
+
+    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
+
+    @seen[name] = out
+
+    out
+  end
+
+end
+

data/lib/rdoc/encoding.rb

@@ -1,4 +1,5 @@
-require 'rdoc'
+# coding: US-ASCII
+# frozen_string_literal: true
 
 ##
 # This class is a wrapper around File IO and Encoding that helps RDoc load
@@ -6,42 +7,74 @@ require 'rdoc'
 
 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:
+
   ##
   # 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
-    content = open filename, "rb" do |f| f.read end
+  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/, '')
 
-    RDoc::Encoding.set_encoding content
+    enc = RDoc::Encoding.detect_encoding content
+    content = RDoc::Encoding.change_encoding content, enc if enc
 
-    if Object.const_defined? :Encoding then
+    begin
       encoding ||= Encoding.default_external
       orig_encoding = content.encoding
 
-      if utf8 then
-        content.force_encoding Encoding::UTF_8
-        content.encode! 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.force_encoding encoding
+        content = RDoc::Encoding.change_encoding content, encoding
       end
 
       unless content.valid_encoding? then
         # revert and try to transcode
-        content.force_encoding orig_encoding
-        content.encode! encoding
+        content = RDoc::Encoding.change_encoding content, orig_encoding
+        content = content.encode encoding
       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
     end
 
     content
@@ -49,33 +82,55 @@ module RDoc::Encoding
     raise unless e.message =~ /unknown encoding name - (.*)/
     warn "unknown encoding name \"#{$1}\" for #{filename}, skipping"
     nil
-  rescue Encoding::UndefinedConversionError => e
-    warn "unable to convert #{e.message} for #{filename}, skipping"
-    nil
   rescue Errno::EISDIR, Errno::ENOENT
     nil
   end
 
-  ##
-  # Sets the encoding of +string+ based on the magic comment
+  def self.remove_frozen_string_literal string
+    string =~ /\A(?:#!.*\n)?(.*\n)/
+    first_line = $1
 
-  def self.set_encoding string
-    first_line = string[/\A(?:#!.*\n)?.*\n/]
+    if first_line =~ /\A# +frozen[-_]string[-_]literal[=:].+$/i
+      string = string.sub first_line, ''
+    end
 
-    name = case first_line
-           when /^<\?xml[^?]*encoding=(["'])(.*?)\1/ then $2
-           when /\b(?:en)?coding[=:]\s*([^\s;]+)/i   then $1
-           else                                           return
-           end
+    string
+  end
 
-    string.sub! first_line, ''
+  ##
+  # Detects the encoding of +string+ based on the magic comment
 
-    return unless Object.const_defined? :Encoding
+  def self.detect_encoding string
+    result = HEADER_REGEXP.match string
+    name = result && result[:name]
 
-    enc = Encoding.find name
-    string.force_encoding enc if enc
+    name ? Encoding.find(name) : nil
   end
 
-end
+  ##
+  # Removes magic comments and shebang
 
+  def self.remove_magic_comment string
+    string.sub HEADER_REGEXP do |s|
+      s.gsub(/[^\n]/, '')
+    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
+      # TODO: Remove this condition after Ruby 2.2 EOL
+      if RUBY_VERSION < '2.3.0'
+        text.force_encoding encoding
+      else
+        String.new text, encoding: encoding
+      end
+    end
+  end
 
+end

data/lib/rdoc/erb_partial.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+##
+# Allows an ERB template to be rendered in the context (binding) of an
+# existing ERB template evaluation.
+
+class RDoc::ERBPartial < ERB
+
+  ##
+  # Overrides +compiler+ startup to set the +eoutvar+ to an empty string only
+  # if it isn't already set.
+
+  def set_eoutvar compiler, eoutvar = '_erbout'
+    super
+
+    compiler.pre_cmd = ["#{eoutvar} ||= +''"]
+  end
+
+end
+

data/lib/rdoc/erbio.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'erb'
 
 ##
@@ -8,7 +9,7 @@ require 'erb'
 #
 #   erbio = RDoc::ERBIO.new '<%= "hello world" %>', nil, nil
 #
-#   open 'hello.txt', 'w' do |io|
+#   File.open 'hello.txt', 'w' do |io|
 #     erbio.result binding
 #   end
 #
@@ -19,8 +20,12 @@ class RDoc::ERBIO < ERB
   ##
   # Defaults +eoutvar+ to 'io', otherwise is identical to ERB's initialize
 
-  def initialize str, safe_level = nil, trim_mode = nil, eoutvar = 'io'
-    super
+  def initialize str, safe_level = nil, legacy_trim_mode = nil, legacy_eoutvar = 'io', trim_mode: nil, eoutvar: 'io'
+    if RUBY_VERSION >= '2.6'
+      super(str, trim_mode: trim_mode, eoutvar: eoutvar)
+    else
+      super(str, safe_level, legacy_trim_mode, legacy_eoutvar)
+    end
   end
 
   ##

data/lib/rdoc/extend.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+##
+# A Module extension to a class with \#extend
+#
+#   RDoc::Extend.new 'Enumerable', 'comment ...'
+
+class RDoc::Extend < RDoc::Mixin
+
+end
+