rdoc 6.17.0 → 8.1.0

data/lib/rdoc/markup/to_html_snippet.rb

@@ -1,287 +1,292 @@
 # frozen_string_literal: true
-##
-# Outputs RDoc markup as paragraphs with inline markup only.
+module RDoc
+  class Markup
+    ##
+    # Outputs RDoc markup as paragraphs with inline markup only.
 
-class RDoc::Markup::ToHtmlSnippet < RDoc::Markup::ToHtml
+    class ToHtmlSnippet < Markup::ToHtml
 
-  ##
-  # After this many characters the input will be cut off.
+      ##
+      # After this many characters the input will be cut off.
 
-  attr_reader :character_limit
+      attr_reader :character_limit
 
-  ##
-  # The number of characters seen so far.
+      ##
+      # The number of characters seen so far.
 
-  attr_reader :characters # :nodoc:
+      attr_reader :characters # :nodoc:
 
-  ##
-  # The attribute bitmask
+      ##
+      # The attribute bitmask
 
-  attr_reader :mask
+      attr_reader :mask
 
-  ##
-  # After this many paragraphs the input will be cut off.
+      ##
+      # After this many paragraphs the input will be cut off.
 
-  attr_reader :paragraph_limit
+      attr_reader :paragraph_limit
 
-  ##
-  # Count of paragraphs found
+      ##
+      # Count of paragraphs found
 
-  attr_reader :paragraphs
+      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.
+      ##
+      # 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
+      def initialize(characters = 100, paragraphs = 3)
+        super()
 
-    @character_limit = characters
-    @paragraph_limit = paragraphs
+        @character_limit = characters
+        @paragraph_limit = paragraphs
 
-    @characters = 0
-    @mask       = 0
-    @paragraphs = 0
+        @characters = 0
+        @mask       = 0
+        @paragraphs = 0
 
-    @markup.add_regexp_handling RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
-  end
+        @markup.add_regexp_handling CrossReference::CROSSREF_REGEXP, :CROSSREF
+      end
 
-  ##
-  # Adds +heading+ to the output as a paragraph
+      ##
+      # Adds +heading+ to the output as a paragraph
 
-  def accept_heading(heading)
-    @res << "<p>#{to_html heading.text}\n"
+      def accept_heading(heading)
+        @res << "<p>#{to_html heading.text}\n"
 
-    add_paragraph
-  end
+        add_paragraph
+      end
 
-  ##
-  # Raw sections are untrusted and ignored
+      ##
+      # Raw sections are untrusted and ignored
 
-  alias accept_raw ignore
+      alias accept_raw ignore
 
-  ##
-  # Rules are ignored
+      ##
+      # Rules are ignored
 
-  alias accept_rule ignore
+      alias accept_rule ignore
 
-  ##
-  # Adds +paragraph+ to the output
+      ##
+      # Adds +paragraph+ to the output
 
-  def accept_paragraph(paragraph)
-    para = @in_list_entry.last || "<p>"
+      def accept_paragraph(paragraph)
+        para = @in_list_entry.last || "<p>"
 
-    text = paragraph.text @hard_break
+        text = paragraph.text @hard_break
 
-    @res << "#{para}#{to_html text}\n"
+        @res << "#{para}#{to_html text}\n"
 
-    add_paragraph
-  end
+        add_paragraph
+      end
 
-  ##
-  # Finishes consumption of +list_item+
+      ##
+      # Finishes consumption of +list_item+
 
-  def accept_list_item_end(list_item)
-  end
+      def accept_list_item_end(list_item)
+      end
 
-  ##
-  # Prepares the visitor for consuming +list_item+
+      ##
+      # Prepares the visitor for consuming +list_item+
 
-  def accept_list_item_start(list_item)
-    @res << list_item_start(list_item, @list.last)
-  end
+      def accept_list_item_start(list_item)
+        @res << list_item_start(list_item, @list.last)
+      end
 
-  ##
-  # Prepares the visitor for consuming +list+
+      ##
+      # 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
+      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
+      ##
+      # Adds +verbatim+ to the output
 
