rdoc 3.9.5 → 3.10.pre.1

data/lib/rdoc/markup/parser.rb

@@ -1,5 +1,4 @@
 require 'strscan'
-require 'rdoc/text'
 
 ##
 # A recursive-descent parser for RDoc markup.
@@ -52,7 +51,9 @@ class RDoc::Markup::Parser
   attr_reader :tokens
 
   ##
-  # Parses +str+ into a Document
+  # Parses +str+ into a Document.
+  #
+  # Use RDoc::Markup#parse instead of this method.
 
   def self.parse str
     parser = new
@@ -426,7 +427,7 @@ class RDoc::Markup::Parser
                      [:TEXT, s.matched.sub(/\r$/, ''), *token_pos(pos)]
                    end
                  # --- (at least 3) and nothing else on the line => :RULE
-                 when s.scan(/(-{3,}) *$/) then
+                 when s.scan(/(-{3,}) *\r?$/) then
                    [:RULE, s[1].length - 2, *token_pos(pos)]
                  # * or - followed by white space and text => :BULLET
                  when s.scan(/([*-]) +(\S)/) then
@@ -451,10 +452,10 @@ class RDoc::Markup::Parser
                      end
                    [list_type, list_label, *token_pos(pos)]
                  # [text] followed by spaces or end of line => :LABEL
-                 when s.scan(/\[(.*?)\]( +|$)/) then
+                 when s.scan(/\[(.*?)\]( +|\r?$)/) then
                    [:LABEL, s[1], *token_pos(pos)]
                  # text:: followed by spaces or end of line => :NOTE
-                 when s.scan(/(.*?)::( +|$)/) then
+                 when s.scan(/(.*?)::( +|\r?$)/) then
                    [:NOTE, s[1], *token_pos(pos)]
                  # anything else: :TEXT
                  else s.scan(/.*/)
@@ -484,14 +485,3 @@ class RDoc::Markup::Parser
 
 end
 
-require 'rdoc/markup/blank_line'
-require 'rdoc/markup/document'
-require 'rdoc/markup/heading'
-require 'rdoc/markup/list'
-require 'rdoc/markup/list_item'
-require 'rdoc/markup/raw'
-require 'rdoc/markup/paragraph'
-require 'rdoc/markup/indented_paragraph'
-require 'rdoc/markup/rule'
-require 'rdoc/markup/verbatim'
-

data/lib/rdoc/markup/pre_process.rb

@@ -1,6 +1,3 @@
-require 'rdoc/markup'
-require 'rdoc/encoding'
-
 ##
 # Handle common directives that can occur in a block of text:
 #
@@ -13,9 +10,27 @@ require 'rdoc/encoding'
 
 class RDoc::Markup::PreProcess
 
+  ##
+  # An RDoc::Options instance that will be filled in with overrides from
+  # directives
+
   attr_accessor :options
 
-  @registered = {}
+  ##
+  # Adds a post-process handler for directives.  The handler will be called
+  # with the result RDoc::Comment (or text String) and the code object for the
+  # comment (if any).
+
+  def self.post_process &block
+    @post_processors << block
+  end
+
+  ##
+  # Registered post-processors
+
+  def self.post_processors
+    @post_processors
+  end
 
   ##
   # Registers +directive+ as one handled by RDoc.  If a block is given the
@@ -33,6 +48,16 @@ class RDoc::Markup::PreProcess
     @registered
   end
 
+  ##
+  # Clears all registered directives and post-processors
+
+  def self.reset
+    @post_processors = []
+    @registered = {}
+  end
+
+  reset
+
   ##
   # Creates a new pre-processor for +input_file_name+ that will look for
   # included files in +include_path+
@@ -44,7 +69,7 @@ class RDoc::Markup::PreProcess
   end
 
   ##
-  # Look for directives in a chunk of +text+.
+  # Look for directives in the given +text+.
   #
   # Options that we don't handle are yielded.  If the block returns false the
   # directive is restored to the text.  If the block returns nil or no block
@@ -54,27 +79,56 @@ class RDoc::Markup::PreProcess
   # If no matching directive was registered the directive is restored to the
   # text.
   #
