rdoc 3.1 → 6.3.3

data/lib/rdoc/markup/formatter.rb

@@ -1,9 +1,14 @@
-require 'rdoc/markup'
-
+# frozen_string_literal: true
 ##
 # Base class for RDoc markup formatters
 #
-# Formatters use a visitor pattern to convert content into output.
+# Formatters are a visitor that converts an RDoc::Markup tree (from a comment)
+# into some kind of output.  RDoc ships with formatters for converting back to
+# rdoc, ANSI text, HTML, a Table of Contents and other formats.
+#
+# If you'd like to write your own Formatter use
+# RDoc::Markup::FormatterTestCase.  If you're writing a text-output formatter
+# use RDoc::Markup::TextFormatterTestCase which provides extra test cases.
 
 class RDoc::Markup::Formatter
 
@@ -13,16 +18,84 @@ class RDoc::Markup::Formatter
 
   InlineTag = Struct.new(:bit, :on, :off)
 
+  ##
+  # Converts a target url to one that is relative to a given path
+
+  def self.gen_relative_url path, target
+    from        = File.dirname path
+    to, to_file = File.split target
+
+    from = from.split "/"
+    to   = to.split "/"
+
+    from.delete '.'
+    to.delete '.'
+
+    while from.size > 0 and to.size > 0 and from[0] == to[0] do
+      from.shift
+      to.shift
+    end
+
+    from.fill ".."
+    from.concat to
+    from << to_file
+    File.join(*from)
+  end
+
   ##
   # Creates a new Formatter
 
-  def initialize
-    @markup = RDoc::Markup.new
-    @am = @markup.attribute_manager
+  def initialize options, markup = nil
+    @options = options
+
+    @markup = markup || RDoc::Markup.new
+    @am     = @markup.attribute_manager
+    @am.add_regexp_handling(/<br>/, :HARD_BREAK)
+
+    @attributes = @am.attributes
+
     @attr_tags = []
 
     @in_tt = 0
-    @tt_bit = RDoc::Markup::Attribute.bitmap_for :TT
+    @tt_bit = @attributes.bitmap_for :TT
+
+    @hard_break = ''
+    @from_path = '.'
+  end
+
+  ##
+  # Adds +document+ to the output
+
+  def accept_document document
+    document.parts.each do |item|
+      case item
+      when RDoc::Markup::Document then # HACK
+        accept_document item
+      else
+        item.accept self
+      end
+    end
+  end
+
+  ##
+  # Adds a regexp handling for links of the form rdoc-...:
+
+  def add_regexp_handling_RDOCLINK
+    @markup.add_regexp_handling(/rdoc-[a-z]+:[^\s\]]+/, :RDOCLINK)
+  end
+
+  ##
+  # Adds a regexp handling for links of the form {<text>}[<url>] and
+  # <word>[<url>]
+
+  def add_regexp_handling_TIDYLINK
+    @markup.add_regexp_handling(/(?:
+                                  \{.*?\} |    # multi-word label
+                                  \b[^\s{}]+? # single-word label
+                                 )
+
+                                 \[\S+?\]     # link target
+                                /x, :TIDYLINK)
   end
 
   ##
@@ -30,7 +103,7 @@ class RDoc::Markup::Formatter
   # tags for flexibility
 
   def add_tag(name, start, stop)
-    attr = RDoc::Markup::Attribute.bitmap_for name
+    attr = @attributes.bitmap_for name
     @attr_tags << InlineTag.new(attr, start, stop)
   end
 
@@ -44,7 +117,7 @@ class RDoc::Markup::Formatter
   ##
   # Marks up +content+
 
-  def convert(content)
+  def convert content
     @markup.convert content, self
   end
 
@@ -61,8 +134,8 @@ class RDoc::Markup::Formatter
       when RDoc::Markup::AttrChanger then
         off_tags res, item
         on_tags res, item
-      when RDoc::Markup::Special then
-        res << convert_special(item)
+      when RDoc::Markup::RegexpHandling then
+        res << convert_regexp_handling(item)
       else
         raise "Unknown flow element: #{item.inspect}"
       end
@@ -72,23 +145,29 @@ class RDoc::Markup::Formatter
   end
 
   ##
-  # Converts added specials.  See RDoc::Markup#add_special
+  # Converts added regexp handlings. See RDoc::Markup#add_regexp_handling
+
+  def convert_regexp_handling target
+    return target.text if in_tt?
 
-  def convert_special(special)
     handled = false
 
-    RDoc::Markup::Attribute.each_name_of special.type do |name|
-      method_name = "handle_special_#{name}"
+    @attributes.each_name_of target.type do |name|
+      method_name = "handle_regexp_#{name}"
 
       if respond_to? method_name then
-        special.text = send method_name, special
+        target.text = public_send method_name, target
         handled = true
       end
     end
 
-    raise "Unhandled special: #{special}" unless handled
+    unless handled then
+      target_name = @attributes.as_string target.type
+
+      raise RDoc::Error, "Unhandled regexp handling #{target_name}: #{target}"
+    end
 
