mega-max-hub 0.0.1

data/rdoc-8.0.0/lib/rdoc/comment.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+##
+# A comment holds the text comment for a RDoc::CodeObject and provides a
+# unified way of cleaning it up and parsing it into an RDoc::Markup::Document.
+#
+# Each comment may have a different markup format set by #format=.  By default
+# 'rdoc' is used.  The :markup: directive tells RDoc which format to use.
+#
+# See {RDoc Markup Reference}[rdoc-ref:doc/markup_reference/rdoc.rdoc@Directive+for+Specifying+RDoc+Source+Format].
+
+
+class RDoc::Comment
+
+  include RDoc::Text
+
+  ##
+  # The format of this comment.  Defaults to RDoc::Markup
+
+  attr_reader :format
+
+  ##
+  # The RDoc::TopLevel this comment was found in
+
+  attr_accessor :location
+
+  ##
+  # Line where this Comment was written
+
+  attr_accessor :line
+
+  ##
+  # For duck-typing when merging classes at load time
+
+  alias file location # :nodoc:
+
+  ##
+  # The text for this comment
+
+  attr_reader :text
+
+  ##
+  # Alias for text
+
+  alias to_s text
+
+  ##
+  # Overrides the content returned by #parse.  Use when there is no #text
+  # source for this comment
+
+  attr_writer   :document
+
+  ##
+  # Creates a new comment with +text+ that is found in the RDoc::TopLevel
+  # +location+.
+
+  def initialize(text = nil, location = nil, language = nil)
+    @location = location
+    @text     = text.nil? ? nil : text.dup
+    @language = language
+
+    @document   = nil
+    @format     = 'rdoc'
+    @normalized = false
+  end
+
+  ##
+  #--
+  # TODO deep copy @document
+
+  def initialize_copy(copy) # :nodoc:
+    @text = copy.text.dup
+  end
+
+  def ==(other) # :nodoc:
+    self.class === other and
+      other.text == @text and other.location == @location
+  end
+
+  ##
+  # A comment is empty if its text String is empty.
+
+  def empty?
+    @text.empty? && (@document.nil? || @document.empty?)
+  end
+
+  ##
+  # HACK dubious
+
+  def encode!(encoding)
+    @text = String.new @text, encoding: encoding
+    self
+  end
+
+  ##
+  # Sets the format of this comment and resets any parsed document
+
+  def format=(format)
+    @format = format
+    @document = nil
+  end
+
+  def inspect # :nodoc:
+    location = @location ? @location.relative_name : '(unknown)'
+
+    "#<%s:%x %s %p>" % [self.class, object_id, location, @text]
+  end
+
+  ##
+  # Normalizes the text.  See RDoc::Text#normalize_comment for details
+
+  def normalize
+    return self unless @text
+    return self if @normalized # TODO eliminate duplicate normalization
+
+    @text = normalize_comment @text
+
+    @normalized = true
+
+    self
+  end
+
+  # Change normalized, when creating already normalized comment.
+
+  def normalized=(value)
+    @normalized = value
+  end
+
+  ##
+  # Was this text normalized?
+
+  def normalized? # :nodoc:
+    @normalized
+  end
+
+  ##
+  # Parses the comment into an RDoc::Markup::Document.  The parsed document is
+  # cached until the text is changed.
+
+  def parse
+    return @document if @document
+
+    @document = super @text, @format
+    @document.file = @location
+    @document
+  end
+
+  ##
+  # Replaces this comment's text with +text+ and resets the parsed document.
+  #
+  # An error is raised if the comment contains a document but no text.
+
+  def text=(text)
+    raise RDoc::Error, 'replacing document-only comment is not allowed' if
+      @text.nil? and @document
+
+    @document = nil
+    @text = text.nil? ? nil : text.dup
+  end
+
+  ##
+  # Returns true if this comment is in TomDoc format.
+
+  def tomdoc?
+    @format == 'tomdoc'
+  end
+
+  MULTILINE_DIRECTIVES = %w[call-seq].freeze # :nodoc:
+
+  # There are more, but already handled by RDoc::Parser::C
+  COLON_LESS_DIRECTIVES = %w[call-seq Document-method].freeze # :nodoc:
+
+  DIRECTIVE_OR_ESCAPED_DIRECTIV_REGEXP = /\A(?<colon>\\?:|:?)(?<directive>[\w-]+):(?<param>.*)/
+
+  private_constant :MULTILINE_DIRECTIVES, :COLON_LESS_DIRECTIVES, :DIRECTIVE_OR_ESCAPED_DIRECTIV_REGEXP
+
+  class << self
+
+    ##
+    # Create a new parsed comment from a document
+
+    def from_document(document) # :nodoc:
+      comment = RDoc::Comment.new('')
+      comment.document = document
+      comment.location = RDoc::TopLevel.new(document.file) if document.file
+      comment
+    end
+
+    # Parse comment, collect directives as an attribute and return [normalized_comment_text, directives_hash]
+    # This method expands include and removes everything not needed in the document text, such as
+    # private section, directive line, comment characters `# /* * */` and indent spaces.
+    #
+    # RDoc comment consists of include, directive, multiline directive, private section and comment text.
+    #
+    # Include
+    #   # :include: filename
+    #
+    # Directive
+    #   # :directive-without-value:
+    #   # :directive-with-value: value
+    #
+    # Multiline directive (only :call-seq:)
+    #   # :multiline-directive:
+    #   #   value1
+    #   #   value2
+    #
+    # Private section
+    #   #--
+    #   # private comment
+    #   #++
+
+    def parse(text, filename, line_no, type, &include_callback)
+      case type
+      when :ruby
+        text = text.gsub(/^#+/, '') if text.start_with?('#')
+        private_start_regexp = /^-{2,}$/
+        private_end_regexp = /^\+{2}$/
+        indent_regexp = /^\s*/
+      when :c
+        private_start_regexp = /^(\s*\*)?-{2,}$/
+        private_end_regexp = /^(\s*\*)?\+{2}$/
+        indent_regexp = /^\s*(\/\*+|\*)?\s*/
+        text = text.gsub(/\s*\*+\/\s*\z/, '')
+      when :simple
+        # Unlike other types, this implementation only looks for two dashes at
+        # the beginning of the line. Three or more dashes are considered to be
+        # a rule and ignored.
+        private_start_regexp = /^-{2}$/
+        private_end_regexp = /^\+{2}$/
+        indent_regexp = /^\s*/
+      end
+
+      directives = {}
+      lines = text.split("\n")
+      in_private = false
+      comment_lines = []
+      until lines.empty?
+        line = lines.shift
+        read_lines = 1
+        if in_private
+          # If `++` appears in a private section that starts with `--`, private section ends.
+          in_private = false if line.match?(private_end_regexp)
+          line_no += read_lines
+          next
+        elsif line.match?(private_start_regexp)
+          # If `--` appears in a line, private section starts.
+          in_private = true
+          line_no += read_lines
+          next
+        end
+
+        prefix = line[indent_regexp]
+        prefix_indent = ' ' * prefix.size
+        line = line.byteslice(prefix.bytesize..)
+
+        if (directive_match = DIRECTIVE_OR_ESCAPED_DIRECTIV_REGEXP.match(line))
+          colon = directive_match[:colon]
+          directive = directive_match[:directive]
+          raw_param = directive_match[:param]
+          param = raw_param.strip
+        else
+          colon = directive = raw_param = param = nil
+        end
+
+        if !directive
+          comment_lines << prefix_indent + line
+        elsif colon == '\\:'
+          # If directive is escaped, unescape it
+          comment_lines << prefix_indent + line.sub('\\:', ':')
+        elsif raw_param.start_with?(':') || (colon.empty? && !COLON_LESS_DIRECTIVES.include?(directive))
+          # Something like `:toto::` is not a directive
+          # Only few directives allows to start without a colon
+          comment_lines << prefix_indent + line
+        elsif directive == 'include'
+          filename_to_include = param
+          include_callback.call(filename_to_include, prefix_indent).lines.each { |l| comment_lines << l.chomp }
+        elsif MULTILINE_DIRECTIVES.include?(directive)
+          value_lines = take_multiline_directive_value_lines(directive, filename, line_no, lines, prefix_indent.size, indent_regexp, !param.empty?)
+          read_lines += value_lines.size
+          lines.shift(value_lines.size)
+          unless param.empty?
+            # Accept `:call-seq: first-line\n  second-line` for now
+            value_lines.unshift(param)
+          end
+          value = value_lines.join("\n")
+          directives[directive] = [value.empty? ? nil : value, line_no]
+        else
+          directives[directive] = [param.empty? ? nil : param, line_no]
+        end
+        line_no += read_lines
+      end
+
+      normalized_comment = String.new(encoding: text.encoding) << normalize_comment_lines(comment_lines).join("\n")
+      [normalized_comment, directives]
+    end
+
+    # Remove preceding indent spaces and blank lines from the comment lines
+
+    private def normalize_comment_lines(lines)
+      blank_line_regexp = /\A\s*\z/
+      lines = lines.dup
+      lines.shift while lines.first&.match?(blank_line_regexp)
+      lines.pop while lines.last&.match?(blank_line_regexp)
+
+      min_spaces = lines.map do |l|
+        l.match(/\A *(?=\S)/)&.end(0)
+      end.compact.min
+      if min_spaces && min_spaces > 0
+        lines.map { |l| l[min_spaces..] || '' }
+      else
+        lines
+      end
+    end
+
+    # Take value lines of multiline directive
+
+    private def take_multiline_directive_value_lines(directive, filename, line_no, lines, base_indent_size, indent_regexp, has_param)
+      return [] if lines.empty?
+
+      first_indent_size = lines.first.match(indent_regexp).end(0)
+
+      # Blank line or unindented line is not part of multiline-directive value
+      return [] if first_indent_size <= base_indent_size
+
+      if has_param
+        # :multiline-directive: line1
+        #   line2
+        #   line3
+        #
+        value_lines = lines.take_while do |l|
+          l.rstrip.match(indent_regexp).end(0) > base_indent_size
+        end
+        min_indent = value_lines.map { |l| l.match(indent_regexp).end(0) }.min
+        value_lines.map { |l| l[min_indent..] }
+      else
+        # Take indented lines accepting blank lines between them
+        value_lines = lines.take_while do |l|
+          l = l.rstrip
+          indent = l[indent_regexp]
+          if indent == l || indent.size >= first_indent_size
+            true
+          end
+        end
+        value_lines.map! { |l| (l[first_indent_size..] || '').chomp }
+
+        if value_lines.size != lines.size && !value_lines.last.empty?
+          warn "#{filename}:#{line_no} Multiline directive :#{directive}: should end with a blank line."
+        end
+        value_lines.pop while value_lines.last&.empty?
+        value_lines
+      end
+    end
+  end
+end

data/rdoc-8.0.0/lib/rdoc/cross_reference.rb

@@ -0,0 +1,215 @@
+# 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
+
+  ##
+  # 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
+        symbol = $2
+      else
+        symbol = "#{type}#{$2}"
+      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
+            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
+    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.
+
+  def resolve(name)
+    return @seen[name] if @seen.include? name
+
+    ref = @context.find_symbol name
+
+    ref = resolve_local_symbol 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
+
+    ref = nil unless ref&.display?
+
+    @seen[name] = ref
+
+    ref
+  end
+
+end

data/rdoc-8.0.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
+      |
+      ^\#\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 = 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/rdoc-8.0.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