rocco 0.6 → 0.7

data/bin/rocco

@@ -8,6 +8,7 @@
 #/                          The string to recognize as a comment marker
 #/   -o, --output=<dir>     Directory where generated HTML files are written
 #/   -t, --template=<path>  The file to use as template when rendering HTML
+#/   -d, --docblocks        Parse Docblock @annotations in comments
 #/       --help             Show this help message
 
 require 'optparse'
@@ -39,6 +40,7 @@ ARGV.options { |o|
   o.on("-l", "--language=LANG") { |lang| options[:language] = lang }
   o.on("-c", "--comment-chars=CHARS") { |chars| options[:comment_chars] = Regexp.escape(chars) }
   o.on("-t", "--template=TEMPLATE") { |template| options[:template_file] = template }
+  o.on("-d", "--docblocks") { options[:docblocks] = true }
   o.on_tail("-h", "--help") { usage($stdout, 0) }
   o.parse!
 } or abort_with_note

data/lib/rocco.rb

@@ -52,8 +52,7 @@ require 'net/http'
 
 # Code is run through [Pygments](http://pygments.org/) for syntax
 # highlighting. If it's not installed, locally, use a webservice.
-include FileTest
-if !ENV['PATH'].split(':').any? { |dir| executable?("#{dir}/pygmentize") }
+if !ENV['PATH'].split(':').any? { |dir| File.executable?("#{dir}/pygmentize") }
   warn "WARNING: Pygments not found. Using webservice."
 end
 
@@ -74,7 +73,7 @@ end
 #   to `nil` (that is, Mustache will use `./lib/rocco/layout.mustache`)_.
 #
 class Rocco
-  VERSION = '0.6'
+  VERSION = '0.7'
 
   def initialize(filename, sources=[], options={}, &block)
     @file       = filename
@@ -159,7 +158,7 @@ class Rocco
   # Returns `true` if `pygmentize` is available locally, `false` otherwise.
   def pygmentize?
     @_pygmentize ||= ENV['PATH'].split(':').
-      any? { |dir| executable?("#{dir}/pygmentize") }
+      any? { |dir| File.executable?("#{dir}/pygmentize") }
   end
 
   # If `pygmentize` is available, we can use it to autodetect a file's
@@ -171,7 +170,7 @@ class Rocco
   def detect_language
     @_language ||=
       if pygmentize?
-        %x[pygmentize -N #{@file}].strip!
+        %x[pygmentize -N #{@file}].strip.split('+').first
       else
         "text"
       end
@@ -208,45 +207,55 @@ class Rocco
   #
   # At the moment, we're only returning `:single`.  Consider this
   # groundwork for block comment parsing.
+  C_STYLE_COMMENTS = {
+    :single => "//",
+    :multi  => { :start => "/**", :middle => "*", :end => "*/" },
+    :heredoc => nil
+  }
   COMMENT_STYLES  = {
     "bash"          =>  { :single => "#", :multi => nil },
-    "c"             =>  {
-      :single => "//",
-      :multi  => { :start => "/**", :middle => "*", :end => "*/" }
-    },
+    "c"             =>  C_STYLE_COMMENTS,
     "coffee-script" =>  {
       :single => "#",
-      :multi  => { :start => "###", :middle => nil, :end => "###" }
-    },
-    "cpp" =>  {
-      :single => "//",
-      :multi  => { :start => "/**", :middle => "*", :end => "*/" }
+      :multi  => { :start => "###", :middle => nil, :end => "###" },
+      :heredoc => nil
     },
+    "cpp" =>  C_STYLE_COMMENTS,
+    "csharp" => C_STYLE_COMMENTS,
     "css"           =>  {
       :single => nil,
-      :multi  => { :start => "/**", :middle => "*", :end => "*/" }
-    },
-    "java"          =>  {
-      :single => "//",
-      :multi  => { :start => "/**", :middle => "*", :end => "*/" }
+      :multi  => { :start => "/**", :middle => "*", :end => "*/" },
+      :heredoc => nil
     },
-    "js"            =>  {
-      :single => "//",
-      :multi  => { :start => "/**", :middle => "*", :end => "*/" }
+    "html"           =>  {
+      :single => nil,
+      :multi => { :start => '<!--', :middle => nil, :end => '-->' },
+      :heredoc => nil
     },
+    "java"          =>  C_STYLE_COMMENTS,
+    "js"            =>  C_STYLE_COMMENTS,
     "lua"           =>  {
       :single => "--",
-      :multi => nil
+      :multi => nil,
+      :heredoc => nil
     },
+    "php" => C_STYLE_COMMENTS,
     "python"        =>  {
       :single => "#",
-      :multi  => { :start => '"""', :middle => nil, :end => '"""' }
+      :multi  => { :start => '"""', :middle => nil, :end => '"""' },
+      :heredoc => nil
     },
     "rb"            =>  {
       :single => "#",
-      :multi  => { :start => '=begin', :middle => nil, :end => '=end' }
+      :multi  => { :start => '=begin', :middle => nil, :end => '=end' },
+      :heredoc => "<<-"
+    },
+    "scheme"        =>  { :single => ";;",  :multi => nil, :heredoc => nil },
+    "xml"           =>  {
+      :single => nil,
+      :multi => { :start => '<!--', :middle => nil, :end => '-->' },
+      :heredoc => nil
     },
-    "scheme"        =>  { :single => ";;",  :multi => nil },
   }
 
   def generate_comment_chars
@@ -254,7 +263,7 @@ class Rocco
       if COMMENT_STYLES[@options[:language]]
         COMMENT_STYLES[@options[:language]]
       else
-        { :single => @options[:comment_chars], :multi => nil }
+        { :single => @options[:comment_chars], :multi => nil, :heredoc => nil }
       end
   end
 
@@ -279,8 +288,9 @@ class Rocco
     # To detect both block comments and single-line comments, we'll set
     # up a tiny state machine, and loop through each line of the file.
     # This requires an `in_comment_block` boolean, and a few regular
-    # expressions for line tests.
+    # expressions for line tests.  We'll do the same for fake heredoc parsing.
     in_comment_block = false
+    in_heredoc = false
     single_line_comment, block_comment_start, block_comment_mid, block_comment_end =
       nil, nil, nil, nil
     if not @options[:comment_chars][:single].nil?
@@ -289,42 +299,77 @@ class Rocco
     if not @options[:comment_chars][:multi].nil?
       block_comment_start = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:multi][:start])}\\s*$")
       block_comment_end   = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:multi][:end])}\\s*$")