-    special.text
+    target.text
   end
 
   ##
@@ -98,6 +177,17 @@ class RDoc::Markup::Formatter
     string
   end
 
+  ##
+  # Use ignore in your subclass to ignore the content of a node.
+  #
+  #   ##
+  #   # We don't support raw nodes in ToNoRaw
+  #
+  #   alias accept_raw ignore
+
+  def ignore *node
+  end
+
   ##
   # Are we currently inside tt tags?
 
@@ -135,6 +225,36 @@ class RDoc::Markup::Formatter
     end
   end
 
+  ##
+  # Extracts and a scheme, url and an anchor id from +url+ and returns them.
+
+  def parse_url url
+    case url
+    when /^rdoc-label:([^:]*)(?::(.*))?/ then
+      scheme = 'link'
+      path   = "##{$1}"
+      id     = " id=\"#{$2}\"" if $2
+    when /([A-Za-z]+):(.*)/ then
+      scheme = $1.downcase
+      path   = $2
+    when /^#/ then
+    else
+      scheme = 'http'
+      path   = url
+      url    = url
+    end
+
+    if scheme == 'link' then
+      url = if path[0, 1] == '#' then # is this meaningful?
+              path
+            else
+              self.class.gen_relative_url @from_path, path
+            end
+    end
+
+    [scheme, url, id]
+  end
+
   ##
   # Is +tag+ a tt tag?
 
@@ -144,10 +264,3 @@ class RDoc::Markup::Formatter
 
 end
 
-class RDoc::Markup
-  autoload :ToAnsi,         'rdoc/markup/to_ansi'
-  autoload :ToBs,           'rdoc/markup/to_bs'
-  autoload :ToHtml,         'rdoc/markup/to_html'
-  autoload :ToHtmlCrossref, 'rdoc/markup/to_html_crossref'
-  autoload :ToRdoc,         'rdoc/markup/to_rdoc'
-end

data/lib/rdoc/markup/hard_break.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+##
+# A hard-break in the middle of a paragraph.
+
+class RDoc::Markup::HardBreak
+
+  @instance = new
+
+  ##
+  # RDoc::Markup::HardBreak is a singleton
+
+  def self.new
+    @instance
+  end
+
+  ##
+  # Calls #accept_hard_break on +visitor+
+
+  def accept visitor
+    visitor.accept_hard_break self
+  end
+
+  def == other # :nodoc:
+    self.class === other
+  end
+
+  def pretty_print q # :nodoc:
+    q.text "[break]"
+  end
+
+end
+

data/lib/rdoc/markup/heading.rb

@@ -1,15 +1,74 @@
+# frozen_string_literal: true
 ##
 # A heading with a level (1-6) and text
 
-class RDoc::Markup::Heading < Struct.new :level, :text
+RDoc::Markup::Heading =
+  Struct.new :level, :text do
+
+  @to_html = nil
+  @to_label = nil
+
+  ##
+  # A singleton RDoc::Markup::ToLabel formatter for headings.
+
+  def self.to_label
+    @to_label ||= RDoc::Markup::ToLabel.new
+  end
+
+  ##
+  # A singleton plain HTML formatter for headings.  Used for creating labels
+  # for the Table of Contents
+
+  def self.to_html
+    return @to_html if @to_html
+
+    markup = RDoc::Markup.new
+    markup.add_regexp_handling RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
+
+    @to_html = RDoc::Markup::ToHtml.new nil
+
+    def @to_html.handle_regexp_CROSSREF target
+      target.text.sub(/^\\/, '')
+    end
+
+    @to_html
+  end
 
   ##
-  # Calls #accept_heading on +wisitor+
+  # Calls #accept_heading on +visitor+
 
   def accept visitor
     visitor.accept_heading self
   end
 
+  ##
+  # An HTML-safe anchor reference for this header.
+
+  def aref
+    "label-#{self.class.to_label.convert text.dup}"
+  end
+
+  ##
+  # Creates a fully-qualified label which will include the label from
+  # +context+.  This helps keep ids unique in HTML.
+
+  def label context = nil
+    label = aref
+
+    label = [context.aref, label].compact.join '-' if
+      context and context.respond_to? :aref
+
+    label
+  end
+
+  ##
+  # HTML markup of the text of this label without the surrounding header
+  # element.
+
+  def plain_html
+    self.class.to_html.to_html(text.dup)
+  end
+
   def pretty_print q # :nodoc:
     q.group 2, "[head: #{level} ", ']' do
       q.pp text

data/lib/rdoc/markup/include.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+##
+# A file included at generation time.  Objects of this class are created by
+# RDoc::RD for an extension-less include.
+#
+# This implementation in incomplete.
+
+class RDoc::Markup::Include
+
+  ##
+  # The filename to be included, without extension
+
+  attr_reader :file
+
+  ##
+  # Directories to search for #file
+
+  attr_reader :include_path
+
+  ##
+  # Creates a new include that will import +file+ from +include_path+
+
+  def initialize file, include_path
+    @file = file
+    @include_path = include_path
+  end
+
+  def == other # :nodoc:
+    self.class === other and
+      @file == other.file and @include_path == other.include_path
+  end
+
+  def pretty_print q # :nodoc:
+    q.group 2, '[incl ', ']' do
+      q.text file
+      q.breakable
+      q.text 'from '
+      q.pp include_path
+    end
+  end
+
+end
+

