rdoc 3.1 → 6.3.3

data/lib/rdoc/markup/to_label.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+require 'cgi'
+
+##
+# Creates HTML-safe labels suitable for use in id attributes.  Tidylinks are
+# converted to their link part and cross-reference links have the suppression
+# marks removed (\\SomeClass is converted to SomeClass).
+
+class RDoc::Markup::ToLabel < RDoc::Markup::Formatter
+
+  attr_reader :res # :nodoc:
+
+  ##
+  # Creates a new formatter that will output HTML-safe labels
+
+  def initialize markup = nil
+    super nil, markup
+
+    @markup.add_regexp_handling RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
+    @markup.add_regexp_handling(/(((\{.*?\})|\b\S+?)\[\S+?\])/, :TIDYLINK)
+
+    add_tag :BOLD, '', ''
+    add_tag :TT,   '', ''
+    add_tag :EM,   '', ''
+
+    @res = []
+  end
+
+  ##
+  # Converts +text+ to an HTML-safe label
+
+  def convert text
+    label = convert_flow @am.flow text
+
+    CGI.escape(label).gsub('%', '-').sub(/^-/, '')
+  end
+
+  ##
+  # Converts the CROSSREF +target+ to plain text, removing the suppression
+  # marker, if any
+
+  def handle_regexp_CROSSREF target
+    text = target.text
+
+    text.sub(/^\\/, '')
+  end
+
+  ##
+  # Converts the TIDYLINK +target+ to just the text part
+
+  def handle_regexp_TIDYLINK target
+    text = target.text
+
+    return text unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/
+
+    $1
+  end
+
+  alias accept_blank_line         ignore
+  alias accept_block_quote        ignore
+  alias accept_heading            ignore
+  alias accept_list_end           ignore
+  alias accept_list_item_end      ignore
+  alias accept_list_item_start    ignore
+  alias accept_list_start         ignore
+  alias accept_paragraph          ignore
+  alias accept_raw                ignore
+  alias accept_rule               ignore
+  alias accept_verbatim           ignore
+  alias end_accepting             ignore
+  alias handle_regexp_HARD_BREAK  ignore
+  alias start_accepting           ignore
+
+end
+

data/lib/rdoc/markup/to_markdown.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+# :markup: markdown
+
+##
+# Outputs parsed markup as Markdown
+
+class RDoc::Markup::ToMarkdown < RDoc::Markup::ToRdoc
+
+  ##
+  # Creates a new formatter that will output Markdown format text
+
+  def initialize markup = nil
+    super
+
+    @headings[1] = ['# ',      '']
+    @headings[2] = ['## ',     '']
+    @headings[3] = ['### ',    '']
+    @headings[4] = ['#### ',   '']
+    @headings[5] = ['##### ',  '']
+    @headings[6] = ['###### ', '']
+
+    add_regexp_handling_RDOCLINK
+    add_regexp_handling_TIDYLINK
+
+    @hard_break = "  \n"
+  end
+
+  ##
+  # Maps attributes to HTML sequences
+
+  def init_tags
+    add_tag :BOLD, '**', '**'
+    add_tag :EM,   '*',  '*'
+    add_tag :TT,   '`',  '`'
+  end
+
+  ##
+  # Adds a newline to the output
+
+  def handle_regexp_HARD_BREAK target
+    "  \n"
+  end
+
+  ##
+  # Finishes consumption of `list`
+
+  def accept_list_end list
+    @res << "\n"
+
+    super
+  end
+
+  ##
+  # Finishes consumption of `list_item`
+
+  def accept_list_item_end list_item
+    width = case @list_type.last
+            when :BULLET then
+              4
+            when :NOTE, :LABEL then
+              use_prefix
+
+              4
+            else
+              @list_index[-1] = @list_index.last.succ
+              4
+            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
+      bullets = Array(list_item.label).map do |label|
+        attributes(label).strip
+      end.join "\n"
+
+      bullets << "\n:"
+
+      @prefix = ' ' * @indent
+      @indent += 4
+      @prefix << bullets + (' ' * (@indent - 1))
+    else
+      bullet = type == :BULLET ? '*' : @list_index.last.to_s + '.'
+      @prefix = (' ' * @indent) + bullet.ljust(4)
+
+      @indent += 4
+    end
+  end
+
+  ##
+  # Prepares the visitor for consuming `list`
+
+  def accept_list_start list
+    case list.type
+    when :BULLET, :LABEL, :NOTE then
+      @list_index << nil
+    when :LALPHA, :NUMBER, :UALPHA then
+      @list_index << 1
+    else
+      raise RDoc::Error, "invalid list type #{list.type}"
+    end
+
+    @list_width << 4
+    @list_type << list.type
+  end
+
+  ##
+  # Adds `rule` to the output
+
+  def accept_rule rule
+    use_prefix or @res << ' ' * @indent
+    @res << '-' * 3
+    @res << "\n"
+  end
+
+  ##
+  # Outputs `verbatim` indented 4 columns
+
+  def accept_verbatim verbatim
+    indent = ' ' * (@indent + 4)
+
+    verbatim.parts.each do |part|
+      @res << indent unless part == "\n"
+      @res << part
+    end
+
+    @res << "\n"
+  end
+
+  ##
+  # Creates a Markdown-style URL from +url+ with +text+.
+
+  def gen_url url, text
+    scheme, url, = parse_url url
+
+    "[#{text.sub(%r{^#{scheme}:/*}i, '')}](#{url})"
+  end
+
+  ##
+  # Handles <tt>rdoc-</tt> type links for footnotes.
+
+  def handle_rdoc_link url
+    case url
+    when /^rdoc-ref:/ then
+      $'
+    when /^rdoc-label:footmark-(\d+)/ then
+      "[^#{$1}]:"
+    when /^rdoc-label:foottext-(\d+)/ then
+      "[^#{$1}]"
+    when /^rdoc-label:label-/ then
+      gen_url url, $'
+    when /^rdoc-image:/ then
+      "![](#{$'})"
+    when /^rdoc-[a-z]+:/ then
+      $'
+    end
+  end
+
+  ##
+  # Converts the RDoc markup tidylink into a Markdown.style link.
+
+  def handle_regexp_TIDYLINK target
+    text = target.text
+
+    return text unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/
+
+    label = $1
+    url   = $2
+
+    if url =~ /^rdoc-label:foot/ then
+      handle_rdoc_link url
+    else
+      gen_url url, label
+    end
+  end
+
+  ##
+  # Converts the rdoc-...: links into a Markdown.style links.
+
+  def handle_regexp_RDOCLINK target
+    handle_rdoc_link target.text
+  end
+
+end
+