+      block_comment_one_liner = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:multi][:start])}\\s*(.*?)\\s*#{Regexp.escape(@options[:comment_chars][:multi][:end])}\\s*$")
+      block_comment_start_with = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:multi][:start])}\\s*(.*?)$")
+      block_comment_end_with = Regexp.new("\\s*(.*?)\\s*#{Regexp.escape(@options[:comment_chars][:multi][:end])}\\s*$")
       if @options[:comment_chars][:multi][:middle]
         block_comment_mid = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:multi][:middle])}\\s?")
       end
     end
+    if not @options[:comment_chars][:heredoc].nil?
+      heredoc_start = Regexp.new("#{Regexp.escape(@options[:comment_chars][:heredoc])}(\\S+)$")
+    end
     lines.each do |line|
       # If we're currently in a comment block, check whether the line matches
-      # the _end_ of a comment block.
+      # the _end_ of a comment block or the _end_ of a comment block with a
+      # comment.
       if in_comment_block
-        if block_comment_end && line.match( block_comment_end )
+        if block_comment_end && line.match(block_comment_end)
+          in_comment_block = false
+        elsif block_comment_end_with && line.match(block_comment_end_with)
           in_comment_block = false
+          docs << line.match(block_comment_end_with).captures.first.
+                        sub(block_comment_mid || '', '')
         else
-          docs << line.sub( block_comment_mid || '', '' )
+          docs << line.sub(block_comment_mid || '', '')
+        end
+      # If we're currently in a heredoc, we're looking for the end of the
+      # heredoc, and everything it contains is code.
+      elsif in_heredoc
+        if line.match(Regexp.new("^#{Regexp.escape(in_heredoc)}$"))
+          in_heredoc = false
         end
-      # Otherwise, check whether the line matches the beginning of a block, or
-      # a single-line comment all on it's lonesome.  In either case, if there's
-      # code, start a new section
+        code << line
+      # Otherwise, check whether the line starts a heredoc. If so, note the end
+      # pattern, and the line is code.  Otherwise check whether the line matches
+      # the beginning of a block, or a single-line comment all on it's lonesome.
+      # In either case, if there's code, start a new section.
       else
-        if block_comment_start && line.match( block_comment_start )
+        if heredoc_start && line.match(heredoc_start)
+          in_heredoc = $1
+          code << line
+        elsif block_comment_one_liner && line.match(block_comment_one_liner)
+          if code.any?
+            sections << [docs, code]
+            docs, code = [], []
+          end
+          docs << line.match(block_comment_one_liner).captures.first
+        elsif block_comment_start && line.match(block_comment_start)
+          in_comment_block = true
+          if code.any?
+            sections << [docs, code]
+            docs, code = [], []
+          end
+        elsif block_comment_start_with && line.match(block_comment_start_with)
           in_comment_block = true
           if code.any?
             sections << [docs, code]
             docs, code = [], []
           end
