rdoc 3.1 → 6.3.3

data/lib/rdoc/markup/to_html_crossref.rb

@@ -1,92 +1,17 @@
-require 'rdoc/markup/to_html'
-
+# frozen_string_literal: true
 ##
-# Subclass of the RDoc::Markup::ToHtml class that supports looking up words
-# from a context.  Those that are found will be hyperlinked.
+# Subclass of the RDoc::Markup::ToHtml class that supports looking up method
+# names, classes, etc to create links.  RDoc::CrossReference is used to
+# generate those links based on the current context.
 
 class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
-  ##
-  # 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 method references.
-  #
-  # See CLASS_REGEXP_STR
-
-  METHOD_REGEXP_STR = '([a-z]\w*[!?=]?)(?:\([\w.+*/=<>-]*\))?'
-
-  ##
-  # Regular expressions matching text that should potentially have
-  # cross-reference links generated are passed to add_special.  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 = /(
-                      # A::B::C.meth
-                      #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
-
-                      # Stand-alone method (preceeded by a #)
-                      | \\?\##{METHOD_REGEXP_STR}
-
-                      # Stand-alone method (preceeded by ::)
-                      | ::#{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-referece is a space, sentence
-                      # punctuation, tag start character, or attribute
-                      # marker.
-                      | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;<\000]|\z)
-
-                      # 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<]
-                      )/x
-
-  ##
-  # Version of CROSSREF_REGEXP used when <tt>--hyperlink-all</tt> is specified.
-
-  ALL_CROSSREF_REGEXP = /(
-                      # A::B::C.meth
-                      #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
-
-                      # Stand-alone method
-                      | \\?#{METHOD_REGEXP_STR}
-
-                      # A::B::C
-                      | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;<\000]|\z)
-
-                      # Things that look like filenames
-                      | (?:\.\.\/)*[-\/\w]+[_\/\.][-\w\/\.]+
-
-                      # Things that have markup suppressed
-                      | \\[^\s<]
-                      )/x
+  # :stopdoc:
+  ALL_CROSSREF_REGEXP = RDoc::CrossReference::ALL_CROSSREF_REGEXP
+  CLASS_REGEXP_STR    = RDoc::CrossReference::CLASS_REGEXP_STR
+  CROSSREF_REGEXP     = RDoc::CrossReference::CROSSREF_REGEXP
+  METHOD_REGEXP_STR   = RDoc::CrossReference::METHOD_REGEXP_STR
+  # :startdoc:
 
   ##
   # RDoc::CodeObject for generating references
@@ -102,33 +27,62 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # Creates a new crossref resolver that generates links relative to +context+
   # which lives at +from_path+ in the generated files.  '#' characters on
   # references are removed unless +show_hash+ is true.  Only method names
-  # preceded by '#' or '::' are hyperlinked, unless +hyperlink_all+ is true.
+  # preceded by '#' or '::' are linked, unless +hyperlink_all+ is true.
 
-  def initialize(from_path, context, show_hash, hyperlink_all = false)
+  def initialize(options, from_path, context, markup = nil)
     raise ArgumentError, 'from_path cannot be nil' if from_path.nil?
-    super()
 
-    crossref_re = hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
+    super options, markup
+
+    @context       = context
+    @from_path     = from_path
+    @hyperlink_all = @options.hyperlink_all
+    @show_hash     = @options.show_hash
+
+    @cross_reference = RDoc::CrossReference.new @context
+  end
+
+  def init_link_notation_regexp_handlings
+    add_regexp_handling_RDOCLINK
+
+    # The crossref must be linked before tidylink because Klass.method[:sym]
+    # will be processed as a tidylink first and will be broken.
+    crossref_re = @options.hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
+    @markup.add_regexp_handling crossref_re, :CROSSREF
+
+    add_regexp_handling_TIDYLINK
+  end
+
+  ##
+  # 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
+    lookup = name
 
-    @markup.add_special crossref_re, :CROSSREF
+    name = name[1..-1] unless @show_hash if name[0, 1] == '#'
 
