rdoc 3.9.5 → 3.10.pre.1

data/lib/rdoc/parser/rd.rb

@@ -0,0 +1,22 @@
+##
+# Parse a RD format file.  The parsed RDoc::Markup::Document is attached as a
+# file comment.
+
+class RDoc::Parser::RD < RDoc::Parser
+
+  include RDoc::Parser::Text
+
+  parse_files_matching(/\.rd(?:\.[^.]+)?$/)
+
+  ##
+  # Creates an rd-format TopLevel for the given file.
+
+  def scan
+    comment = RDoc::Comment.new @content, @top_level
+    comment.format = 'rd'
+
+    @top_level.comment = comment
+  end
+
+end
+

data/lib/rdoc/parser/ruby.rb

@@ -7,15 +7,6 @@
 #       by Keiju ISHITSUKA (Nippon Rational Inc.)
 #
 
-require 'rdoc/ruby_token'
-require 'rdoc/ruby_lex'
-
-require 'rdoc/code_objects'
-require 'rdoc/token_stream'
-require 'rdoc/markup/pre_process'
-require 'rdoc/parser'
-require 'rdoc/parser/ruby_tools'
-
 $TOKEN_DEBUG ||= nil
 
 ##
@@ -173,6 +164,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
     @scanner = RDoc::RubyLex.new content, @options
     @scanner.exception_on_syntax_error = false
     @prev_seek = nil
+    @markup = @options.markup
 
     @encoding = nil
     @encoding = @options.encoding if Object.const_defined? :Encoding
@@ -213,7 +205,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
     unget_tk tk
 
-    comment
+    new_comment comment
   end
 
   ##
@@ -225,22 +217,6 @@ class RDoc::Parser::Ruby < RDoc::Parser
     abort msg
   end
 
