tomparse 0.3.0 → 0.4.0

data/lib/tomparse.yml

@@ -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.4.0
+date: '2013-02-11'

data/lib/tomparse/argument.rb

@@ -0,0 +1,69 @@
+module TomParse
+
+  # Encapsulate a method argument.
+  #
+  class Argument
+
+    attr_accessor :name
+
+    attr_accessor :description
+
+    attr_accessor :options
+
+    # Create new Argument object.
+    #
+    # name        - name of argument
+    # description - argument description
+    #
+    def initialize(name, description = '')
+      @name = name.to_s.intern
+      parse(description)
+    end
+
+    # Is this an optional argument?
+    #
+    # Returns Boolean.
+    def optional?
+      @description.downcase.include? 'optional'
+    end
+
+    # Parse arguments section. Arguments occur subsequent to
+    # the description.
+    #
+    # section - String containing argument definitions.
+    #
+    # Returns nothing.
+    def parse(description)
+      desc = []
+      opts = []
+
+      lines = description.lines.to_a
+
+      until lines.empty? or /^\s+\:(\w+)\s+-\s+(.*?)$/ =~ lines.first
+        desc << lines.shift.chomp.squeeze(" ")
+      end
+
+      opts = []
+      last_indent = nil
+
+      lines.each do |line|
+        next if line.strip.empty?
+        indent = line.scan(/^\s*/)[0].to_s.size
+
+        if last_indent && indent > last_indent
+          opts.last.description << line.squeeze(" ")
+        else
+          param, d = line.split(" - ")
+          opts << Option.new(param.strip, d.strip) if param && d
+        end
+
+        last_indent = indent
+      end
+
+      @description = desc.join
+      @options     = opts
+    end
+
+  end
+
+end

data/lib/tomparse/option.rb

@@ -0,0 +1,30 @@
+module TomParse
+
+  # Encapsulate a named parameter.
+  #
+  class Option
+
+    attr_accessor :name
+
+    attr_accessor :description
+
+    # Create new Argument object.
+    #
+    # name        - name of option
+    # description - option description
+    #
+    def initialize(name, description = '')
+      @name = name.to_s.intern
+      @description = description
+    end
+
+    # Is this a required option?
+    #
+    # Returns Boolean.
+    def required?
+      @description.downcase.include? 'required'
+    end
+
+  end
+
+end

data/lib/tomparse/parse_error.rb

@@ -0,0 +1,30 @@
+module TomParse
+
+  # Raised when comment can't be parsed, which means it's most
+  # likely not valid TomDoc.
+  #
+  class ParseError < RuntimeError
+    # Create new ParseError object.
+    #
+    # doc - document string
+    #
+    def initialize(doc)
+      @doc = doc
+    end
+
+    # Provide access to document string.
+    #
+    # Returns String.
+    def message
+      @doc
+    end
+
+    # Provide access to document string.
+    #
+    # Returns String.
+    def to_s
+      @doc
+    end
+  end
+
+end

data/lib/tomparse/parser.rb