-    @from_path = from_path
-    @context = context
-    @show_hash = show_hash
-    @hyperlink_all = hyperlink_all
+    if !(name.end_with?('+@', '-@')) and name =~ /(.*[^#:])@/
+      text ||= "#{CGI.unescape $'} at <code>#{$1}</code>"
+      code = false
+    else
+      text ||= name
+    end
 
-    @seen = {}
+    link lookup, text, code
   end
 
   ##
   # We're invoked when any text matches the CROSSREF pattern.  If we find the
-  # corresponding reference, generate a hyperlink.  If the name we're looking
-  # for contains no punctuation, we look for it up the module/class chain.
-  # For example, ToHtml is found, even without the <tt>RDoc::Markup::</tt>
-  # prefix, because we look for it in module Markup first.
+  # corresponding reference, generate a link.  If the name we're looking for
+  # contains no punctuation, we look for it up the module/class chain.  For
+  # example, ToHtml is found, even without the <tt>RDoc::Markup::</tt> prefix,
+  # because we look for it in module Markup first.
+
+  def handle_regexp_CROSSREF(target)
+    name = target.text
 
-  def handle_special_CROSSREF(special)
-    name = special.text
+    return name if name =~ /@[\w-]+\.[\w-]/ # labels that look like emails
 
     unless @hyperlink_all then
       # This ensures that words entirely consisting of lowercase letters will
@@ -137,66 +91,85 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
       return name if name =~ /\A[a-z]*\z/
     end
 
-    return @seen[name] if @seen.include? name
+    cross_reference name
+  end
 
-    lookup = name
+  ##
+  # Handles <tt>rdoc-ref:</tt> scheme links and allows RDoc::Markup::ToHtml to
+  # handle other schemes.
 
-    name = name[1..-1] unless @show_hash if name[0, 1] == '#'
+  def handle_regexp_HYPERLINK target
+    return cross_reference $' if target.text =~ /\Ardoc-ref:/
+
+    super
+  end
+
+  ##
+  # +target+ is an rdoc-schemed link that will be converted into a hyperlink.
+  # For the rdoc-ref scheme the cross-reference will be looked up and the
+  # given name will be used.
+  #
+  # All other contents are handled by
+  # {the superclass}[rdoc-ref:RDoc::Markup::ToHtml#handle_regexp_RDOCLINK]
+
+  def handle_regexp_RDOCLINK target
+    url = target.text
 
-    # Find class, module, or method in class or module.
-    #
-    # Do not, however, use an if/elsif/else chain to do so.  Instead, test
-    # each possible pattern until one matches.  The reason for this is that a
-    # string like "YAML.txt" could be the txt() class method of class YAML (in
-    # which case it would match the first pattern, which splits the string
-    # into container and method components and looks up both) or a filename
-    # (in which case it would match the last pattern, which just checks
-    # whether the string as a whole is a known symbol).
-
-    if /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/ =~ lookup then
-      type = $2
-      type = '' if type == '.'  # will find either #method or ::method
-      method = "#{type}#{$3}"
-      container = @context.find_symbol_module($1)
-    elsif /^([.#]|::)#{METHOD_REGEXP_STR}/ =~ lookup then
-      type = $1
-      type = '' if type == '.'
-      method = "#{type}#{$2}"
-      container = @context
+    case url
+    when /\Ardoc-ref:/ then
+      cross_reference $'
     else
-      container = nil
+      super
     end
+  end
+
+  ##
+  # Generates links for <tt>rdoc-ref:</tt> scheme URLs and allows
+  # RDoc::Markup::ToHtml to handle other schemes.
 
-    if container then
-      ref = container.find_local_symbol method
+  def gen_url url, text
+    return super unless url =~ /\Ardoc-ref:/
 
-      unless ref || RDoc::TopLevel === container then
-        ref = container.find_ancestor_local_symbol method
-      end
+    name = $'
+    cross_reference name, text, name == text
+  end
+
+  ##
+  # Creates an HTML link to +name+ with the given +text+.
+
+  def link name, text, code = true
+    if !(name.end_with?('+@', '-@')) and name =~ /(.*[^#:])@/
+      name = $1
+      label = $'
     end
 
-    ref = @context.find_symbol lookup unless ref
-    ref = nil if RDoc::Alias === ref # external alias: can't link to it
-
-    out = if lookup == '\\' then
-            lookup
-          elsif lookup =~ /^\\/ then
-            # we remove the \ only in front of what we know:
-            # other backslashes are treated later, only outside of <tt>
-            ref ? $' : lookup
-          elsif ref then
-            if ref.document_self then
-              "<a href=\"#{ref.as_href @from_path}\">#{name}</a>"
-            else
-              name
-            end
-          else
-            lookup
-          end
-
-    @seen[lookup] = out
-
-    out
+    ref = @cross_reference.resolve name, text
+
+    case ref
+    when String then
+      ref
+    else
+      path = ref.as_href @from_path
+
+      if code and RDoc::CodeObject === ref and !(RDoc::TopLevel === ref)
+        text = "<code>#{CGI.escapeHTML text}</code>"
+      end
+
+      if path =~ /#/ then
+        path << "-label-#{label}"
+      elsif ref.sections and
+            ref.sections.any? { |section| label == section.title } then
+        path << "##{label}"
+      else
+        if ref.respond_to?(:aref)
+          path << "##{ref.aref}-label-#{label}"
+        else
+          path << "#label-#{label}"
+        end
+      end if label
+
+      "<a href=\"#{path}\">#{text}</a>"
+    end
   end
 
 end

data/lib/rdoc/markup/to_html_snippet.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+##
+# Outputs RDoc markup as paragraphs with inline markup only.
+
+class RDoc::Markup::ToHtmlSnippet < RDoc::Markup::ToHtml
+
+  ##
+  # After this many characters the input will be cut off.
+
+  attr_reader :character_limit
+
+  ##
+  # The number of characters seen so far.
+
+  attr_reader :characters # :nodoc:
+
+  ##
+  # The attribute bitmask
+
+  attr_reader :mask
+
+  ##
+  # After this many paragraphs the input will be cut off.
+
+  attr_reader :paragraph_limit
+
+  ##
+  # Count of paragraphs found
+
+  attr_reader :paragraphs
+
+  ##
+  # Creates a new ToHtmlSnippet formatter that will cut off the input on the
+  # next word boundary after the given number of +characters+ or +paragraphs+
+  # of text have been encountered.
+
+  def initialize options, characters = 100, paragraphs = 3, markup = nil
+    super options, markup
+
+    @character_limit = characters
+    @paragraph_limit = paragraphs
+
+    @characters = 0
+    @mask       = 0
+    @paragraphs = 0
+
+    @markup.add_regexp_handling RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
+  end
+
+  ##
+  # Adds +heading+ to the output as a paragraph
+
+  def accept_heading heading
+    @res << "<p>#{to_html heading.text}\n"
+
+    add_paragraph
+  end
+
+  ##
+  # Raw sections are untrusted and ignored
+
+  alias accept_raw ignore
+
+  ##
+  # Rules are ignored
+
+  alias accept_rule ignore
+
+  def accept_paragraph paragraph
+    para = @in_list_entry.last || "<p>"
+
+    text = paragraph.text @hard_break
+
+    @res << "#{para}#{to_html text}\n"
+
+    add_paragraph
+  end
+
+  ##
+  # Finishes consumption of +list_item+
+
+  def accept_list_item_end list_item
+  end
+
+  ##
+  # Prepares the visitor for consuming +list_item+
+
+  def accept_list_item_start list_item
+    @res << list_item_start(list_item, @list.last)
+  end
+
+  ##
+  # Prepares the visitor for consuming +list+
+
+  def accept_list_start list
+    @list << list.type
+    @res << html_list_name(list.type, true)
+    @in_list_entry.push ''
+  end
+
+  ##
+  # Adds +verbatim+ to the output
+
+  def accept_verbatim verbatim
+    throw :done if @characters >= @character_limit
+    input = verbatim.text.rstrip
+
+    text = truncate input
+    text << ' ...' unless text == input
+
+    super RDoc::Markup::Verbatim.new text
+
+    add_paragraph
+  end
+
+  ##
+  # Prepares the visitor for HTML snippet generation
+
+  def start_accepting
+    super
+
+    @characters = 0
+  end
+
+  ##
+  # Removes escaping from the cross-references in +target+
+
+  def handle_regexp_CROSSREF target
+    target.text.sub(/\A\\/, '')
+  end
+
+  ##
+  # +target+ is a <code><br></code>
+
+  def handle_regexp_HARD_BREAK target
+    @characters -= 4
+    '<br>'
+  end
+
+  ##
+  # Lists are paragraphs, but notes and labels have a separator
+
+  def list_item_start list_item, list_type
+    throw :done if @characters >= @character_limit
+
+    case list_type
+    when :BULLET, :LALPHA, :NUMBER, :UALPHA then
+      "<p>"
+    when :LABEL, :NOTE then
+      labels = Array(list_item.label).map do |label|
+        to_html label
+      end.join ', '
+
+      labels << " &mdash; " unless labels.empty?
+
+      start = "<p>#{labels}"
+      @characters += 1 # try to include the label
+      start
+    else
+      raise RDoc::Error, "Invalid list type: #{list_type.inspect}"
+    end
+  end
+
+  ##
+  # Returns just the text of +link+, +url+ is only used to determine the link
+  # type.
+
+  def gen_url url, text
+    if url =~ /^rdoc-label:([^:]*)(?::(.*))?/ then
+      type = "link"
+    elsif url =~ /([A-Za-z]+):(.*)/ then
+      type = $1
+    else
+      type = "http"
+    end
+
+    if (type == "http" or type == "https" or type == "link") and
+       url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then
+      ''
+    else
+      text.sub(%r%^#{type}:/*%, '')
+    end
+  end
+
+  ##
+  # In snippets, there are no lists
+
+  def html_list_name list_type, open_tag
+    ''
+  end
+
+  ##
+  # Throws +:done+ when paragraph_limit paragraphs have been encountered
+
+  def add_paragraph
+    @paragraphs += 1
+
+    throw :done if @paragraphs >= @paragraph_limit
+  end
+
+  ##
+  # Marks up +content+
+
+  def convert content
+    catch :done do
+      return super
+    end
+
+    end_accepting
+  end
+
+  ##
+  # Converts flow items +flow+
+
+  def convert_flow flow
+    throw :done if @characters >= @character_limit
+
+    res = []
+    @mask = 0
+
+    flow.each do |item|
+      case item
+      when RDoc::Markup::AttrChanger then
+        off_tags res, item
+        on_tags  res, item
+      when String then
+        text = convert_string item
+        res << truncate(text)
+      when RDoc::Markup::RegexpHandling then
+        text = convert_regexp_handling item
+        res << truncate(text)
+      else
+        raise "Unknown flow element: #{item.inspect}"
+      end
+
+      if @characters >= @character_limit then
+        off_tags res, RDoc::Markup::AttrChanger.new(0, @mask)
+        break
+      end
+    end
+
+    res << ' ...' if @characters >= @character_limit
+
+    res.join
+  end
+
+  ##
+  # Maintains a bitmask to allow HTML elements to be closed properly.  See
+  # RDoc::Markup::Formatter.
+
+  def on_tags res, item
+    @mask ^= item.turn_on
+
+    super
+  end
+
+  ##
+  # Maintains a bitmask to allow HTML elements to be closed properly.  See
+  # RDoc::Markup::Formatter.
+
+  def off_tags res, item
+    @mask ^= item.turn_off
+
+    super
+  end
+
+  ##
+  # Truncates +text+ at the end of the first word after the character_limit.
+
+  def truncate text
+    length = text.length
+    characters = @characters
+    @characters += length
+
+    return text if @characters < @character_limit
+
+    remaining = @character_limit - characters
+
+    text =~ /\A(.{#{remaining},}?)(\s|$)/m # TODO word-break instead of \s?
+
+    $1
+  end
+
+end
+

data/lib/rdoc/markup/to_joined_paragraph.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+##
+# Joins the parts of an RDoc::Markup::Paragraph into a single String.
+#
+# This allows for easier maintenance and testing of Markdown support.
+#
+# This formatter only works on Paragraph instances.  Attempting to process
+# other markup syntax items will not work.
+
+class RDoc::Markup::ToJoinedParagraph < RDoc::Markup::Formatter
+
+  def initialize # :nodoc:
+    super nil
+  end
+
+  def start_accepting # :nodoc:
+  end
+
+  def end_accepting # :nodoc:
+  end
+
+  ##
+  # Converts the parts of +paragraph+ to a single entry.
+
+  def accept_paragraph paragraph
+    parts = paragraph.parts.chunk do |part|
+      String === part
+    end.map do |string, chunk|
+      string ? chunk.join.rstrip : chunk
+    end.flatten
+
+    paragraph.parts.replace parts
+  end
+
+  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_raw             ignore
+  alias accept_rule            ignore
+  alias accept_verbatim        ignore
+  alias accept_table           ignore
+
+end
+