-        elsif single_line_comment && line.match( single_line_comment )
+          docs << line.match(block_comment_start_with).captures.first
+        elsif single_line_comment && line.match(single_line_comment)
           if code.any?
             sections << [docs, code]
             docs, code = [], []
           end
-          docs << line.sub( single_line_comment || '', '' )
+          docs << line.sub(single_line_comment || '', '')
         else
           code << line
         end
       end
     end
     sections << [docs, code] if docs.any? || code.any?
-    normalize_leading_spaces( sections )
+    normalize_leading_spaces(sections)
   end
 
   # Normalizes documentation whitespace by checking for leading whitespace,
@@ -340,13 +385,13 @@ class Rocco
   #
   # should yield a comment block of `Comment 1\nComment 2` and code of
   # `def func():\n  print "omg!"`
-  def normalize_leading_spaces( sections )
+  def normalize_leading_spaces(sections)
     sections.map do |section|
       if section.any? && section[0].any?
-        leading_space = section[0][0].match( "^\s+" )
+        leading_space = section[0][0].match("^\s+")
         if leading_space
           section[0] =
-            section[0].map{ |line| line.sub( /^#{leading_space.to_s}/, '' ) }
+            section[0].map{ |line| line.sub(/^#{leading_space.to_s}/, '') }
         end
       end
       section
@@ -368,11 +413,26 @@ class Rocco
     [docs_blocks, code_blocks]
   end
 
+  # Take a list of block comments and convert Docblock @annotations to
+  # Markdown syntax.
+  def docblock(docs)
+    docs.map do |doc|
+      doc.split("\n").map do |line|
+        line.match(/^@\w+/) ? line.sub(/^@(\w+)\s+/, '> **\1** ')+"  " : line
+      end.join("\n")
+    end
+  end
+
   # Take the result of `split` and apply Markdown formatting to comments and
   # syntax highlighting to source code.
   def highlight(blocks)
     docs_blocks, code_blocks = blocks
 
+    # Pre-process Docblock @annotations.
+    if @options[:docblocks]
+      docs_blocks = docblock(docs_blocks)
+    end
+
     # Combine all docs blocks into a single big markdown document with section
     # dividers and run through the Markdown processor. Then split it back out
     # into separate sections.
@@ -390,7 +450,7 @@ class Rocco
       divider_output = Regexp.new(
         [ "\\n*",
           span,
-          Regexp.escape(front),
+          Regexp.escape(CGI.escapeHTML(front)),
           ' DIVIDER',
           espan,
           "\\n*"
@@ -402,17 +462,17 @@ class Rocco
       divider_input  = "\n\n#{front}\nDIVIDER\n#{back}\n\n"
       divider_output = Regexp.new(
         [ "\\n*",
-          span, Regexp.escape(front), espan,
+          span, Regexp.escape(CGI.escapeHTML(front)), espan,
           "\\n",
           span, "DIVIDER", espan,
           "\\n",
-          span, Regexp.escape(back), espan,
+          span, Regexp.escape(CGI.escapeHTML(back)), espan,
           "\\n*"
         ].join, Regexp::MULTILINE
       )
     end
 
-    code_stream = code_blocks.join( divider_input )
+    code_stream = code_blocks.join(divider_input)
 
     code_html =
       if pygmentize?

data/lib/rocco/layout.mustache

@@ -3,7 +3,7 @@
 <head>
   <meta http-equiv="content-type" content="text/html;charset=utf-8">
   <title>{{ title }}</title>
-  <link rel="stylesheet" href="http://github.com/jashkenas/docco/raw/0.3.0/resources/docco.css">
+  <link rel="stylesheet" href="http://jashkenas.github.com/docco/resources/docco.css">
 </head>
 <body>
 <div id='container'>

data/rocco.gemspec

@@ -3,8 +3,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
 
   s.name = 'rocco'
-  s.version = '0.6'
-  s.date = '2011-03-05'
+  s.version = '0.7'
+  s.date = '2011-05-22'
 
   s.description = "Docco in Ruby"
   s.summary     = s.description
@@ -29,10 +29,13 @@ Gem::Specification.new do |s|
     test/helper.rb
     test/suite.rb
     test/test_basics.rb
+    test/test_block_comment_styles.rb
     test/test_block_comments.rb
     test/test_comment_normalization.rb
     test/test_commentchar_detection.rb
     test/test_descriptive_section_names.rb
+    test/test_docblock_annotations.rb
+    test/test_heredoc.rb
     test/test_language_detection.rb
     test/test_reported_issues.rb
     test/test_skippable_lines.rb

data/test/test_block_comment_styles.rb

@@ -0,0 +1,64 @@
+require File.expand_path('../helper', __FILE__)
+
+class RoccoBlockCommentTest < Test::Unit::TestCase
+  def test_one_liner
+    r = Rocco.new( 'test', '', { :language => "c" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        [ [ "Comment 1" ], [ "def codeblock", "end" ] ]
+      ],
+      r.parse( "/** Comment 1 */\ndef codeblock\nend\n" )
+    )
+  end
+
+  def test_block_start_with_comment
+    r = Rocco.new( 'test', '', { :language => "c" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        [ [ "Comment 1a", "Comment 1b" ], [ "def codeblock", "end" ] ]
+      ],
+      r.parse( "/** Comment 1a\n * Comment 1b\n */\ndef codeblock\nend\n" )
+    )
+  end
+
+  def test_block_end_with_comment
+    r = Rocco.new( 'test', '', { :language => "c" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        [ [ "Comment 1a", "Comment 1b" ], [ "def codeblock", "end" ] ]
+      ],
+      r.parse( "/**\n * Comment 1a\n Comment 1b */\ndef codeblock\nend\n" )
+    )
+  end
+
+  def test_block_end_with_comment_and_middle
+    r = Rocco.new( 'test', '', { :language => "c" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        [ [ "Comment 1a", "Comment 1b" ], [ "def codeblock", "end" ] ]
+      ],
+      r.parse( "/**\n * Comment 1a\n * Comment 1b */\ndef codeblock\nend\n" )
+    )
+  end
+
+  def test_block_start_with_comment_and_end_with_comment
+    r = Rocco.new( 'test', '', { :language => "c" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        [ [ "Comment 1a", "Comment 1b" ], [ "def codeblock", "end" ] ]
+      ],
+      r.parse( "/** Comment 1a\n Comment 1b */\ndef codeblock\nend\n" )
+    )
+  end
+
+  def test_block_start_with_comment_and_end_with_comment_and_middle
+    r = Rocco.new( 'test', '', { :language => "c" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        [ [ "Comment 1a", "Comment 1b" ], [ "def codeblock", "end" ] ]
+      ],
+      r.parse( "/** Comment 1a\n * Comment 1b */\ndef codeblock\nend\n" )
+    )
+  end
+
+end

data/test/test_docblock_annotations.rb

@@ -0,0 +1,22 @@
+require File.expand_path('../helper', __FILE__)
+
+class RoccoDocblockAnnotationsTest < Test::Unit::TestCase
+  def test_basics
+    r = Rocco.new( 'test', '', { :language => "c", :docblocks => true } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        "Comment\n\n> **param** mixed foo  \n> **return** void  "
+      ],
+      r.docblock( ["Comment\n\n@param mixed foo\n@return void"] )
+    )
+  end
+  def test_highlighted_in_blocks
+    r = Rocco.new( 'test', '', { :language => "c", :docblocks => true } ) { "" } # Generate throwaway instance so I can test `parse`
+    highlighted = r.highlight( r.split( r.parse( "/**\n * Comment\n * @param type name\n */\ndef codeblock\nend\n" ) ) )
+
+    assert_equal(
+      "<p>Comment</p>\n\n<blockquote><p><strong>param</strong> type name</p></blockquote>\n",
+      highlighted[0][0]
+    )
+  end
+end

data/test/test_heredoc.rb

@@ -0,0 +1,13 @@
+require File.expand_path('../helper', __FILE__)
+
+class RoccoHeredocTest < Test::Unit::TestCase
+  def test_basics
+    r = Rocco.new( 'test', '', { :language => "rb" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        [ [ "Comment 1" ], [ "heredoc <<-EOH", "#comment", "code", "EOH" ] ]
+      ],
+      r.parse( "# Comment 1\nheredoc <<-EOH\n#comment\ncode\nEOH" )
+    )
+  end
+end

metadata

@@ -1,12 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: rocco
 version: !ruby/object:Gem::Version 
-  hash: 7
+  hash: 5
   prerelease: false
   segments: 
   - 0
-  - 6
-  version: "0.6"
+  - 7
+  version: "0.7"
 platform: ruby
 authors: 
 - Ryan Tomayko
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-05 00:00:00 -08:00
+date: 2011-05-22 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -72,10 +72,13 @@ files:
 - test/helper.rb
 - test/suite.rb
 - test/test_basics.rb
+- test/test_block_comment_styles.rb
 - test/test_block_comments.rb
 - test/test_comment_normalization.rb
 - test/test_commentchar_detection.rb
 - test/test_descriptive_section_names.rb
+- test/test_docblock_annotations.rb
+- test/test_heredoc.rb
 - test/test_language_detection.rb
 - test/test_reported_issues.rb
 - test/test_skippable_lines.rb