docspring 3.0.0 → 3.1.0

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

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+##
+# Outputs RDoc markup as RDoc markup! (mostly)
+
+class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
+
+  ##
+  # Current indent amount for output in characters
+
+  attr_accessor :indent
+
+  ##
+  # Output width in characters
+
+  attr_accessor :width
+
+  ##
+  # Stack of current list indexes for alphabetic and numeric lists
+
+  attr_reader :list_index
+
+  ##
+  # Stack of list types
+
+  attr_reader :list_type
+
+  ##
+  # Stack of list widths for indentation
+
+  attr_reader :list_width
+
+  ##
+  # Prefix for the next list item.  See #use_prefix
+
+  attr_reader :prefix
+
+  ##
+  # Output accumulator
+
+  attr_reader :res
+
+  ##
+  # Creates a new formatter that will output (mostly) \RDoc markup
+
+  def initialize markup = nil
+    super nil, markup
+
+    @markup.add_regexp_handling(/\\\S/, :SUPPRESSED_CROSSREF)
+    @width = 78
+    init_tags
+
+    @headings = {}
+    @headings.default = []
+
+    @headings[1] = ['= ',      '']
+    @headings[2] = ['== ',     '']
+    @headings[3] = ['=== ',    '']
+    @headings[4] = ['==== ',   '']
+    @headings[5] = ['===== ',  '']
+    @headings[6] = ['====== ', '']
+
+    @hard_break = "\n"
+  end
+
+  ##
+  # Maps attributes to HTML sequences
+
+  def init_tags
+    add_tag :BOLD, "<b>", "</b>"
+    add_tag :TT,   "<tt>", "</tt>"
+    add_tag :EM,   "<em>", "</em>"
+  end
+
+  ##
+  # Adds +blank_line+ to the output
+
+  def accept_blank_line blank_line
+    @res << "\n"
+  end
+
+  ##
+  # Adds +paragraph+ to the output
+
+  def accept_block_quote block_quote
+    @indent += 2
+
+    block_quote.parts.each do |part|
+      @prefix = '> '
+
+      part.accept self
+    end
+
+    @indent -= 2
+  end
+
+  ##
+  # Adds +heading+ to the output
+
+  def accept_heading heading
+    use_prefix or @res << ' ' * @indent
+    @res << @headings[heading.level][0]
+    @res << attributes(heading.text)
+    @res << @headings[heading.level][1]
+    @res << "\n"
+  end
+
+  ##
+  # Finishes consumption of +list+
+
+  def accept_list_end list
+    @list_index.pop
+    @list_type.pop
+    @list_width.pop
+  end
+
+  ##
+  # Finishes consumption of +list_item+
+
+  def accept_list_item_end list_item
+    width = case @list_type.last
+            when :BULLET then
+              2
+            when :NOTE, :LABEL then
+              if @prefix then
+                @res << @prefix.strip
+                @prefix = nil
+              end
+
+              @res << "\n"
+              2
+            else
+              bullet = @list_index.last.to_s
+              @list_index[-1] = @list_index.last.succ
+              bullet.length + 2
+            end
+
+    @indent -= width
+  end
+
+  ##
+  # Prepares the visitor for consuming +list_item+
+
+  def accept_list_item_start list_item
+    type = @list_type.last
+
+    case type
+    when :NOTE, :LABEL then
+      stripped_labels = Array(list_item.label).map do |label|
+        attributes(label).strip
+      end
+
+      bullets = case type
+      when :NOTE
+        stripped_labels.map { |b| "#{b}::" }
+      when :LABEL
+        stripped_labels.map { |b| "[#{b}]" }
+      end
+
+      bullets = bullets.join("\n")
+      bullets << "\n" unless stripped_labels.empty?
+
+      @prefix = ' ' * @indent
+      @indent += 2
+      @prefix << bullets + (' ' * @indent)
+    else
+      bullet = type == :BULLET ? '*' :  @list_index.last.to_s + '.'
+      @prefix = (' ' * @indent) + bullet.ljust(bullet.length + 1)
+      width = bullet.length + 1
+      @indent += width
+    end
+  end
+
+  ##
+  # Prepares the visitor for consuming +list+
+
+  def accept_list_start list
+    case list.type
+    when :BULLET then
+      @list_index << nil
+      @list_width << 1
+    when :LABEL, :NOTE then
+      @list_index << nil
+      @list_width << 2
+    when :LALPHA then
+      @list_index << 'a'
+      @list_width << list.items.length.to_s.length
+    when :NUMBER then
+      @list_index << 1
+      @list_width << list.items.length.to_s.length
+    when :UALPHA then
+      @list_index << 'A'
+      @list_width << list.items.length.to_s.length
+    else
+      raise RDoc::Error, "invalid list type #{list.type}"
+    end
+
+    @list_type << list.type
+  end
+
+  ##
+  # Adds +paragraph+ to the output
+
+  def accept_paragraph paragraph
+    text = paragraph.text @hard_break
+    wrap attributes text
+  end
+
+  ##
+  # Adds +paragraph+ to the output
+
+  def accept_indented_paragraph paragraph
+    @indent += paragraph.indent
+    text = paragraph.text @hard_break
+    wrap attributes text
+    @indent -= paragraph.indent
+  end
+
+  ##
+  # Adds +raw+ to the output
+
+  def accept_raw raw
+    @res << raw.parts.join("\n")
+  end
+
+  ##
+  # Adds +rule+ to the output
+
+  def accept_rule rule
+    use_prefix or @res << ' ' * @indent
+    @res << '-' * (@width - @indent)
+    @res << "\n"
+  end
+
+  ##
+  # Outputs +verbatim+ indented 2 columns
+
+  def accept_verbatim verbatim
+    indent = ' ' * (@indent + 2)
+
+    verbatim.parts.each do |part|
+      @res << indent unless part == "\n"
+      @res << part
+    end
+
+    @res << "\n"
+  end
+
+  ##
+  # Adds +table+ to the output
+
+  def accept_table header, body, aligns
+    widths = header.zip(*body).map do |cols|
+      cols.map(&:size).max
+    end
+    aligns = aligns.map do |a|
+      case a
+      when nil, :center
+        :center
+      when :left
+        :ljust
+      when :right
+        :rjust
+      end
+    end
+    @res << header.zip(widths, aligns).map do |h, w, a|
+      h.__send__(a, w)
+    end.join("|").rstrip << "\n"
+    @res << widths.map {|w| "-" * w }.join("|") << "\n"
+    body.each do |row|
+      @res << row.zip(widths, aligns).map do |t, w, a|
+        t.__send__(a, w)
+      end.join("|").rstrip << "\n"
+    end
+  end
+
+  ##
+  # Applies attribute-specific markup to +text+ using RDoc::AttributeManager
+
+  def attributes text
+    flow = @am.flow text.dup
+    convert_flow flow
+  end
+
+  ##
+  # Returns the generated output
+
+  def end_accepting
+    @res.join
+  end
+
+  ##
+  # Removes preceding \\ from the suppressed crossref +target+
+
+  def handle_regexp_SUPPRESSED_CROSSREF target
+    text = target.text
+    text = text.sub('\\', '') unless in_tt?
+    text
+  end
+
+  ##
+  # Adds a newline to the output
+
+  def handle_regexp_HARD_BREAK target
+    "\n"
+  end
+
+  ##
+  # Prepares the visitor for text generation
+
+  def start_accepting
+    @res = [""]
+    @indent = 0
+    @prefix = nil
+
+    @list_index = []
+    @list_type  = []
+    @list_width = []
+  end
+
+  ##
+  # Adds the stored #prefix to the output and clears it.  Lists generate a
+  # prefix for later consumption.
+
+  def use_prefix
+    prefix, @prefix = @prefix, nil
+    @res << prefix if prefix
+
+    prefix
+  end
+
+  ##
+  # Wraps +text+ to #width
+
+  def wrap text
+    return unless text && !text.empty?
+
+    text_len = @width - @indent
+
+    text_len = 20 if text_len < 20
+
+    next_prefix = ' ' * @indent
+
+    prefix = @prefix || next_prefix
+    @prefix = nil
+
+    text.scan(/\G(?:([^ \n]{#{text_len}})(?=[^ \n])|(.{1,#{text_len}})(?:[ \n]|\z))/) do
+      @res << prefix << ($1 || $2) << "\n"
+      prefix = next_prefix
+    end
+  end
+
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+##
+# Extracts just the RDoc::Markup::Heading elements from a
+# RDoc::Markup::Document to help build a table of contents
+
+class RDoc::Markup::ToTableOfContents < RDoc::Markup::Formatter
+
+  @to_toc = nil
+
+  ##
+  # Singleton for table-of-contents generation
+
+  def self.to_toc
+    @to_toc ||= new
+  end
+
+  ##
+  # Output accumulator
+
+  attr_reader :res
+
+  ##
+  # Omits headings with a level less than the given level.
+
+  attr_accessor :omit_headings_below
+
+  def initialize # :nodoc:
+    super nil
+
+    @omit_headings_below = nil
+  end
+
+  ##
+  # Adds +document+ to the output, using its heading cutoff if present
+
+  def accept_document document
+    @omit_headings_below = document.omit_headings_below
+
+    super
+  end
+
+  ##
+  # Adds +heading+ to the table of contents
+
+  def accept_heading heading
+    @res << heading unless suppressed? heading
+  end
+
+  ##
+  # Returns the table of contents
+
+  def end_accepting
+    @res
+  end
+
+  ##
+  # Prepares the visitor for text generation
+
+  def start_accepting
+    @omit_headings_below = nil
+    @res = []
+  end
+
+  ##
+  # Returns true if +heading+ is below the display threshold
+
+  def suppressed? heading
+    return false unless @omit_headings_below
+
+    heading.level > @omit_headings_below
+  end
+
+  # :stopdoc:
+  alias accept_block_quote     ignore
+  alias accept_raw             ignore
+  alias accept_rule            ignore
+  alias accept_blank_line      ignore
+  alias accept_paragraph       ignore
+  alias accept_verbatim        ignore
+  alias accept_list_end        ignore
+  alias accept_list_item_start ignore
+  alias accept_list_item_end   ignore
+  alias accept_list_end_bullet ignore
+  alias accept_list_start      ignore
+  alias accept_table           ignore
+  # :startdoc:
+
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+##
+# This Markup outputter is used for testing purposes.
+
+class RDoc::Markup::ToTest < RDoc::Markup::Formatter
+
+  # :stopdoc:
+
+  ##
+  # :section: Visitor
+
+  def start_accepting
+    @res = []
+    @list = []
+  end
+
+  def end_accepting
+    @res
+  end
+
+  def accept_paragraph(paragraph)
+    @res << convert_flow(@am.flow(paragraph.text))
+  end
+
+  def accept_raw raw
+    @res << raw.parts.join
+  end
+
+  def accept_verbatim(verbatim)
+    @res << verbatim.text.gsub(/^(\S)/, '  \1')
+  end
+
+  def accept_list_start(list)
+    @list << case list.type
+             when :BULLET then
+               '*'
+             when :NUMBER then
+               '1'
+             else
+               list.type
+             end
+  end
+
+  def accept_list_end(list)
+    @list.pop
+  end
+
+  def accept_list_item_start(list_item)
+    @res << "#{' ' * (@list.size - 1)}#{@list.last}: "
+  end
+
+  def accept_list_item_end(list_item)
+  end
+
+  def accept_blank_line(blank_line)
+    @res << "\n"
+  end
+
+  def accept_heading(heading)
+    @res << "#{'=' * heading.level} #{heading.text}"
+  end
+
+  def accept_rule(rule)
+    @res << '-' * rule.weight
+  end
+
+  # :startdoc:
+
+end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+##
+# Extracts sections of text enclosed in plus, tt or code.  Used to discover
+# undocumented parameters.
+
+class RDoc::Markup::ToTtOnly < RDoc::Markup::Formatter
+
+  ##
+  # Stack of list types
+
+  attr_reader :list_type
+
+  ##
+  # Output accumulator
+
+  attr_reader :res
+
+  ##
+  # Creates a new tt-only formatter.
+
+  def initialize markup = nil
+    super nil, markup
+
+    add_tag :TT, nil, nil
+  end
+
+  ##
+  # Adds tts from +block_quote+ to the output
+
+  def accept_block_quote block_quote
+    tt_sections block_quote.text
+  end
+
+  ##
+  # Pops the list type for +list+ from #list_type
+
+  def accept_list_end list
+    @list_type.pop
+  end
+
+  ##
+  # Pushes the list type for +list+ onto #list_type
+
+  def accept_list_start list
+    @list_type << list.type
+  end
+
+  ##
+  # Prepares the visitor for consuming +list_item+
+
+  def accept_list_item_start list_item
+    case @list_type.last
+    when :NOTE, :LABEL then
+      Array(list_item.label).map do |label|
+        tt_sections label
+      end.flatten
+    end
+  end
+
+  ##
+  # Adds +paragraph+ to the output
+
+  def accept_paragraph paragraph
+    tt_sections(paragraph.text)
+  end
+
+  ##
+  # Does nothing to +markup_item+ because it doesn't have any user-built
+  # content
+
+  def do_nothing markup_item
+  end
+
+  alias accept_blank_line    do_nothing # :nodoc:
+  alias accept_heading       do_nothing # :nodoc:
+  alias accept_list_item_end do_nothing # :nodoc:
+  alias accept_raw           do_nothing # :nodoc:
+  alias accept_rule          do_nothing # :nodoc:
+  alias accept_verbatim      do_nothing # :nodoc:
+
+  ##
+  # Extracts tt sections from +text+
+
+  def tt_sections text
+    flow = @am.flow text.dup
+
+    flow.each do |item|
+      case item
+      when String then
+        @res << item if in_tt?
+      when RDoc::Markup::AttrChanger then
+        off_tags res, item
+        on_tags res, item
+      when RDoc::Markup::RegexpHandling then
+        @res << convert_regexp_handling(item) if in_tt? # TODO can this happen?
+      else
+        raise "Unknown flow element: #{item.inspect}"
+      end
+    end
+
+    res
+  end
+
+  ##
+  # Returns an Array of items that were wrapped in plus, tt or code.
+
+  def end_accepting
+    @res.compact
+  end
+
+  ##
+  # Prepares the visitor for gathering tt sections
+
+  def start_accepting
+    @res = []
+
+    @list_type = []
+  end
+
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+##
+# A section of verbatim text
+
+class RDoc::Markup::Verbatim < RDoc::Markup::Raw
+
+  ##
+  # Format of this verbatim section
+
+  attr_accessor :format
+
+  def initialize *parts # :nodoc:
+    super
+
+    @format = nil
+  end
+
+  def == other # :nodoc:
+    super and @format == other.format
+  end
+
+  ##
+  # Calls #accept_verbatim on +visitor+
+
+  def accept visitor
+    visitor.accept_verbatim self
+  end
+
+  ##
+  # Collapses 3+ newlines into two newlines
+
+  def normalize
+    parts = []
+
+    newlines = 0
+
+    @parts.each do |part|
+      case part
+      when /^\s*\n/ then
+        newlines += 1
+        parts << part if newlines == 1
+      else
+        newlines = 0
+        parts << part
+      end
+    end
+
+    parts.pop if parts.last =~ /\A\r?\n\z/
+
+    @parts = parts
+  end
+
+  def pretty_print q # :nodoc:
+    self.class.name =~ /.*::(\w{1,4})/i
+
+    q.group 2, "[#{$1.downcase}: ", ']' do
+      if @format then
+        q.text "format: #{@format}"
+        q.breakable
+      end
+
+      q.seplist @parts do |part|
+        q.pp part
+      end
+    end
+  end
+
+  ##
+  # Is this verbatim section Ruby code?
+
+  def ruby?
+    @format ||= nil # TODO for older ri data, switch the tree to marshal_dump
+    @format == :ruby
+  end
+
+  ##
+  # The text of the section
+
+  def text
+    @parts.join
+  end
+
+end