-  def accept_verbatim(verbatim)
-    throw :done if @characters >= @character_limit
-    input = verbatim.text.rstrip
+      def accept_verbatim(verbatim)
+        throw :done if @characters >= @character_limit
+        input = verbatim.text.rstrip
+        text = truncate(input, @character_limit - @characters)
+        @characters += input.length
+        text << " #{TO_HTML_CHARACTERS[text.encoding][:ellipsis]}" unless text == input
 
-    text = truncate input
-    text << ' ...' unless text == input
+        super Markup::Verbatim.new text
 
-    super RDoc::Markup::Verbatim.new text
+        add_paragraph
+      end
 
-    add_paragraph
-  end
+      ##
+      # Prepares the visitor for HTML snippet generation
 
-  ##
-  # Prepares the visitor for HTML snippet generation
+      def start_accepting
+        super
 
-  def start_accepting
-    super
+        @characters = 0
+      end
 
-    @characters = 0
-  end
+      ##
+      # Removes escaping from the cross-references in +target+ and escapes HTML
+      # characters, since snippets don't link cross-references.
 
-  ##
-  # Removes escaping from the cross-references in +target+
+      def handle_regexp_CROSSREF(text)
+        convert_string(text.delete_prefix('\\'))
+      end
 
-  def handle_regexp_CROSSREF(target)
-    target.text.sub(/\A\\/, '')
-  end
+      ##
+      # Lists are paragraphs, but notes and labels have a separator
 
-  ##
-  # +target+ is a <code><br></code>
+      def list_item_start(list_item, list_type)
+        throw :done if @characters >= @character_limit
 
-  def handle_regexp_HARD_BREAK(target)
-    @characters -= 4
-    '<br>'
-  end
+        case list_type
+        when :BULLET, :LALPHA, :NUMBER, :UALPHA
+          "<p>"
+        when :LABEL, :NOTE
+          labels = Array(list_item.label).map do |label|
+            to_html label
+          end.join ', '
 
-  ##
-  # Lists are paragraphs, but notes and labels have a separator
+          labels << " &mdash; " unless labels.empty?
 
-  def list_item_start(list_item, list_type)
-    throw :done if @characters >= @character_limit
+          start = "<p>#{labels}"
+          @characters += 1 # try to include the label
+          start
+        else
+          raise Error, "Invalid list type: #{list_type.inspect}"
+        end
+      end
 