-  ##
-  # Look for a 'call-seq' in the comment, and override the normal parameter
-  # stuff
-  #--
-  # TODO handle undent
-
-  def extract_call_seq(comment, meth)
-    if comment.sub!(/:?call-seq:(.*?)(^\s*#?\s*$|\z)/m, '') then
-      seq = $1
-      seq.gsub!(/^\s*\#\s*/, '')
-      meth.call_seq = seq
-    end
-
-    meth
-  end
-
   ##
   # Looks for a true or false token.  Returns false if TkFALSE or TkNIL are
   # found.
@@ -412,8 +388,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
            'attr', 'attr_accessor', 'attr_reader', 'attr_writer' then
         false # handled elsewhere
       when 'section' then
-        context.set_current_section param, comment
-        comment.replace ''
+        context.set_current_section param, comment.dup
+        comment.text = ''
         break
       end
     end
@@ -432,6 +408,15 @@ class RDoc::Parser::Ruby < RDoc::Parser
     "#{prefix} #{message}"
   end
 
+  ##
+  # Creates a comment with the correct format
+
+  def new_comment comment
+    c = RDoc::Comment.new comment, @top_level
+    c.format = @markup
+    c
+  end
+
   ##
   # Creates an RDoc::Attr for the name following +tk+, setting the comment to
   # +comment+.
@@ -751,15 +736,18 @@ class RDoc::Parser::Ruby < RDoc::Parser
   # Generates an RDoc::Method or RDoc::Attr from +comment+ by looking for
   # :method: or :attr: directives in +comment+.
 
-  def parse_comment(container, tk, comment)
+  def parse_comment container, tk, comment
+    return parse_comment_tomdoc container, tk, comment if @markup == 'tomdoc'
     column  = tk.char_no
     offset  = tk.seek
     line_no = tk.line_no
 
-    singleton = !!comment.sub!(/(^# +:?)(singleton-)(method:)/, '\1\3')
+    text = comment.text
+
+    singleton = !!text.sub!(/(^# +:?)(singleton-)(method:)/, '\1\3')
 
     # REFACTOR
-    if comment.sub!(/^# +:?method: *(\S*).*?\n/i, '') then
+    if text.sub!(/^# +:?method: *(\S*).*?\n/i, '') then
       name = $1 unless $1.empty?
 
       meth = RDoc::GhostMethod.new get_tkread, name
@@ -769,16 +757,17 @@ class RDoc::Parser::Ruby < RDoc::Parser
       meth.line      = line_no
 
       meth.start_collecting_tokens
-      indent = TkSPACE.new nil, 1, 1
+      indent = TkSPACE.new 0, 1, 1
       indent.set_text " " * column
 
-      position_comment = TkCOMMENT.new nil, line_no, 1
+      position_comment = TkCOMMENT.new 0, line_no, 1
       position_comment.set_text "# File #{@top_level.absolute_name}, line #{line_no}"
       meth.add_tokens [position_comment, NEWLINE_TOKEN, indent]
 
       meth.params = ''
 
-      extract_call_seq comment, meth
+      comment.normalize
+      comment.extract_call_seq meth
 
       return unless meth.name
 
@@ -787,7 +776,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
       meth.comment = comment
 
       @stats.add_method meth
-    elsif comment.sub!(/# +:?(attr(_reader|_writer|_accessor)?): *(\S*).*?\n/i, '') then
+    elsif text.sub!(/# +:?(attr(_reader|_writer|_accessor)?): *(\S*).*?\n/i, '') then
       rw = case $1
            when 'attr_reader' then 'R'
            when 'attr_writer' then 'W'
@@ -809,6 +798,43 @@ class RDoc::Parser::Ruby < RDoc::Parser
     true
   end
 
+  ##
+  # Creates an RDoc::Method on +container+ from +comment+ if there is a
+  # Signature section in the comment
+
+  def parse_comment_tomdoc container, tk, comment
+    return unless signature = RDoc::TomDoc.signature(comment)
+    offset  = tk.seek
+    line_no = tk.line_no
+
+    name, = signature.split %r%[ \(]%, 2
+
+    meth = RDoc::GhostMethod.new get_tkread, name
+    meth.record_location @top_level
+    meth.offset    = offset
+    meth.line      = line_no
+
+    meth.start_collecting_tokens
+    indent = TkSPACE.new 0, 1, 1
+    indent.set_text " " * offset
+
+    position_comment = TkCOMMENT.new 0, line_no, 1
+    position_comment.set_text "# File #{@top_level.absolute_name}, line #{line_no}"
+    meth.add_tokens [position_comment, NEWLINE_TOKEN, indent]
+
+    meth.call_seq = signature
+
+    comment.normalize
+
+    return unless meth.name
+
+    container.add_method meth
+
+    meth.comment = comment
+
+    @stats.add_method meth
+  end
+
   ##
   # Parses an +include+ in +context+ with +comment+
 
@@ -867,7 +893,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
     tmp = RDoc::CodeObject.new
     read_documentation_modifiers tmp, RDoc::ATTR_MODIFIERS
 
-    if comment.sub!(/^# +:?(attr(_reader|_writer|_accessor)?): *(\S*).*?\n/i, '') then
+    if comment.text.sub!(/^# +:?(attr(_reader|_writer|_accessor)?): *(\S*).*?\n/i, '') then
       rw = case $1
            when 'attr_reader' then 'R'
            when 'attr_writer' then 'W'
@@ -908,9 +934,9 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
     skip_tkspace false
 
-    singleton = !!comment.sub!(/(^# +:?)(singleton-)(method:)/, '\1\3')
+    singleton = !!comment.text.sub!(/(^# +:?)(singleton-)(method:)/, '\1\3')
 
-    if comment.sub!(/^# +:?method: *(\S*).*?\n/i, '') then
+    if comment.text.sub!(/^# +:?method: *(\S*).*?\n/i, '') then
       name = $1 unless $1.empty?
     end
 
@@ -939,10 +965,10 @@ class RDoc::Parser::Ruby < RDoc::Parser
     remove_token_listener self
 
     meth.start_collecting_tokens
-    indent = TkSPACE.new nil, 1, 1
+    indent = TkSPACE.new 0, 1, 1
     indent.set_text " " * column
 
-    position_comment = TkCOMMENT.new nil, line_no, 1
+    position_comment = TkCOMMENT.new 0, line_no, 1
     position_comment.value = "# File #{@top_level.absolute_name}, line #{line_no}"
     meth.add_tokens [position_comment, NEWLINE_TOKEN, indent]
     meth.add_tokens @token_stream
@@ -950,7 +976,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
     token_listener meth do
       meth.params = ''
 
-      extract_call_seq comment, meth
+      comment.normalize
+      comment.extract_call_seq meth
 
       container.add_method meth
 
@@ -1084,10 +1111,10 @@ class RDoc::Parser::Ruby < RDoc::Parser
     meth.line   = line_no
 
     meth.start_collecting_tokens
-    indent = TkSPACE.new nil, 1, 1
+    indent = TkSPACE.new 0, 1, 1
     indent.set_text " " * column
 
-    token = TkCOMMENT.new nil, line_no, 1
+    token = TkCOMMENT.new 0, line_no, 1
     token.set_text "# File #{@top_level.absolute_name}, line #{line_no}"
     meth.add_tokens [token, NEWLINE_TOKEN, indent]
     meth.add_tokens @token_stream
@@ -1118,7 +1145,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
       parse_statements container, single, meth
     end
 
-    extract_call_seq comment, meth
+    comment.normalize
+    comment.extract_call_seq meth
 
     meth.comment = comment
 
@@ -1253,7 +1281,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
   # The core of the ruby parser.
 
   def parse_statements(container, single = NORMAL, current_method = nil,
-                       comment = '')
+                       comment = new_comment(''))
+    raise 'no' unless RDoc::Comment === comment
     comment.force_encoding @encoding if @encoding
 
     nest = 1
@@ -1293,6 +1322,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
             end
           end
 
+          comment = new_comment comment
+
           unless comment.empty? then
             look_for_directives_in container, comment
 
@@ -1370,8 +1401,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
           when 'require', 'include' then
             # ignore
           else
-            if comment =~ /\A#\#$/ then
-              case comment
+            if comment.text =~ /\A#\#$/ then
+              case comment.text
               when /^# +:?attr(_reader|_writer|_accessor)?:/ then
                 parse_meta_attr container, single, tk, comment
               else
@@ -1410,7 +1441,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
       end
 
       unless keep_comment then
-        comment = ''
+        comment = new_comment ''
         comment.force_encoding @encoding if @encoding
       end
 
@@ -1497,8 +1528,11 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
   def parse_top_level_statements container
     comment = collect_first_comment
+
     look_for_directives_in container, comment
 
+    @markup = comment.format
+
     # HACK move if to RDoc::Context#comment=
     container.comment = comment if container.document_self unless comment.empty?
 
@@ -1640,13 +1674,11 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
   ##
   # Removes private comments from +comment+
+  #--
+  # TODO remove
 
-  def remove_private_comments(comment)
-    empty = ''
-    empty.force_encoding comment.encoding if Object.const_defined? :Encoding
-
-    comment.gsub!(/^#--.*?^#\+\+\n?/m, empty)
-    comment.sub!(/^#--.*/m, '')
+  def remove_private_comments comment
+    comment.remove_private
   end
 
   ##

data/lib/rdoc/parser/simple.rb

@@ -4,6 +4,8 @@
 
 class RDoc::Parser::Simple < RDoc::Parser
 
+  include RDoc::Parser::Text
+
   parse_files_matching(//)
 
   attr_reader :content # :nodoc:
@@ -24,20 +26,14 @@ class RDoc::Parser::Simple < RDoc::Parser
 
   def scan
     comment = remove_coding_comment @content
-    comment = remove_private_comments comment
+    comment = remove_private_comment comment
+
+    comment = RDoc::Comment.new comment, @top_level
 
     @top_level.comment = comment
-    @top_level.parser = self.class
     @top_level
   end
 
-  ##
-  # Removes comments wrapped in <tt>--/++</tt>
-
-  def remove_private_comments text
-    text.gsub(/^--\n.*?^\+\+/m, '').sub(/^--\n.*/m, '')
-  end
-
   ##
   # Removes the encoding magic comment from +text+
 
@@ -45,5 +41,21 @@ class RDoc::Parser::Simple < RDoc::Parser
     text.sub(/\A# .*coding[=:].*$/, '')
   end
 
+  ##
+  # Removes private comments.
+  #
+  # Unlike RDoc::Comment#remove_private this implementation only looks for two
+  # dashes at the beginning of the line.  Three or more dashes are considered
+  # to be a rule and ignored.
+
+  def remove_private_comment comment
+    # Workaround for gsub encoding for Ruby 1.9.2 and earlier
+    empty = ''
+    empty.force_encoding comment.encoding if Object.const_defined? :Encoding
+
+    comment = comment.gsub(%r%^--\n.*?^\+\+\n?%m, empty)
+    comment.sub(%r%^--\n.*%m, empty)
+  end
+
 end
 

data/lib/rdoc/parser/text.rb

@@ -0,0 +1,11 @@
+##
+# Indicates this parser is text and doesn't contain code constructs.
+#
+# Include this module in a RDoc::Parser subclass to make it show up as a file,
+# not as part of a class or module.
+#--
+# This is not named File to avoid overriding ::File
+
+module RDoc::Parser::Text
+end
+

data/lib/rdoc/rd.rb

@@ -0,0 +1,95 @@
+##
+# RDoc::RD implements the RD format from the rdtool gem.
+#
+# = LICENSE
+#
+# The grammar that produces RDoc::RD::BlockParser and RDoc::RD::InlineParser
+# is included in RDoc under the Ruby License.
+#
+# You can find the original source for rdtool at
+# https://github.com/uwabami/rdtool/
+#
+# You can use, re-distribute or change these files under Ruby's License or GPL.
+# 
+# 1. You may make and give away verbatim copies of the source form of the
+#    software without restriction, provided that you duplicate all of the
+#    original copyright notices and associated disclaimers.
+#
+# 2. You may modify your copy of the software in any way, provided that
+#    you do at least ONE of the following:
+#
+#    a. place your modifications in the Public Domain or otherwise
+#       make them Freely Available, such as by posting said
+#       modifications to Usenet or an equivalent medium, or by allowing
+#       the author to include your modifications in the software.
+#
+#    b. use the modified software only within your corporation or
+#       organization.
+#
+#    c. give non-standard binaries non-standard names, with
+#       instructions on where to get the original software distribution.
+#
+#    d. make other distribution arrangements with the author.
+#
+# 3. You may distribute the software in object code or binary form,
+#    provided that you do at least ONE of the following:
+#
+#    a. distribute the binaries and library files of the software,
+#       together with instructions (in the manual page or equivalent)
+#       on where to get the original distribution.
+#
+#    b. accompany the distribution with the machine-readable source of
+#       the software.
+#
+#    c. give non-standard binaries non-standard names, with
+#       instructions on where to get the original software distribution.
+#
+#    d. make other distribution arrangements with the author.
+#
+# 4. You may modify and include the part of the software into any other
+#    software (possibly commercial).  But some files in the distribution
+#    are not written by the author, so that they are not under these terms.
+#
+#    For the list of those files and their copying conditions, see the
+#    file LEGAL.
+#
+# 5. The scripts and library files supplied as input to or produced as 
+#    output from the software do not automatically fall under the
+#    copyright of the software, but belong to whomever generated them, 
+#    and may be sold commercially, and may be aggregated with this
+#    software.
+#
+# 6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+#    IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+#    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+#    PURPOSE.
+
+class RDoc::RD
+
+  ##
+  # Parses +rd+ source and returns an RDoc::Markup::Document.  If the
+  # <tt>=begin</tt> or <tt>=end</tt> lines are missing they will be added.
+
+  def self.parse rd
+    rd = rd.lines.to_a
+
+    if rd.find { |i| /\S/ === i } and !rd.find{|i| /^=begin\b/ === i } then
+      rd.unshift("=begin\n").push("=end\n")
+    end
+
+    parser = RDoc::RD::BlockParser.new
+    document = parser.parse rd
+
+    # isn't this always true?
+    document.parts.shift if RDoc::Markup::BlankLine === document.parts.first
+    document.parts.pop   if RDoc::Markup::BlankLine === document.parts.last
+
+    document
+  end
+
+  autoload :BlockParser,  'rdoc/rd/block_parser'
+  autoload :InlineParser, 'rdoc/rd/inline_parser'
+  autoload :Inline,       'rdoc/rd/inline'
+
+end
+