data/lib/rdoc/markup/to_rdoc.rb

@@ -1,6 +1,4 @@
-require 'rdoc/markup/formatter'
-require 'rdoc/markup/inline'
-
+# frozen_string_literal: true
 ##
 # Outputs RDoc markup as RDoc markup! (mostly)
 
@@ -44,10 +42,10 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
   ##
   # Creates a new formatter that will output (mostly) \RDoc markup
 
-  def initialize
-    super
+  def initialize markup = nil
+    super nil, markup
 
-    @markup.add_special(/\\\S/, :SUPPRESSED_CROSSREF)
+    @markup.add_regexp_handling(/\\\S/, :SUPPRESSED_CROSSREF)
     @width = 78
     init_tags
 
@@ -60,6 +58,8 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     @headings[4] = ['==== ',   '']
     @headings[5] = ['===== ',  '']
     @headings[6] = ['====== ', '']
+
+    @hard_break = "\n"
   end
 
   ##
@@ -78,6 +78,21 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     @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
 
@@ -106,6 +121,11 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
             when :BULLET then
               2
             when :NOTE, :LABEL then
+              if @prefix then
+                @res << @prefix.strip
+                @prefix = nil
+              end
+
               @res << "\n"
               2
             else
@@ -125,10 +145,15 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
 
     case type
     when :NOTE, :LABEL then
-      bullet = attributes(list_item.label) + ":\n"
+      bullets = Array(list_item.label).map do |label|
+        attributes(label).strip
+      end.join "\n"
+
+      bullets << ":\n" unless bullets.empty?
+
       @prefix = ' ' * @indent
       @indent += 2
-      @prefix << bullet + (' ' * @indent)
+      @prefix << bullets + (' ' * @indent)
     else
       bullet = type == :BULLET ? '*' :  @list_index.last.to_s + '.'
       @prefix = (' ' * @indent) + bullet.ljust(bullet.length + 1)
@@ -168,7 +193,18 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
   # Adds +paragraph+ to the output
 
   def accept_paragraph paragraph
-    wrap attributes(paragraph.text)
+    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
 
   ##
@@ -198,7 +234,35 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
       @res << part
     end
 
-    @res << "\n" unless @res =~ /\n\z/
+    @res << "\n"
+  end
+
+  ##
+  # Adds +table+ to the output
+
+  def accept_table header, body, aligns
+    widths = header.zip(body) do |h, b|
+      [h.size, b.size].max
+    end
+    aligns = aligns.map do |a|
+      case a
+      when nil
+        :center
+      when :left
+        :ljust
+      when :right
+        :rjust
+      end
+    end
+    @res << header.zip(widths, aligns) 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) do |t, w, a|
+        t.__send__(a, w)
+      end.join("|").rstrip << "\n"
+    end
   end
 
   ##
@@ -217,14 +281,21 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
   end
 
   ##
-  # Removes preceeding \\ from the suppressed crossref +special+
+  # Removes preceding \\ from the suppressed crossref +target+
 
-  def handle_special_SUPPRESSED_CROSSREF special
-    text = special.text
+  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
 
@@ -243,8 +314,7 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
   # prefix for later consumption.
 
   def use_prefix
-    prefix = @prefix
-    @prefix = nil
+    prefix, @prefix = @prefix, nil
     @res << prefix if prefix
 
     prefix

data/lib/rdoc/markup/to_table_of_contents.rb

@@ -0,0 +1,89 @@
+# 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/lib/rdoc/markup/to_test.rb

@@ -1,6 +1,4 @@
-require 'rdoc/markup'
-require 'rdoc/markup/formatter'
-
+# frozen_string_literal: true
 ##
 # This Markup outputter is used for testing purposes.
 
@@ -21,7 +19,7 @@ class RDoc::Markup::ToTest < RDoc::Markup::Formatter
   end
 
   def accept_paragraph(paragraph)
-    @res << paragraph.text
+    @res << convert_flow(@am.flow(paragraph.text))
   end
 
   def accept_raw raw

data/lib/rdoc/markup/to_tt_only.rb

@@ -0,0 +1,121 @@
+# 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/lib/rdoc/markup/verbatim.rb

@@ -1,8 +1,24 @@
+# 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+
 
@@ -34,6 +50,29 @@ class RDoc::Markup::Verbatim < RDoc::Markup::Raw
     @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