tomparse 0.2.1 → 0.3.0

data/.index

@@ -0,0 +1,68 @@
+---
+revision: 2013
+type: ruby
+sources:
+- var
+- VERSION
+authors:
+- name: trans
+  email: transfire@gmail.com
+organizations:
+- name: Rubyworks
+  website: http://rubyworks.github.com
+requirements:
+- groups:
+  - test
+  development: true
+  name: citron
+- groups:
+  - test
+  development: true
+  name: ae
+- groups:
+  - build
+  development: true
+  name: detroit
+conflicts: []
+alternatives: []
+resources:
+- type: home
+  uri: http://rubyworks.github.com/tomparse
+  label: Homepage
+- type: code
+  uri: http://github.com/rubyworks/tomparse
+  label: Source Code
+- type: api
+  uri: http://rubydoc.info/gems/tomparse/frames
+  label: API Guide
+- type: mail
+  uri: http://groups.google.com/group/rubyworks-mailinglist
+  label: Mailing List
+- type: chat
+  uri: http://chat.us.freenode.net/rubyworks
+  label: IRC Channel
+repositories:
+- name: upstream
+  scm: git
+  uri: http://github.com/rubyworks/tomparse/tomparse.git
+categories:
+- documentation
+copyrights:
+- holder: Rubyworks
+  year: '2012'
+  license: BSD-2-Clause
+customs: []
+paths:
+  lib:
+  - lib
+created: '2012-03-04'
+summary: TomDoc parser for Ruby
+title: TomParse
+name: tomparse
+description: ! 'TomParse provides no other functionality than to take a code comment
+
+  and parse it in to a convenient object-oriented structure in accordance
+
+  with TomDoc standard.'
+version: 0.3.0
+date: '2013-01-21'

data/HISTORY.md

@@ -1,5 +1,17 @@
 # Release History
 
+## 0.3.0 / 2012-01-21
+
+This release fixes a bug which prevented descriptions from having
+multiple paragraphs. In addition it adds support for section tags.
+See the README for more information of tags.
+
+Changes:
+
+* Fix multi-paragraph description parsing.
+* Add support for tags.
+
+
 ## 0.2.1 / 2012-04-30
 
 This release fixes indention with multi-line examples.

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright 2002 Rubyworks. All rights reserved.
+BSD-2-Clause License
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
@@ -20,5 +20,3 @@ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-(BSD-2-Clauase License)

data/README.md