-    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 ', '
+      ##
+      # Returns just the text of +link+, +url+ is only used to determine the link
+      # type.
+
+      def gen_url(url, text)
+        if url =~ /^rdoc-label:([^:]*)(?::(.*))?/
+          type = "link"
+        elsif url =~ /([A-Za-z]+):(.*)/
+          type = $1
+        else
+          type = "http"
+        end
+
+        if (type == "http" or type == "https" or type == "link") and
+           url =~ /\.(gif|png|jpg|jpeg|bmp)$/
+          ''
+        else
+          text.sub(%r%^#{type}:/*%, '')
+        end
+      end
 
-      labels << " &mdash; " unless labels.empty?
+      ##
+      # In snippets, there are no lists
 
-      start = "<p>#{labels}"
-      @characters += 1 # try to include the label
-      start
-    else
-      raise RDoc::Error, "Invalid list type: #{list_type.inspect}"
-    end
-  end
+      def html_list_name(list_type, open_tag)
+        ''
+      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
+      ##
+      # Throws +:done+ when paragraph_limit paragraphs have been encountered
 
-    if (type == "http" or type == "https" or type == "link") and
-       url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then
-      ''
-    else
-      text.sub(%r%^#{type}:/*%, '')
-    end
-  end
+      def add_paragraph
+        @paragraphs += 1
 
-  ##
-  # In snippets, there are no lists
+        throw :done if @paragraphs >= @paragraph_limit
+      end
 
-  def html_list_name(list_type, open_tag)
-    ''
-  end
+      ##
+      # Marks up +content+
 
-  ##
-  # Throws +:done+ when paragraph_limit paragraphs have been encountered
+      def convert(content)
+        catch :done do
+          return super
+        end
 
-  def add_paragraph
-    @paragraphs += 1
+        end_accepting
+      end
 
-    throw :done if @paragraphs >= @paragraph_limit
-  end
+      def handle_PLAIN_TEXT(text) # :nodoc:
+        return if inline_limit_reached?
 
-  ##
-  # Marks up +content+
+        truncated = truncate(text, @inline_character_limit)
+        @inline_character_limit -= text.size
+        emit_inline(convert_string(truncated))
+      end
 
-  def convert(content)
-    catch :done do
-      return super
-    end
+      def handle_REGEXP_HANDLING_TEXT(text) # :nodoc:
+        return if inline_limit_reached?
 
-    end_accepting
-  end
+        # We can't truncate text including html tags.
+        # Just emit as is, and count all characters including html tag part.
+        emit_inline(text)
+        @inline_character_limit -= text.size
+      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}"
+      def handle_BOLD(nodes)
+        super unless inline_limit_reached?
       end
 
-      if @characters >= @character_limit then
-        off_tags res, RDoc::Markup::AttrChanger.new(0, @mask)
-        break
+      def handle_BOLD_WORD(word)
+        super unless inline_limit_reached?
       end
-    end
 
-    res << ' ...' if @characters >= @character_limit
+      def handle_EM(nodes)
+        super unless inline_limit_reached?
+      end
 
-    res.join
-  end
+      def handle_EM_WORD(word)
+        super unless inline_limit_reached?
+      end
 
-  ##
-  # Maintains a bitmask to allow HTML elements to be closed properly.  See
-  # RDoc::Markup::Formatter.
+      def handle_TT(code)
+        super unless inline_limit_reached?
+      end
 
-  def on_tags(res, item)
-    @mask ^= item.turn_on
+      def handle_STRIKE(nodes)
+        super unless inline_limit_reached?
+      end
 
-    super
-  end
+      def handle_HARD_BREAK
+        super unless inline_limit_reached?
+      end
 
-  ##
-  # Maintains a bitmask to allow HTML elements to be closed properly.  See
-  # RDoc::Markup::Formatter.
+      def handle_TIDYLINK(label_part, url)
+        traverse_inline_nodes(label_part) unless inline_limit_reached?
+      end
 
-  def off_tags(res, item)
-    @mask ^= item.turn_off
+      def inline_limit_reached?
+        @inline_character_limit <= 0
+      end
 
-    super
-  end
+      def handle_inline(text)
+        limit = @character_limit - @characters
+        return ['', 0] if limit <= 0
+        @inline_character_limit = limit
+        res = super
+        res << " #{TO_HTML_CHARACTERS[text.encoding][:ellipsis]}" if @inline_character_limit <= 0
+        @characters += limit - @inline_character_limit
+        res
+      end
 
-  ##
-  # Truncates +text+ at the end of the first word after the character_limit.
+      def to_html(item)
+        throw :done if @characters >= @character_limit
+        handle_inline(item)
+      end
 
-  def truncate(text)
-    length = text.length
-    characters = @characters
-    @characters += length
+      ##
+      # Truncates +text+ at the end of the first word after the limit.
 
-    return text if @characters < @character_limit
+      def truncate(text, limit)
+        return text if limit >= text.size
+        return '' if limit <= 0
 
-    remaining = @character_limit - characters
+        text =~ /\A(.{#{limit},}?)(\s|$)/m # TODO word-break instead of \s?
 
-    text =~ /\A(.{#{remaining},}?)(\s|$)/m # TODO word-break instead of \s?
+        $1
+      end
 
-    $1
+    end
   end
-
 end

data/lib/rdoc/markup/to_joined_paragraph.rb

@@ -1,46 +1,45 @@
 # 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.
+module RDoc
+  class Markup
+    ##
+    # 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 ToJoinedParagraph < Markup::Formatter
+      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.flat_map do |string, chunk|
+          string ? chunk.join.rstrip : chunk
+        end
+
+        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
 
-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.flat_map do |string, chunk|
-      string ? chunk.join.rstrip : chunk
     end
-
-    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