-  # If +code_object+ is given and the param is set as metadata on the
-  # +code_object+.  See RDoc::CodeObject#metadata
+  # If +code_object+ is given and the directive is unknown then the
+  # directive's parameter is set as metadata on the +code_object+.  See
+  # RDoc::CodeObject#metadata for details.
 
   def handle text, code_object = nil, &block
-    encoding = if defined?(Encoding) then text.encoding else nil end
+    if RDoc::Comment === text then
+      comment = text
+      text = text.text
+    end
+
+    encoding = text.encoding if defined?(Encoding)
+
     # regexp helper (square brackets for optional)
     # $1      $2  $3        $4      $5
     # [prefix][\]:directive:[spaces][param]newline
-    text.gsub!(/^([ \t]*(?:#|\/?\*)?[ \t]*)(\\?):(\w+):([ \t]*)(.+)?\n/) do
+    text.gsub!(/^([ \t]*(?:#|\/?\*)?[ \t]*)(\\?):(\w+):([ \t]*)(.+)?(\r?\n|$)/) do
       # skip something like ':toto::'
       next $& if $4.empty? and $5 and $5[0, 1] == ':'
 
       # skip if escaped
       next "#$1:#$3:#$4#$5\n" unless $2.empty?
 
+      # This is not in handle_directive because I didn't want to pass another
+      # argument into it
+      if comment and $3 == 'markup' then
+        next "#{$1.strip}\n" unless $5
+        comment.format = $5.downcase
+        next "#{$1.strip}\n"
+      end
+
       handle_directive $1, $3, $5, code_object, encoding, &block
     end
 
+    comment = text unless comment
+
+    self.class.post_processors.each do |handler|
+      handler.call comment, code_object
+    end
+
     text
   end
 
+  ##
+  # Performs the actions described by +directive+ and its parameter +param+.
+  #
+  # +code_object+ is used for directives that operate on a class or module.
+  # +prefix+ is used to ensure the replacement for handled directives is
+  # correct.  +encoding+ is used for the <tt>include</tt> directive.
+  #
+  # For a list of directives in RDoc see RDoc::Markup.
   #--
   # When 1.8.7 support is ditched prefix can be defaulted to ''
 
@@ -92,7 +146,7 @@ class RDoc::Markup::PreProcess
       blankline
     when 'category' then
       if RDoc::Context === code_object then
-        section = code_object.add_section param, ''
+        section = code_object.add_section param
         code_object.temporary_section = section
       end
 

data/lib/rdoc/markup/raw.rb

@@ -24,7 +24,7 @@ class RDoc::Markup::Raw
   end
 
   def == other # :nodoc:
-    self.class == other.class and text == other.text
+    self.class == other.class and @parts == other.parts
   end
 
   ##

data/lib/rdoc/markup/special.rb

@@ -0,0 +1,40 @@
+##
+# Hold details of a special sequence
+
+class RDoc::Markup::Special
+
+  ##
+  # Special type
+
+  attr_reader   :type
+
+  ##
+  # Special text
+
+  attr_accessor :text
+
+  ##
+  # Creates a new special sequence of +type+ with +text+
+
+  def initialize(type, text)
+    @type, @text = type, text
+  end
+
+  ##
+  # Specials are equal when the have the same text and type
+
+  def ==(o)
+    self.text == o.text && self.type == o.type
+  end
+
+  def inspect # :nodoc:
+    "#<RDoc::Markup::Special:0x%x @type=%p, name=%p @text=%p>" % [
+      object_id, @type, RDoc::Markup::Attribute.as_string(type), text.dump]
+  end
+
+  def to_s # :nodoc:
+    "Special: type=#{type}, name=#{RDoc::Markup::Attribute.as_string type}, text=#{text.dump}"
+  end
+
+end
+

data/lib/rdoc/markup/text_formatter_test_case.rb

@@ -1,5 +1,3 @@
-require 'rdoc/markup/formatter_test_case'
-
 ##
 # Test case for creating new plain-text RDoc::Markup formatters.  See also
 # RDoc::Markup::FormatterTestCase

data/lib/rdoc/markup/to_ansi.rb

@@ -1,5 +1,3 @@
-require 'rdoc/markup/to_rdoc'
-
 ##
 # Outputs RDoc markup with vibrant ANSI color!
 

data/lib/rdoc/markup/to_bs.rb

@@ -1,5 +1,3 @@
-require 'rdoc/markup/to_rdoc'
-
 ##
 # Outputs RDoc markup with hot backspace action!  You will probably need a
 # pager to use this output format.

data/lib/rdoc/markup/to_html.rb

@@ -1,10 +1,7 @@
-require 'rdoc/markup/formatter'
-require 'rdoc/markup/inline'
-
 require 'cgi'
 
 ##
-# Outputs RDoc markup as HTML
+# Outputs RDoc markup as HTML.
 
 class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
@@ -16,18 +13,24 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   # Maps RDoc::Markup::Parser::LIST_TOKENS types to HTML tags
 
   LIST_TYPE_TO_HTML = {
-    :BULLET => ['<ul>', '</ul>'],
-    :LABEL  => ['<dl class="rdoc-list">', '</dl>'],
-    :LALPHA => ['<ol style="display: lower-alpha">', '</ol>'],
-    :NOTE   => ['<table class="rdoc-list">', '</table>'],
-    :NUMBER => ['<ol>', '</ol>'],
-    :UALPHA => ['<ol style="display: upper-alpha">', '</ol>'],
+    :BULLET => ['<ul>',                                      '</ul>'],
+    :LABEL  => ['<dl class="rdoc-list label-list">',         '</dl>'],
+    :LALPHA => ['<ol style="list-style-type: lower-alpha">', '</ol>'],
+    :NOTE   => ['<dl class="rdoc-list note-list">',          '</dl>'],
+    :NUMBER => ['<ol>',                                      '</ol>'],
+    :UALPHA => ['<ol style="list-style-type: upper-alpha">', '</ol>'],
   }
 
   attr_reader :res # :nodoc:
   attr_reader :in_list_entry # :nodoc:
   attr_reader :list # :nodoc:
 
+  ##
+  # The RDoc::CodeObject HTML is being generated for.  This is used to
+  # generate namespaced URI fragments
+
+  attr_accessor :code_object
+
   ##
   # Path to this document for relative links
 
@@ -65,14 +68,18 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   def initialize markup = nil
     super
 
-    @th = nil
+    @code_object = nil
+    @from_path = ''
     @in_list_entry = nil
     @list = nil
-    @from_path = ''
+    @th = nil
 
     # external links
     @markup.add_special(/((link:|https?:|mailto:|ftp:|www\.)\S+\w)/, :HYPERLINK)
 
+    # internal links
+    @markup.add_special(/rdoc-[a-z]+:\S+/, :RDOCLINK)
+
     # and links of the form  <text>[<url>]
     @markup.add_special(/(((\{.*?\})|\b\S+?)\[\S+?\])/, :TIDYLINK)
 
@@ -101,6 +108,39 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     gen_url url, url
   end
 
+  ##
+  # +special+ is an rdoc-schemed link that will be converted into a hyperlink.
+  #
+  # For the +rdoc-ref+ scheme the named reference will be returned without
+  # creating a link.
+  #
+  # 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_special_RDOCLINK special
+    url = special.text
+
+    case url
+    when /\Ardoc-ref:/
+      $'
+    when /\Ardoc-label:/
+      text = $'
+
+      text = case text
+             when /\Alabel-/    then $'
+             when /\Afootmark-/ then "^#{$'}"
+             when /\Afoottext-/ then "*#{$'}"
+             else                    text
+             end
+
+      gen_url url, text
+    else
+      url =~ /\Ardoc-[a-z]+:/
+
+      $'
+    end
+  end
+
   ##
   # This +special+ is a link where the label is different from the URL
   # <tt>label[url]</tt> or <tt>{long label}[url]</tt>
@@ -147,10 +187,24 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   ##
   # Adds +verbatim+ to the output
 
-  def accept_verbatim(verbatim)
-    @res << "\n<pre>"
-    @res << CGI.escapeHTML(verbatim.text.rstrip)
-    @res << "</pre>\n"
+  def accept_verbatim verbatim
+    text = verbatim.text.rstrip
+
+    @res << if verbatim.ruby? or parseable? text then
+              options = RDoc::RDoc.current.options if RDoc::RDoc.current
+
+              begin
+                tokens = RDoc::RubyLex.tokenize text, options
+
+                "\n<pre class=\"ruby\">" \
+                "#{RDoc::TokenStream.to_html tokens}" \
+                "</pre>\n"
+              rescue RDoc::RubyLex::Error
+                "\n<pre>#{CGI.escapeHTML text}</pre>\n"
+              end
+            else
+              "\n<pre>#{CGI.escapeHTML text}</pre>\n"
+            end
   end
 
   ##
@@ -208,12 +262,19 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   end
 
   ##
-  # Adds +heading+ to the output
+  # Adds +heading+ to the output.  The headings greater than 6 are trimmed to
+  # level 6.
+
+  def accept_heading heading
+    level = [6, heading.level].min
+
+    label = heading.label
+    label = [@code_object.aref, label].compact.join '-' if
+      @code_object and @code_object.respond_to? :aref
 
-  def accept_heading(heading)
-    @res << "\n<h#{heading.level}>"
+    @res << "\n<h#{level} id=\"#{label}\">"
     @res << to_html(heading.text)
-    @res << "</h#{heading.level}>\n"
+    @res << "</h#{level}>\n"
   end
 
   ##
@@ -233,11 +294,15 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   end
 
   ##
-  # Generate a link for +url+, labeled with +text+.  Handles the special cases
+  # Generate a link to +url+ with content +text+.  Handles the special cases
   # for img: and link: described under handle_special_HYPERLINK
 
-  def gen_url(url, text)
-    if url =~ /([A-Za-z]+):(.*)/ then
+  def gen_url url, text
+    if url =~ /^rdoc-label:([^:]*)(?::(.*))?/ then
+      type = "link"
+      path = "##{$1}"
+      id   = " id=\"#{$2}\"" if $2
+    elsif url =~ /([A-Za-z]+):(.*)/ then
       type = $1
       path = $2
     else
@@ -258,7 +323,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
        url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then
       "<img src=\"#{url}\" />"
     else
-      "<a href=\"#{url}\">#{text.sub(%r{^#{type}:/*}, '')}</a>"
+      "<a#{id} href=\"#{url}\">#{text.sub(%r{^#{type}:/*}, '')}</a>"
     end
   end
 
@@ -275,9 +340,9 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   # Maps attributes to HTML tags
 
   def init_tags
-    add_tag :BOLD, "<b>",  "</b>"
-    add_tag :TT,   "<tt>", "</tt>"
-    add_tag :EM,   "<em>", "</em>"
+    add_tag :BOLD, "<strong>", "</strong>"
+    add_tag :TT,   "<code>",   "</code>"
+    add_tag :EM,   "<em>",     "</em>"
   end
 
   ##
@@ -288,10 +353,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     case list_type
     when :BULLET, :LALPHA, :NUMBER, :UALPHA then
       "<li>"
-    when :LABEL then
-      "<dt>#{to_html list_item.label}</dt>\n<dd>"
-    when :NOTE then
-      "<tr><td class=\"rdoc-term\"><p>#{to_html list_item.label}</p></td>\n<td>"
+    when :LABEL, :NOTE then
+      "<dt>#{to_html list_item.label}\n<dd>"
     else
       raise RDoc::Error, "Invalid list type: #{list_type.inspect}"
     end
@@ -304,15 +367,20 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     case list_type
     when :BULLET, :LALPHA, :NUMBER, :UALPHA then
       "</li>"
-    when :LABEL then
+    when :LABEL, :NOTE then
       "</dd>"
-    when :NOTE then
-      "</td></tr>"
     else
       raise RDoc::Error, "Invalid list type: #{list_type.inspect}"
     end
   end
 
+  ##
+  # Returns true if Ripper is available it can create a sexp from +text+
+
+  def parseable? text
+    text =~ /\b(def|class|module|require)\b|=>|\{\s?\||do \|/
+  end
+
   ##
   # Converts +item+ to HTML using RDoc::Text#to_html