@@ -6,26 +6,28 @@
 [Gem Page](http://rubygems.org/gems/tomparse)
 
 [![Build Status](https://secure.travis-ci.org/rubyworks/tomparse.png)](http://travis-ci.org/rubyworks/tomparse)
+[![Gem Version](https://badge.fury.io/rb/tomparse.png)](http://badge.fury.io/rb/tomparse)
 
 
 ## Description
 
-TomParse is TomDoc parser for Ruby. It provides no other functionality
-than to take a code comment and parse it in to a convenient object-oriented
-structure in accordance with TomDoc standard.
+TomParse is a TomDoc parser for Ruby. It provides no other functionality than
+to take a code comment and parse it in to a convenient object-oriented
+structure in accordance with TomDoc standard. See [TomDoc](https://github.com/mojombo/tomdoc)
+for more information about the TomDoc format.
 
-See [TomDoc](https://github.com/mojombo/tomdoc) for more information about
-the TomDoc format.
 
+## Instruction
+
+### Installation
 
-## Installation
+TomParse is available as a Ruby gem.
 
     $ gem install tomparse
 
+### Usage
 
-## Instruction
-
-The primay interface is the `TomParse.parse` method. It will parse the
+The primary interface is the `TomParse.parse` method. It will parse the
 comment and return a `TomParse::TomDoc` instance.
 
     TomParse.parse(comment)  #=> TomParse::TomDoc
@@ -38,13 +40,12 @@ the comment, such as `#arguments`, `#examples`, etc.
 See the [API documention](http://rubydoc.info/gems/tomparse/frames)
 for more details on this.
 
-
-## Example
+### Example
 
 If you are unfamiliar with TomDoc, an example TomDoc comment for a method
 looks something like this:
 
-    # Duplicate some text an abitrary number of times.
+    # Duplicate some text an arbitrary number of times.
     #
     # text  - The String to be duplicated.
     # count - The Integer number of times to duplicate the text.
@@ -58,12 +59,64 @@ looks something like this:
       text * count
     end
 
+### Extra Features
+
+Okay, we told a little white lie in the description. TomParse does take a tiny 
+bit of liberty with the specification to offer up some additional documentation
+goodness. In particular, TomParse recoginizes paragraphs starting with an all-caps
+word, followed by a colon and a space, as special tags. Here is an example:
+
+```ruby
+  # Method to do something.
+  #
+  # TODO: This is a todo note.
+  #
+  # Returns nothing.
+  def dosomething
+    ...
+```
+
+When this is parsed, rather then lumping the TODO line in with the description,
+the TomDoc instance will have a `tags` property containing `{'todo'=>'This is a todo note.'}`.
+
+
+## Resources
+
+* [Website](http://rubyworks.github.com/tomparse)
+* [Source Code](http://github.com/rubyworks/tomparse) (Github)
+* [API Reference](http://rubydoc.info/gems/tomparse/frames")
+* [Mailiing List](http://groups.google.com/group/rubyworks-mailinglist)
+* [IRC Chat](http://chat.us.freenode.net/rubyworks)
+* [Upstream Repo](http://github.com/rubyworks/tomparse/tomparse.git)
+
+
+## Authors
+
+<ul>
+<li class="iauthor vcard">
+  <span class="nickname">trans</span>
+  <span>&lt;<a class="email" href="mailto:transfire@gmail.com">transfire@gmail.com</a>&gt;</span>
+  <br/><a class="url" href="http://trans.gihub.com/">http://trans.github.com/</a>
+</li>
+</ul>
+
+
+## Development 
+
+### Requirements
+
+* [Citron](http://rubyworks.github.com/citron) (testing)
+* [AE](http://rubyworks.github.com/ae) (testing)
+* [Detroit](http://detroit.github.com/detroit) (building)
+
+
+## Copyright & License
 
-## License
+TomParse is copyrighted open-source software.
 
-Copyright (c) 2012 Rubyworks
+Copyright (c) 2012 [Rubyworks](http://rubyworks.github.com). All rights reserved.
 
-TomParse is distributable under the terms of the *BSD-2-Clause* license.
+TomParse is distributable under the terms of the [BSD-2-Clause]((http://www.spdx.org/licenses/BSD-2-Clause) license.
 
 See LICENSE.txt for details.
 

data/lib/tomparse.rb

@@ -31,10 +31,14 @@ module TomParse
       @raises           = []
       @signatures       = []
       @signature_fields = []
+      @tags             = {}
 
       parse unless @raw.empty?
     end
 
+    # Raw documentation text.
+    #
+    # Returns String of raw documentation text.
     def to_s
       @raw
     end
@@ -192,6 +196,15 @@ module TomParse
       }
     end
 
+    # A mapping of tags.
+    #
+    # Returns Hash of tags.
+    def tags
+      parsed {
+        @tags
+      }
+    end
+
     # Check if method is public.
     #
     # Returns true if method is public.
@@ -233,11 +246,24 @@ module TomParse
     def parse
       @parsed = true
 
-      @sections = tomdoc.split("\n\n")
-      sections  = @sections.dup
+      sections = tomdoc.split("\n\n")
 
       return false if sections.empty?
 
+      # The description is always the first section, but it may have
+      # multiple paragraphs. This routine collects those together.
+      desc = [sections.shift]
+      loop do
+         s = sections.first
+         break if s.nil?
+         break if s =~ /^\w+\s+\-/m
+         break if section_type(s) != nil
+         desc << sections.shift
+      end
+      sections = [desc.join("\n\n")] + sections
+  
+      @sections = sections.dup
+
       parse_description(sections.shift)
 
       if sections.first && sections.first =~ /^\w+\s+\-/m
@@ -246,15 +272,19 @@ module TomParse
 
       current = sections.shift
       while current
-        case current
-        when /^Examples/
+        case type = section_type(current)
+        when :examples
           parse_examples(current, sections)
-        when /^Yields/
+        when :yields
           parse_yields(current)
-        when /^(Returns|Raises)/
-          parse_returns(current)
-        when /^Signature/
+        when :returns
+          parse_returns(current)  # also does raises
+        when :raises
+          parse_returns(current)  # also does returns
+        when :signature
           parse_signature(current, sections)
+        when Symbol
+          parse_tag(current)
         end
         current = sections.shift
       end
@@ -262,6 +292,30 @@ module TomParse
       return @parsed
     end
 
+    #
+    #
+    def section_type(section)
+      case section
+      when /^Examples/
+        :examples
+      when /^Yields/
+        :yields
+      when /^Returns/
+        :returns
+      when /^Raises/
+        :raises
+      when /^Signature/
+        :signature
+      when /^([A-Z]*)\:\ /
+        $1.downcase.to_sym
+      else
+        nil
+      end
+    end
+
+    # Recognized description status.
+    TOMDOC_STATUS = ['Internal', 'Public', 'Deprecated']
+
     # Parse description.
     #
     # section - String containig description.
@@ -269,8 +323,12 @@ module TomParse
     # Returns nothing.
     def parse_description(section)
       if md = /^([A-Z]\w+\:)/.match(section)
-        @status      = md[1].chomp(':')
-        @description = md.post_match.strip
+        @status = md[1].chomp(':')
+        if TOMDOC_STATUS.include?(@status)
+          @description = md.post_match.strip
+        else
+          @description = section.strip
+        end
       else
         @description = section.strip
       end   
@@ -286,12 +344,12 @@ module TomParse
       args = []
       last_indent = nil
 
-      section.split("\n").each do |line|
+      section.lines.each do |line|
         next if line.strip.empty?
         indent = line.scan(/^\s*/)[0].to_s.size
 
-        if last_indent && indent > last_indent
-          args.last.description << line.squeeze(" ")
+        if last_indent && indent > 0 && indent >= last_indent
+          args.last.description << "\r\n" + line
         else
           param, desc = line.split(" - ")
           args << Argument.new(param.strip, desc.strip) if param && desc
@@ -300,6 +358,10 @@ module TomParse
         last_indent = indent
       end
 
+      args.each do |arg|
+        arg.parse(arg.description)
+      end
+
       @arguments = args
     end
 
@@ -413,6 +475,22 @@ module TomParse
       @signature_fields = args
     end
 
+    # Tags are arbitrary sections designated by all cap labels and a colon.
+    #
+    # label   - String name of the tag.
+    # section - String of the tag section.
+    #
+    # Returns nothing.
+    def parse_tag(section)
+
+      md = /^([A-Z]*)\:\ /.match(section)
+
+      label = md[1]
+      text  = md.post_match
+
+      @tags[label.downcase] = text
+    end
+
   end
 
   # Encapsulate a method argument.
@@ -455,7 +533,7 @@ module TomParse
       lines = description.lines.to_a
 
       until lines.empty? or /^\s+\:(\w+)\s+-\s+(.*?)$/ =~ lines.first
-        desc << lines.shift
+        desc << lines.shift.chomp.squeeze(" ")
       end
 
       opts = []
@@ -466,10 +544,10 @@ module TomParse
         indent = line.scan(/^\s*/)[0].to_s.size
 
         if last_indent && indent > last_indent
-          args.last.description << line.squeeze(" ")
+          opts.last.description << line.squeeze(" ")
         else
-          param, desc = line.split(" - ")
-          opts << Option.new(param.strip, desc.strip) if param && desc
+          param, d = line.split(" - ")
+          opts << Option.new(param.strip, d.strip) if param && d
         end
 
         last_indent = indent

data/test/test_tags.rb

@@ -0,0 +1,38 @@
+require 'helper'
+
+testcase "Tags" do
+
+  context "TODO" do
+
+    setup do
+      @tomdoc = TomParse::TomDoc.new(<<-END)
+        # This is an example of tags.
+        #
+        # TODO: Something we have to do.
+      END
+    end
+
+    test "tags has todo" do
+      assert @tomdoc.tags['todo'] == "Something we have to do."
+    end
+
+  end
+
+  context "FOO" do
+
+    setup do
+      @tomdoc = TomParse::TomDoc.new(<<-END)
+        # This is an example of tags.
+        #
+        # FOO: They can be anything really.
+      END
+    end
+
+    test "tags has foo" do
+      assert @tomdoc.tags['foo'] == "They can be anything really."
+    end
+
+  end
+
+
+end

data/test/test_tomdoc.rb

@@ -13,6 +13,10 @@ testcase TomParse::TomDoc do
         #           duplicate the text.
         # reverse - An optional Boolean indicating
         #           whether to reverse the result text or not.
+        # options - Options (default: {})
+        #         :insert_spaces - Whether to insert spaces
+        #         :upcase - Convert the string to upper case
+        # blk - The block.
         #
         # Examples
         #   multiplex('Tom', 4)
@@ -38,13 +42,22 @@ testcase TomParse::TomDoc do
     end
 
     test "parses args" do
-      @comment.args.size.assert == 3
+      @comment.args.size.assert == 5
+    end
+
+    test "know a hash arg's options" do
+      @comment.args[3].options.size.assert == 2
+      @comment.args[3].options.first.name.assert == :':insert_spaces'
+      @comment.args[3].options[1].name.assert == :':upcase'
+      @comment.args[3].options.first.description.assert == 'Whether to insert spaces'
+      @comment.args[3].options[1].description.assert == 'Convert the string to upper case'
     end
 
     test "knows an arg's name" do
       @comment.args.first.name.assert == :text
       @comment.args[1].name.assert == :count
       @comment.args[2].name.assert == :reverse
+      @comment.args[3].name.assert == :options
     end
 
     test "knows an arg's description" do
@@ -57,7 +70,7 @@ testcase TomParse::TomDoc do
 
     test "knows an arg's optionality" do
       refute @comment.args.first.optional?
-      assert @comment.args.last.optional?
+      assert @comment.args[2].optional?
     end
 
     test "knows how many examples there are" do
@@ -90,6 +103,28 @@ testcase TomParse::TomDoc do
 
   end
 
+  context "handles multiple paragraph descriptions" do
+
+    setup do
+      @comment = TomParse::TomDoc.new %{
+        # Has an initial paragraph.
+        #
+        # Has another paragraph in the description.
+        #
+        # Examples
+        #
+        #   def multiplex(str, length)
+        #     str * length
+        #   end
+      }
+    end
+
+    test "correctly handles multiple paragraphs" do
+      @comment.description.assert == "Has an initial paragraph.\n\nHas another paragraph in the description."
+    end
+
+  end
+
   context "handles whitespace in examples" do
 
     setup do

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: tomparse
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
-- Trans
+- trans
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-30 00:00:00.000000000 Z
+date: 2013-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: citron
-  requirement: &21084040 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,31 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *21084040
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ae
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: detroit
-  requirement: &21077200 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,12 +53,17 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *21077200
-description: ! 'TomParse is a Ruby TomDoc parser. It contains no other functionality
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ! 'TomParse provides no other functionality than to take a code comment
 
-  than the ability to take a comment and parse it in accordance to the
+  and parse it in to a convenient object-oriented structure in accordance
 
-  TomDoc standard.'
+  with TomDoc standard.'
 email:
 - transfire@gmail.com
 executables: []
@@ -47,17 +73,17 @@ extra_rdoc_files:
 - HISTORY.md
 - README.md
 files:
-- .ruby
+- .index
+- .rubyrc
 - lib/tomparse.rb
-- lib/tomparse.yml
 - test/helper.rb
 - test/test_prefixes.rb
 - test/test_signatures.rb
+- test/test_tags.rb
 - test/test_tomdoc.rb
-- LICENSE.txt
 - HISTORY.md
 - README.md
-- Config.rb
+- LICENSE.txt
 homepage: http://rubyworks.github.com/tomparse
 licenses:
 - BSD-2-Clause
@@ -79,8 +105,14 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.11
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: TomDoc parser for Ruby
-test_files: []
+test_files:
+- test/helper.rb
+- test/test_signatures.rb
+- test/test_tags.rb
+- test/test_tomdoc.rb
+- test/test_prefixes.rb
+has_rdoc: 

data/.ruby

@@ -1,55 +0,0 @@
----
-source:
-- meta
-authors:
-- name: Trans
-  email: transfire@gmail.com
-copyrights:
-- holder: Rubyworks
-  year: '2012'
-  license: BSD-2-Clause
-requirements:
-- name: citron
-  groups:
-  - test
-  development: true
-- name: detroit
-  groups:
-  - build
-  development: true
-dependencies: []
-alternatives: []
-conflicts: []
-repositories:
-- uri: git@github.com:rubyworks/tomparse.git
-  scm: git
-  name: upstream
-resources:
-- uri: http://rubyworks.github.com/tomparse
-  name: home
-  type: home
-- uri: http://rubydoc.info/gems/tomparse
-  name: docs
-  type: doc
-- uri: http://github.com/rubyworks/tomparse
-  name: code
-  type: code
-- uri: http://groups.google.com/groups/rubyworks-mailinglist
-  name: mail
-  type: mail
-extra: {}
-load_path:
-- lib
-revision: 0
-created: '2012-03-04'
-summary: TomDoc parser for Ruby
-title: TomParse
-version: 0.2.1
-name: tomparse
-description: ! 'TomParse is a Ruby TomDoc parser. It contains no other functionality
-
-  than the ability to take a comment and parse it in accordance to the
-
-  TomDoc standard.'
-organization: rubyworks
-date: '2012-04-30'

data/lib/tomparse.yml

@@ -1,55 +0,0 @@
----
-source:
-- meta
-authors:
-- name: Trans
-  email: transfire@gmail.com
-copyrights:
-- holder: Rubyworks
-  year: '2012'
-  license: BSD-2-Clause
-requirements:
-- name: citron
-  groups:
-  - test
-  development: true
-- name: detroit
-  groups:
-  - build
-  development: true
-dependencies: []
-alternatives: []
-conflicts: []
-repositories:
-- uri: git@github.com:rubyworks/tomparse.git
-  scm: git
-  name: upstream
-resources:
-- uri: http://rubyworks.github.com/tomparse
-  name: home
-  type: home
-- uri: http://rubydoc.info/gems/tomparse
-  name: docs
-  type: doc
-- uri: http://github.com/rubyworks/tomparse
-  name: code
-  type: code
-- uri: http://groups.google.com/groups/rubyworks-mailinglist
-  name: mail
-  type: mail
-extra: {}
-load_path:
-- lib
-revision: 0
-created: '2012-03-04'
-summary: TomDoc parser for Ruby
-title: TomParse
-version: 0.2.1
-name: tomparse
-description: ! 'TomParse is a Ruby TomDoc parser. It contains no other functionality
-
-  than the ability to take a comment and parse it in accordance to the
-
-  TomDoc standard.'
-organization: rubyworks
-date: '2012-04-30'