rdoc 6.13.0 → 6.17.0

data/lib/rdoc/markup/raw.rb

@@ -20,29 +20,29 @@ class RDoc::Markup::Raw
   ##
   # Appends +text+
 
-  def << text
+  def <<(text)
     @parts << text
   end
 
-  def == other # :nodoc:
+  def ==(other) # :nodoc:
     self.class == other.class and @parts == other.parts
   end
 
   ##
   # Calls #accept_raw+ on +visitor+
 
-  def accept visitor
+  def accept(visitor)
     visitor.accept_raw self
   end
 
   ##
   # Appends +other+'s parts
 
-  def merge other
+  def merge(other)
     @parts.concat other.parts
   end
 
-  def pretty_print q # :nodoc:
+  def pretty_print(q) # :nodoc:
     self.class.name =~ /.*::(\w{1,4})/i
 
     q.group 2, "[#{$1.downcase}: ", ']' do

data/lib/rdoc/markup/rule.rb

@@ -7,11 +7,11 @@ class RDoc::Markup::Rule < Struct.new :weight
   ##
   # Calls #accept_rule on +visitor+
 
-  def accept visitor
+  def accept(visitor)
     visitor.accept_rule self
   end
 
-  def pretty_print q # :nodoc:
+  def pretty_print(q) # :nodoc:
     q.group 2, '[rule:', ']' do
       q.pp weight
     end

data/lib/rdoc/markup/table.rb

@@ -13,23 +13,23 @@ class RDoc::Markup::Table
   attr_accessor :body
 
   # Creates new instance
-  def initialize header, align, body
+  def initialize(header, align, body)
     @header, @align, @body = header, align, body
   end
 
   # :stopdoc:
-  def == other
+  def ==(other)
     self.class == other.class and
       @header == other.header and
       @align == other.align and
       @body == other.body
   end
 
-  def accept visitor
+  def accept(visitor)
     visitor.accept_table @header, @body, @align
   end
 
-  def pretty_print q
+  def pretty_print(q)
     q.group 2, '[Table: ', ']' do
       q.group 2, '[Head: ', ']' do
         q.seplist @header.zip(@align) do |text, align|

data/lib/rdoc/markup/to_ansi.rb

@@ -7,7 +7,7 @@ class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
   ##
   # Creates a new ToAnsi visitor that is ready to output vibrant ANSI color!
 
-  def initialize markup = nil
+  def initialize(markup = nil)
     super
 
     @headings.clear
@@ -28,7 +28,7 @@ class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
   ##
   # Overrides indent width to ensure output lines up correctly.
 
-  def accept_list_item_end list_item
+  def accept_list_item_end(list_item)
     width = case @list_type.last
             when :BULLET then
               2
@@ -52,7 +52,7 @@ class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
   ##
   # Adds coloring to note and label list items
 
-  def accept_list_item_start list_item
+  def accept_list_item_start(list_item)
     bullet = case @list_type.last
              when :BULLET then
                '*'
@@ -81,6 +81,10 @@ class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
     end
   end
 
