docspring 3.0.0 → 3.1.0

data/vendor/bundle/ruby/3.3.0/gems/rdoc-6.12.0/lib/rdoc/cross_reference.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require_relative 'markup/attribute_manager' # for PROTECT_ATTR
+
+##
+# 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#{RDoc::Markup::AttributeManager::PROTECT_ATTR}]+[!?=]?|
+    %|=(?:==?|~)|![=~]|\[\]=?|<(?:<|=>?)?|>[>=]?|[-+!]@?|\*\*?|[\/%\`|&^~]
+  )#{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 reference to +name+.
+
+  def resolve_method name
+    ref = nil
+
+    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
+  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
+
+    ref = case name
+          when /^\\(#{CLASS_REGEXP_STR})$/o then
+            @context.find_symbol $1
+          else
+            @context.find_symbol name
+          end
+
+    ref = resolve_method name 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/vendor/bundle/ruby/3.3.0/gems/rdoc-6.12.0/lib/rdoc/encoding.rb

@@ -0,0 +1,120 @@
+# 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:
+
+  ##
+  # 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
+      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
+  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
+
+  def self.detect_encoding string
+    result = HEADER_REGEXP.match string
+    name = result && result[:name]
+
+    name ? Encoding.find(name) : nil
+  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
+      String.new text, encoding: encoding
+    end
+  end
+
+end

data/vendor/bundle/ruby/3.3.0/gems/rdoc-6.12.0/lib/rdoc/erb_partial.rb

@@ -0,0 +1,18 @@
+# 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/vendor/bundle/ruby/3.3.0/gems/rdoc-6.12.0/lib/rdoc/erbio.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+require 'erb'
+
+##
+# A subclass of ERB that writes directly to an IO.  Credit to Aaron Patterson
+# and Masatoshi SEKI.
+#
+# To use:
+#
+#   erbio = RDoc::ERBIO.new '<%= "hello world" %>', nil, nil
+#
+#   File.open 'hello.txt', 'w' do |io|
+#     erbio.result binding
+#   end
+#
+# Note that binding must enclose the io you wish to output on.
+
+class RDoc::ERBIO < ERB
+
+  ##
+  # Defaults +eoutvar+ to 'io', otherwise is identical to ERB's initialize
+
+  def initialize str, trim_mode: nil, eoutvar: 'io'
+    super(str, trim_mode: trim_mode, eoutvar: eoutvar)
+  end
+
+  ##
+  # Instructs +compiler+ how to write to +io_variable+
+
+  def set_eoutvar compiler, io_variable
+    compiler.put_cmd    = "#{io_variable}.write"
+    compiler.insert_cmd = "#{io_variable}.write"
+    compiler.pre_cmd    = []
+    compiler.post_cmd   = []
+  end
+
+end