@@ -0,0 +1,699 @@
+module TomParse
+
+  # Encapsulate parsed tomdoc documentation.
+  #
+  # TODO: Currently uses lazy evaluation, eventually this should
+  # be removed and simply parsed all at once.
+  #
+  class Parser
+
+    #
+    attr_accessor :raw
+
+    # Public: Initialize a TomDoc object.
+    #
+    # text - The raw text of a method or class/module comment.
+    #
+    # Returns new TomDoc instance.
+    def initialize(text, parse_options={})
+      @raw = text.to_s.strip
+
+      @arguments        = []
+      @options          = []
+      @examples         = []
+      @returns          = []
+      @raises           = []
+      @signatures       = []
+      @signature_fields = []
+      @tags             = []
+
+      #parse unless @raw.empty?
+    end
+
+    # Raw documentation text.
+    #
+    # Returns String of raw documentation text.
+    def to_s
+      @raw
+    end
+
+    # Validate given comment text.
+    #
+    # Returns true if comment is valid, otherwise false.
+    def self.valid?(text)
+      new(text).valid?
+    end
+
+    # Validate raw comment.
+    #
+    # TODO: This needs improvement.
+    #
+    # Returns true if comment is valid, otherwise false.
+    def valid?
+      begin
+        new(text).validate
+        true
+      rescue ParseError
+        false
+      end
+    end
+
+    # Validate raw comment.
+    #
+    # Returns true if comment is valid.
+    # Raises ParseError if comment is not valid.
+    def validate
+      if !raw.include?('Returns')
+        raise ParseError.new("No `Returns' statement.")
+      end
+
+      if sections.size < 2
+        raise ParseError.new("No description section found.")
+      end
+
+      true
+    end
+
+    # The raw comment text cleaned-up and ready for section parsing.
+    #
+    # Returns cleaned-up comment String.
+    def tomdoc
+      lines = raw.split("\n")
+
+      # remove remark symbol
+      if lines.all?{ |line| /^\s*#/ =~ line }   
+        lines = lines.map do |line|
+          line =~ /^(\s*#)/ ? line.sub($1, '') : nil
+        end
+      end
+
+      # for some reason the first line is coming in without indention
+      # regardless, so we temporary remove it
+      first = lines.shift
+
+      # remove indention
+      spaces = lines.map do |line|
+        next if line.strip.empty?
+        md = /^(\s*)/.match(line)
+        md ? md[1].size : nil
+      end.compact
+
+      space = spaces.min || 0
+      lines = lines.map do |line|
+        if line.strip.empty?
+          line.strip
+        else
+          line[space..-1]
+        end
+      end
+
+      # put first line back
+      lines.unshift(first.sub(/^\s*/,'')) if first
+
+      lines.compact.join("\n")
+    end
+
+    # List of comment sections. These are divided simply on "\n\n".
+    #
+    # Returns Array of comment sections.
+    def sections
+      parsed {
+        @sections
+      }
+    end
+
+    # Description of method or class/module.
+    #
+    # Returns description String.
+    def description
+      parsed {
+        @description
+      }
+    end
+
+    # Arguments list.
+    #
+    # Returns list of arguments.
+    def arguments
+      parsed {
+        @arguments
+      }
+    end
+    alias args arguments
+
+    # Keyword arguments, aka Options.
+    #
+    # Returns list of options.
+    def options
+      parsed {
+        @options
+      }
+    end
+    alias keyword_arguments options
+
+    # List of use examples of a method or class/module.
+    #
+    # Returns String of examples.
+    def examples
+      parsed {
+        @examples
+      }
+    end
+
+    # Description of a methods yield procedure.
+    #
+    # Returns String decription of yield procedure.
+    def yields
+      parsed {
+        @yields
+      }
+    end
+
+    # The list of retrun values a method can return.
+    #
+    # Returns Array of method return descriptions.
+    def returns
+      parsed {
+        @returns
+      }
+    end
+
+    # A list of errors a method might raise.
+    #
+    # Returns Array of method raises descriptions.
+    def raises
+      parsed {
+        @raises
+      }
+    end
+
+    # A list of alternate method signatures.
+    #
+    # Returns Array of signatures.
+    def signatures
+      parsed {
+        @signatures 
+      }
+    end
+
+    # A list of signature fields.
+    #
+    # Returns Array of field definitions.
+    def signature_fields
+      parsed {
+        @signature_fields
+      }
+    end
+
+    # List of tags.
+    #
+    # Returns an associatve array of tags. [Array<Array<String>>]
+    def tags
+      parsed {
+        @tags
+      }
+    end
+
+    # Method status, can be `Public`, `Internal` or `Deprecated`.
+    #
+    # Returns [String]
+    def status
+      parsed {
+        @status
+      }
+    end
+
+    # Check if method is public.
+    #
+    # Returns true if method is public.
+    def public?
+      parsed {
+        @status == 'Public'
+      }
+    end
+
+    # Check if method is internal.
+    #
+    # Returns true if method is internal.
+    def internal?
+      parsed {
+        @status == 'Internal'
+      }
+    end
+
+    # Check if method is deprecated.
+    #
+    # Returns true if method is deprecated.
+    def deprecated?
+      parsed {
+        @status == 'Deprecated'
+      }
+    end
+
+=begin
+    # Internal: Parse the Tomdoc formatted comment.
+    #
+    # Returns true if there was a comment to parse.
+    def parse
+      @parsed = true
+
+      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?                  # got nothing
+         break if s =~ /^\w+\s+\-/m       # argument line
+         break if section_type(s) != nil  # another section type
+         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
+        parse_arguments(sections.shift)
+      end
+
+      current = sections.shift
+      while current
+        case type = section_type(current)
+        #when :arguments
+        #  parse_arguments(current)
+        #when :options
+        #  parse_options(current)
+        when :examples
+          parse_examples(current, sections)
+        when :yields
+          parse_yields(current)
+        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
+
+      return @parsed
+    end
+=end
+
+    # Internal: Parse the Tomdoc formatted comment.
+    #
+    # Returns true if there was a comment to parse.
+    def parse
+      @parsed = true
+
+      sections = smart_split(tomdoc)
+
+      return false if sections.empty?
+
+      # We are assuming that the first section is always description.
+      # And it should be, but people aren't always proper, so perhaps
+      # this can be made a little smarter in the future.
+      parse_description(sections.shift)
+
+      # The second section may be arguments.
+      if sections.first && sections.first =~ /^\w+\s+\-/m
+        parse_arguments(sections.shift)
+      end
+
+      current = sections.shift
+      while current
+        case type = section_type(current)
+        when :arguments
+          parse_arguments(current)
+        when :options
+          parse_options(current)
+        when :example
+          parse_example(current)
+        when :examples
+          parse_examples(current)
+        when :yields
+          parse_yields(current)
+        when :returns
+          parse_returns(current)
+        when :raises
+          parse_raises(current)
+        when :signature
+          parse_signature(current)
+        when Symbol
+          parse_tag(current)
+        end
+        current = sections.shift
+      end
+
+      return @parsed
+    end
+
+  private
+
+    # Has the comment been parsed yet?
+    def parsed(&block)
+      parse unless @parsed
+      block.call
+    end
+
+    # Split the documentation up into proper sections.
+    #
+    # Returns an array section strings. [Array<String>]
+    def smart_split(doc)
+      splits = []
+      index  = -1
+
+      lines = doc.lines.to_a
+
+      # Remove any blank lines off the top.
+      lines.shift while lines.first && lines.first.strip.empty?
+
+      # Keep a copy of the lines for later use.
+      doc_lines = lines.dup
+     
+      # The first line may have a `Public`/`Private`/`Deprecated` marker.
+      # We need to remove that for the moment to properly check for 
+      # subsequent labeled sections.
+      #first = lines.first.dup
+      #lines.first.sub(/^[A-Z]\w+\:\s*/, '')
+
+      # The description is always the first section, but it may have
+      # multiple paragraphs. And the second section may be an arguments
+      # list without a header. This loop handles that.
+      while line = lines.shift
+        index += 1
+        if argument_line?(line)
+          splits << index
+          break
+        elsif section_type(line)
+          splits << index
+          break
+        end
+      end
+      
+      # The rest of the the document should have identifiable section markers.
+      while line = lines.shift
+        index += 1
+        if section_type(line)
+          splits << index
+        end
+      end
+
+      # Now we split the documentation up into sections using
+      # the line indexes we collected above.
+      sections = []
+      b = 0
+      splits.shift if splits.first == 0
+      splits.each do |i|
+        sections << doc_lines[b...i].join
+        b = i
+      end
+      sections << doc_lines[b..-1].join
+
+      return sections
+    end
+
+    # Check if a line of text could be an argument definition.
+    # I.e. it has a word followed by a dash.
+    #
+    # Return [Boolean]
+    def argument_line?(line)
+      /^\w+\s+\-/m =~ line.strip
+    end
+
+    # Determine section type.
+    def section_type(section)
+      case section
+      when /\AArguments\s*$/
+        :arguments
+      when /\AOptions\s*$/
+        :options
+      when /\AExamples\s*$/
+        :examples
+      when /\AExample\s*$/
+        :example
+      when /\ASignature(s)?\s*$/
+        :signature
+      when /^Yield(s)?/
+        :yields
+      when /^Return(s)?/
+        :returns
+      when /^Raise(s)?/
+        :raises
+      when /\A([A-Z]\w+)\:\ /
+        $1.to_sym
+      else
+        nil
+      end
+    end
+
+    # Recognized description status.
+    TOMDOC_STATUS = ['Internal', 'Public', 'Deprecated']
+
+    # Parse description.
+    #
+    # section - String containig description.
+    #
+    # Returns nothing.
+    def parse_description(section)
+      if md = /^([A-Z]\w+\:)/.match(section)
+        @status = md[1].chomp(':')
+        if TOMDOC_STATUS.include?(@status)
+          @description = md.post_match.strip
+        else
+          @description = section.strip
+        end
+      else
+        @description = section.strip
+      end   
+    end
+
+    # Parse arguments section. Arguments occur subsequent to
+    # the description.
+    #
+    # section - String containing argument definitions.
+    #
+    # Returns nothing.
+    def parse_arguments(section)
+      args = []
+      last_indent = nil
+
+      section.lines.each do |line|
+        next if /^Arguments\s*$/i =~ line  # optional header
+        next if line.strip.empty?
+        indent = line.scan(/^\s*/)[0].to_s.size
+
+        if last_indent && indent >= last_indent
+          args.last.description << "\r\n" + line
+        else
+          param, desc = line.split(" - ")
+          args << Argument.new(param.strip, desc.to_s.strip) if param #&& desc
+          last_indent = indent + 1
+        end
+      end
+
+      args.each do |arg|
+        arg.parse(arg.description)
+      end
+
+      @arguments = args
+    end
+
+    # the description.
+    #
+    # section - String containing argument definitions.
+    #
+    # Returns nothing.
+    def parse_options(section)
+      opts = []
+      last_indent = nil
+
+      section.lines.each do |line|
+        next if /^\s*Options\s*$/i =~ line  # optional header
+        next if line.strip.empty?
+        indent = line.scan(/^\s*/)[0].to_s.size
+
+        if last_indent && indent > 0 && indent >= last_indent
+          opts.last.description << "\r\n" + line
+        else
+          param, desc = line.split(" - ")
+          opts << Option.new(param.strip, desc.strip) if param && desc
+        end
+
+        last_indent = indent
+      end
+
+      #opts.each do |opt|
+      #  opt.parse(arg.description)
+      #end
+
+      @options = opts
+    end
+
+    # Parse example.
+    #
+    # section  - String starting with `Examples`.
+    # sections - All sections subsequent to section.
+    #
+    # Returns nothing.
+    def parse_example(section)
+      examples = []
+
+      # TODO: make the unidention smarter (could be more than 2 spaces)
+      section = section.sub('Example', '').gsub(/^\s{2}/,'')
+
+      @examples << section unless section.strip.empty?
+    end
+
+    # Parse examples.
+    #
+    # section  - String starting with `Examples`.
+    # sections - All sections subsequent to section.
+    #
+    # Returns nothing.
+    def parse_examples(section)
+      #examples = []
+
+      # TODO: make the unidention smarter (could be more than 2 spaces)
+      section = section.sub('Examples', '')
+
+      section.split("\n\n").each do |ex|
+        @examples << ex.gsub(/^\s{2}/,'') unless ex.strip.empty?
+      end
+    end
+
+    # Parse yields section.
+    #
+    # section - String contaning Yields line.
+    #
+    # Returns nothing.
+    def parse_yields(section)
+      @yields = section.strip
+    end
+
+    # Parse returns section.
+    #
+    # section - String contaning Returns and/or Raises lines.
+    #
+    # Returns nothing.
+    def parse_returns(section)
+      text = section.gsub(/\s+/, ' ').strip
+      @returns << text
+
+      #returns, raises, current = [], [], []
+      #
+      #lines = section.split("\n")  
+      #lines.each do |line|
+      #  case line
+      #  when /^Returns/
+      #    returns << line
+      #    current = returns
+      #  when /^Raises/
+      #    raises << line
+      #    current = raises
+      #  when /^\s+/
+      #    current.last << line.squeeze(' ')
+      #  else
+      #    current << line  # TODO: What to do with non-compliant line?
+      #  end
+      #end
+      #
+      #@returns.concat(returns)
+      #@raises.concat(raises)
+    end
+
+    # Parse raises section.
+    #
+    # section - String contaning Raises text.
+    #
+    # Returns nothing.
+    def parse_raises(section)
+      text = section.gsub(/\s+/, ' ').strip
+      @raises << text.strip
+    end
+
+    # Parse signature section.
+    #
+    # IMPORTANT! This is not mojombo TomDoc! Rather signatures are simply
+    # a list of alternate ways to call a method, e.g. when *args is used but
+    # only specific argument patterns are possible.
+    #
+    # section - String starting with `Signature`.
+    #
+    # Returns nothing.
+    def parse_signature(section)
+      signatures = []
+
+      section = section.sub(/^\s*Signature(s)?/, '').strip
+
+      lines = section.lines.to_a
+
+      lines.each do |line|
+        next if line.strip.empty?
+        signatures << line.strip
+      end
+
+      @signatures = signatures
+
+      #if line =~ /^\w+\s*\-/m
+      #  parse_signature_fields(sections.shift)
+      #end
+    end
+
+=begin
+    # Subsequent to Signature section there can be field
+    # definitions.
+    #
+    # section  - String subsequent to signatures.
+    #
+    # Returns nothing.
+    def parse_signature_fields(section)
+      args = []
+      last_indent = nil
+
+      section.split("\n").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(" ")
+        else
+          param, desc = line.split(" - ")
+          args << Argument.new(param.strip, desc.strip) if param && desc
+        end
+
+        last_indent = indent
+      end
+
+      @signature_fields = args
+    end
+=end
+
+    # Tags are arbitrary sections designated by a capitalized label and a colon.
+    #
+    # label   - String name of the tag.
+    # section - String of the tag section.
+    #
+    # Returns nothing.
+    def parse_tag(section)
+      md = /^([A-Z]\w+)\:\ /m.match(section)
+ 
+      label = md[1]
+      desc  = md.post_match
+
+      warn "No label?" unless label
+
+      @tags << [label, desc.strip] if label
+    end
+
+  end
+
+end