data/lib/rdoc/markup/indented_paragraph.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+##
+# An Indented Paragraph of text
+
+class RDoc::Markup::IndentedParagraph < RDoc::Markup::Raw
+
+  ##
+  # The indent in number of spaces
+
+  attr_reader :indent
+
+  ##
+  # Creates a new IndentedParagraph containing +parts+ indented with +indent+
+  # spaces
+
+  def initialize indent, *parts
+    @indent = indent
+
+    super(*parts)
+  end
+
+  def == other # :nodoc:
+    super and indent == other.indent
+  end
+
+  ##
+  # Calls #accept_indented_paragraph on +visitor+
+
+  def accept visitor
+    visitor.accept_indented_paragraph self
+  end
+
+  ##
+  # Joins the raw paragraph text and converts inline HardBreaks to the
+  # +hard_break+ text followed by the indent.
+
+  def text hard_break = nil
+    @parts.map do |part|
+      if RDoc::Markup::HardBreak === part then
+        '%1$s%3$*2$s' % [hard_break, @indent, ' '] if hard_break
+      else
+        part
+      end
+    end.join
+  end
+
+end
+

data/lib/rdoc/markup/list.rb

@@ -1,5 +1,25 @@
+# frozen_string_literal: true
 ##
-# A List of ListItems
+# A List is a homogeneous set of ListItems.
+#
+# The supported list types include:
+#
+# :BULLET::
+#   An unordered list
+# :LABEL::
+#   An unordered definition list, but using an alternate RDoc::Markup syntax
+# :LALPHA::
+#   An ordered list using increasing lowercase English letters
+# :NOTE::
+#   An unordered definition list
+# :NUMBER::
+#   An ordered list using increasing Arabic numerals
+# :UALPHA::
+#   An ordered list using increasing uppercase English letters
+#
+# Definition lists behave like HTML definition lists.  Each list item can
+# describe multiple terms.  See RDoc::Markup::ListItem for how labels and
+# definition are stored as list items.
 
 class RDoc::Markup::List
 
@@ -14,12 +34,13 @@ class RDoc::Markup::List
   attr_reader :items
 
   ##
-  # Creates a new list of +type+ with +items+
+  # Creates a new list of +type+ with +items+.  Valid list types are:
+  # +:BULLET+, +:LABEL+, +:LALPHA+, +:NOTE+, +:NUMBER+, +:UALPHA+
 
   def initialize type = nil, *items
     @type = type
     @items = []
-    @items.push(*items)
+    @items.concat items
   end
 
   ##
@@ -74,7 +95,7 @@ class RDoc::Markup::List
   # Appends +items+ to the list
 
   def push *items
-    @items.push(*items)
+    @items.concat items
   end
 
 end

data/lib/rdoc/markup/list_item.rb

@@ -1,5 +1,13 @@
+# frozen_string_literal: true
 ##
 # An item within a List that contains paragraphs, headings, etc.
+#
+# For BULLET, NUMBER, LALPHA and UALPHA lists, the label will always be nil.
+# For NOTE and LABEL lists, the list label may contain:
+#
+# * a single String for a single label
+# * an Array of Strings for a list item with multiple terms
+# * nil for an extra description attached to a previously labeled list item
 
 class RDoc::Markup::ListItem
 
@@ -19,7 +27,7 @@ class RDoc::Markup::ListItem
   def initialize label = nil, *parts
     @label = label
     @parts = []
-    @parts.push(*parts)
+    @parts.concat parts
   end
 
   ##
@@ -64,8 +72,14 @@ class RDoc::Markup::ListItem
 
   def pretty_print q # :nodoc:
     q.group 2, '[item: ', ']' do
-      if @label then
-        q.text @label
+      case @label
+      when Array then
+        q.pp @label
+        q.text ';'
+        q.breakable
+      when String then
+        q.pp @label
+        q.text ';'
         q.breakable
       end
 
@@ -79,7 +93,7 @@ class RDoc::Markup::ListItem
   # Adds +parts+ to the ListItem
 
   def push *parts
-    @parts.push(*parts)
+    @parts.concat parts
   end
 
 end

data/lib/rdoc/markup/paragraph.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 ##
 # A Paragraph of text
 
@@ -10,5 +11,19 @@ class RDoc::Markup::Paragraph < RDoc::Markup::Raw
     visitor.accept_paragraph self
   end
 
+  ##
+  # Joins the raw paragraph text and converts inline HardBreaks to the
+  # +hard_break+ text.
+
+  def text hard_break = ''
+    @parts.map do |part|
+      if RDoc::Markup::HardBreak === part then
+        hard_break
+      else
+        part
+      end
+    end.join
+  end
+
 end