+  def calculate_text_width(text)
+    text.gsub(/\e\[[\d;]*m/, '').size
+  end
+
   ##
   # Starts accepting with a reset screen
 

data/lib/rdoc/markup/to_bs.rb

@@ -10,7 +10,7 @@ class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
   ##
   # Returns a new ToBs that is ready for hot backspace action!
 
-  def initialize markup = nil
+  def initialize(markup = nil)
     super
 
     @in_b  = false
@@ -30,7 +30,7 @@ class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
   ##
   # Makes heading text bold.
 
-  def accept_heading heading
+  def accept_heading(heading)
     use_prefix or @res << ' ' * @indent
     @res << @headings[heading.level][0]
     @in_b = true
@@ -43,7 +43,7 @@ class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
   ##
   # Prepares the visitor for consuming +list_item+
 
-  def accept_list_item_start list_item
+  def accept_list_item_start(list_item)
     type = @list_type.last
 
     case type
@@ -65,10 +65,14 @@ class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
     end
   end
 
+  def calculate_text_width(text)
+    text.gsub(/_\x08/, '').gsub(/\x08./, '').size
+  end
+
   ##
   # Turns on or off regexp handling for +convert_string+
 
-  def annotate tag
+  def annotate(tag)
     case tag
     when '+b' then @in_b = true
     when '-b' then @in_b = false
@@ -81,14 +85,14 @@ class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
   ##
   # Calls convert_string on the result of convert_regexp_handling
 
-  def convert_regexp_handling target
+  def convert_regexp_handling(target)
     convert_string super
   end
 
   ##
   # Adds bold or underline mixed with backspaces
 
-  def convert_string string
+  def convert_string(string)
     return string unless @in_b or @in_em
     chars = if @in_b then
               string.chars.map do |char| "#{char}\b#{char}" end

data/lib/rdoc/markup/to_html.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
-require 'cgi/util'
+require 'cgi/escape'
+require 'cgi/util' unless defined?(CGI::EscapeExt)
 
 ##
 # Outputs RDoc markup as HTML.
@@ -42,7 +43,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   ##
   # Creates a new formatter that will output HTML
 
-  def initialize options, markup = nil
+  def initialize(options, markup = nil)
     super
 
     @code_object = nil
@@ -82,7 +83,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     add_regexp_handling_TIDYLINK
   end
 
-  def handle_RDOCLINK url # :nodoc:
+  def handle_RDOCLINK(url) # :nodoc:
     case url
     when /^rdoc-ref:/
       CGI.escapeHTML($')
@@ -98,7 +99,10 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
       gen_url CGI.escapeHTML(url), CGI.escapeHTML(text)
     when /^rdoc-image:/
-      url, alt = $'.split(":", 2) # Split the string after "rdoc-image:" into url and alt
+      # Split the string after "rdoc-image:" into url and alt.
+      #   "path/to/image.jpg:alt text" => ["path/to/image.jpg", "alt text"]
+      #   "http://example.com/path/to/image.jpg:alt text" => ["http://example.com/path/to/image.jpg", "alt text"]
+      url, alt = $'.split(/:(?!\/)/, 2)
       if alt && !alt.empty?
         %[<img src="#{CGI.escapeHTML(url)}" alt="#{CGI.escapeHTML(alt)}">]
       else
@@ -112,7 +116,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   ##
   # +target+ is a <code><br></code>
 
-  def handle_regexp_HARD_BREAK target
+  def handle_regexp_HARD_BREAK(target)
     '<br>'
   end
 
@@ -143,7 +147,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   # For the +rdoc-label+ scheme the footnote and label prefixes are stripped
   # when creating a link.  All other contents will be linked verbatim.
 
-  def handle_regexp_RDOCLINK target
+  def handle_regexp_RDOCLINK(target)
     handle_RDOCLINK target.text
   end
 
@@ -154,19 +158,16 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   def handle_regexp_TIDYLINK(target)
     text = target.text
 
-    return text unless
-      text =~ /^\{(.*)\}\[(.*?)\]$/ or text =~ /^(\S+)\[(.*?)\]$/
-
-    label = $1
-    url   = CGI.escapeHTML($2)
+    if tidy_link_capturing?
+      return finish_tidy_link(text)
+    end
 
-    if /^rdoc-image:/ =~ label
-      label = handle_RDOCLINK(label)
-    else
-      label = CGI.escapeHTML(label)
+    if text.start_with?('{') && !text.include?('}')
+      start_tidy_link text
+      return ''
     end
 
-    gen_url url, label
+    convert_complete_tidy_link(text)
   end
 
   # :section: Visitor
@@ -192,7 +193,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   ##
   # Adds +block_quote+ to the output
 
-  def accept_block_quote block_quote
+  def accept_block_quote(block_quote)
     @res << "\n<blockquote>"
 
     block_quote.parts.each do |part|
@@ -205,7 +206,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   ##
   # Adds +paragraph+ to the output
 
-  def accept_paragraph paragraph
+  def accept_paragraph(paragraph)
     @res << "\n<p>"
     text = paragraph.text @hard_break
     text = text.gsub(/(#{SPACE_SEPARATED_LETTER_CLASS})?\K\r?\n(?=(?(1)(#{SPACE_SEPARATED_LETTER_CLASS})?))/o) {
@@ -218,7 +219,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   ##
   # Adds +verbatim+ to the output
 
-  def accept_verbatim verbatim
+  def accept_verbatim(verbatim)
     text = verbatim.text.rstrip
 
     klass = nil
@@ -248,7 +249,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   ##
   # Adds +rule+ to the output
 
-  def accept_rule rule
+  def accept_rule(rule)
     @res << "<hr>\n"
   end
 
@@ -301,7 +302,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   # Adds +heading+ to the output.  The headings greater than 6 are trimmed to
   # level 6.
 
-  def accept_heading heading
+  def accept_heading(heading)
     level = [6, heading.level].min
 
     label = heading.label @code_object
@@ -311,25 +312,27 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
             else
               "\n<h#{level}>"
             end
-    @res << to_html(heading.text)
-    unless @options.pipe then
-      @res << "<span><a href=\"##{label}\">&para;</a>"
-      @res << " <a href=\"#top\">&uarr;</a></span>"
+
+    if @options.pipe
+      @res << to_html(heading.text)
+    else
+      @res << "<a href=\"##{label}\">#{to_html(heading.text)}</a>"
     end
+
     @res << "</h#{level}>\n"
   end
 
   ##
   # Adds +raw+ to the output
 
-  def accept_raw raw
+  def accept_raw(raw)
     @res << raw.parts.join("\n")
   end
 
   ##
   # Adds +table+ to the output
 
-  def accept_table header, body, aligns
+  def accept_table(header, body, aligns)
     @res << "\n<table role=\"table\">\n<thead>\n<tr>\n"
     header.zip(aligns) do |text, align|
       @res << '<th'
@@ -362,7 +365,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   # Generate a link to +url+ with content +text+.  Handles the special cases
   # for img: and link: described under handle_regexp_HYPERLINK
 
-  def gen_url url, text
+  def gen_url(url, text)
     scheme, url, id = parse_url url
 
     if %w[http https link].include?(scheme) and
@@ -436,7 +439,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   ##
   # Returns true if text is valid ruby syntax
 
-  def parseable? text
+  def parseable?(text)
     verbose, $VERBOSE = $VERBOSE, nil
     catch(:valid) do
       eval("BEGIN { throw :valid, true }\n#{text}")
@@ -450,8 +453,157 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   ##
   # Converts +item+ to HTML using RDoc::Text#to_html
 
-  def to_html item
+  def to_html(item)
     super convert_flow @am.flow item
   end
 
+  private
+
+  def convert_flow(flow_items)
+    res = []
+
+    flow_items.each do |item|
+      case item
+      when String
+        append_flow_fragment res, convert_string(item)
+      when RDoc::Markup::AttrChanger
+        off_tags res, item
+        on_tags  res, item
+      when RDoc::Markup::RegexpHandling
+        append_flow_fragment res, convert_regexp_handling(item)
+      else
+        raise "Unknown flow element: #{item.inspect}"
+      end
+    end
+
+    res.join
+  end
+
+  def append_flow_fragment(res, fragment)
+    return if fragment.nil? || fragment.empty?
+
+    emit_tidy_link_fragment(res, fragment)
+  end
+
+  def append_to_tidy_label(fragment)
+    @tidy_link_buffer << fragment
+  end
+
+  ##
+  # Matches an entire tidy link with a braced label "{label}[url]".
+  #
+  # Capture 1: label contents.
+  # Capture 2: URL text.
+  # Capture 3: trailing content.
+  TIDY_LINK_WITH_BRACES = /\A\{(.*?)\}\[(.*?)\](.*)\z/
+
+  ##
+  # Matches the tail of a braced tidy link when the opening brace was
+  # consumed earlier while accumulating the label text.
+  #
+  # Capture 1: remaining label content.
+  # Capture 2: URL text.
+  # Capture 3: trailing content.
+  TIDY_LINK_WITH_BRACES_TAIL = /\A(.*?)\}\[(.*?)\](.*)\z/
+
+  ##
+  # Matches a tidy link with a single-word label "label[url]".
+  #
+  # Capture 1: the single-word label (no whitespace).
+  # Capture 2: URL text between the brackets.
+  TIDY_LINK_SINGLE_WORD = /\A(\S+)\[(.*?)\](.*)\z/
+
+  def convert_complete_tidy_link(text)
+    return text unless
+      text =~ TIDY_LINK_WITH_BRACES or text =~ TIDY_LINK_SINGLE_WORD
+
+    label = $1
+    url   = CGI.escapeHTML($2)
+
+    label_html = if /^rdoc-image:/ =~ label
+                   handle_RDOCLINK(label)
+                 else
+                   render_tidy_link_label(label)
+                 end
+
+    gen_url url, label_html
+  end
+
+  def emit_tidy_link_fragment(res, fragment)
+    if tidy_link_capturing?
+      append_to_tidy_label fragment
+    else
+      res << fragment
+    end
+  end
+
+  def finish_tidy_link(text)
+    label_tail, url, trailing = extract_tidy_link_parts(text)
+    append_to_tidy_label CGI.escapeHTML(label_tail) unless label_tail.empty?
+
+    return '' unless url
+
+    label_html = @tidy_link_buffer
+    @tidy_link_buffer = nil
+    link = gen_url(url, label_html)
+
+    return link if trailing.empty?
+
+    link + CGI.escapeHTML(trailing)
+  end
+
+  def extract_tidy_link_parts(text)
+    if text =~ TIDY_LINK_WITH_BRACES
+      [$1, CGI.escapeHTML($2), $3]
+    elsif text =~ TIDY_LINK_WITH_BRACES_TAIL
+      [$1, CGI.escapeHTML($2), $3]
+    elsif text =~ TIDY_LINK_SINGLE_WORD
+      [$1, CGI.escapeHTML($2), $3]
+    else
+      [text, nil, '']
+    end
+  end
+
+  def on_tags(res, item)
+    each_attr_tag(item.turn_on) do |tag|
+      emit_tidy_link_fragment(res, annotate(tag.on))
+      @in_tt += 1 if tt? tag
+    end
+  end
+
+  def off_tags(res, item)
+    each_attr_tag(item.turn_off, true) do |tag|
+      emit_tidy_link_fragment(res, annotate(tag.off))
+      @in_tt -= 1 if tt? tag
+    end
+  end
+
+  def start_tidy_link(text)
+    @tidy_link_buffer = String.new
+    append_to_tidy_label CGI.escapeHTML(text.delete_prefix('{'))
+  end
+
+  def tidy_link_capturing?
+    !!@tidy_link_buffer
+  end
+
+  def render_tidy_link_label(label)
+    RDoc::Markup::LinkLabelToHtml.render(label, @options, @from_path)
+  end
+end
+
+##
+# Formatter dedicated to rendering tidy link labels without mutating the
+# calling formatter's state.
+
+class RDoc::Markup::LinkLabelToHtml < RDoc::Markup::ToHtml
+  def self.render(label, options, from_path)
+    new(options, from_path).to_html(label)
+  end
+
+  def initialize(options, from_path = nil)
+    super(options)
+
+    self.from_path = from_path if from_path
+  end
 end

data/lib/rdoc/markup/to_html_crossref.rb

@@ -58,7 +58,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # Creates a link to the reference +name+ if the name exists.  If +text+ is
   # given it is used as the link text, otherwise +name+ is used.
 
-  def cross_reference name, text = nil, code = true, rdoc_ref: false
+  def cross_reference(name, text = nil, code = true, rdoc_ref: false)
     lookup = name
 
     name = name[1..-1] unless @show_hash if name[0, 1] == '#'
@@ -101,7 +101,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # Handles <tt>rdoc-ref:</tt> scheme links and allows RDoc::Markup::ToHtml to
   # handle other schemes.
 
-  def handle_regexp_HYPERLINK target
+  def handle_regexp_HYPERLINK(target)
     url = target.text
 
     case url
@@ -120,7 +120,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # All other contents are handled by
   # {the superclass}[rdoc-ref:RDoc::Markup::ToHtml#handle_regexp_RDOCLINK]
 
-  def handle_regexp_RDOCLINK target
+  def handle_regexp_RDOCLINK(target)
     url = target.text
 
     case url
@@ -135,7 +135,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # Generates links for <tt>rdoc-ref:</tt> scheme URLs and allows
   # RDoc::Markup::ToHtml to handle other schemes.
 
-  def gen_url url, text
+  def gen_url(url, text)
     if url =~ /\Ardoc-ref:/
       name = $'
       cross_reference name, text, name == text, rdoc_ref: true
@@ -147,7 +147,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   ##
   # Creates an HTML link to +name+ with the given +text+.
 
-  def link name, text, code = true, rdoc_ref: false
+  def link(name, text, code = true, rdoc_ref: false)
     if !(name.end_with?('+@', '-@')) and name =~ /(.*[^#:])?@/
       name = $1
       label = $'
@@ -184,38 +184,35 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
     end
   end
 
-  def convert_flow(flow)
+  def convert_flow(flow_items, &block)
     res = []
 
     i = 0
-    while i < flow.size
-      item = flow[i]
-      i += 1
+    while i < flow_items.size
+      item = flow_items[i]
+
       case item
-      when RDoc::Markup::AttrChanger then
-        # Make "+Class#method+" a cross reference
-        if tt_tag?(item.turn_on) and
-          String === (str = flow[i]) and
-          RDoc::Markup::AttrChanger === flow[i+1] and
-          tt_tag?(flow[i+1].turn_off, true) and
-          (@options.hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP).match?(str) and
-          (text = cross_reference str) != str
-        then
-          text = yield text, res if defined?(yield)
-          res << text
-          i += 2
+      when RDoc::Markup::AttrChanger
+        if !tidy_link_capturing? && (text = convert_tt_crossref(flow_items, i))
+          text = block.call(text, res) if block
+          append_flow_fragment res, text
+          i += 3
           next
         end
+
         off_tags res, item
-        on_tags res, item
-      when String then
+        on_tags  res, item
+        i += 1
+      when String
         text = convert_string(item)
-        text = yield text, res if defined?(yield)
-        res << text
-      when RDoc::Markup::RegexpHandling then
+        text = block.call(text, res) if block
+        append_flow_fragment res, text
+        i += 1
+      when RDoc::Markup::RegexpHandling
         text = convert_regexp_handling(item)
-        text = yield text, res if defined?(yield)
-        res << text
+        text = block.call(text, res) if block
+        append_flow_fragment res, text
+        i += 1
       else
         raise "Unknown flow element: #{item.inspect}"
       end
@@ -223,4 +220,37 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
     res.join('')
   end
+
+  private
+
+  ##
+  # Detects <tt>...</tt> spans that contain a single cross-reference candidate.
+  # When the candidate occupies the whole span (aside from trailing
+  # punctuation), the tt markup is replaced by the resolved cross-reference.
+
+  def convert_tt_crossref(flow_items, index)
+    opener = flow_items[index]
+    return unless tt_tag?(opener.turn_on)
+
+    string = flow_items[index + 1]
+    closer = flow_items[index + 2]
+
+    return unless String === string
+    return unless RDoc::Markup::AttrChanger === closer
+    return unless tt_tag?(closer.turn_off, true)
+
+    crossref_regexp = @options.hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
+    match = crossref_regexp.match(string)
+    return unless match
+    return unless match.begin(1).zero?
+
+    trailing = match.post_match
+    # Only convert when the remainder is punctuation/whitespace so other tt text stays literal.
+    return unless trailing.match?(/\A[[:punct:]\s]*\z/)
+
+    text = cross_reference(string)
+    return if text == string
+
+    text
+  end
 end