bahuvrihi-tap 0.10.4 → 0.10.5

data/lib/tap/support/lazydoc/comment.rb

@@ -0,0 +1,499 @@
+require 'strscan'
+
+module Tap
+  module Support 
+    module Lazydoc
+      # Comment represents a code comment parsed by Lazydoc.  Comments consist
+      # of a subject and the content of the comment which normally break down
+      # like this:
+      #   
+      #   sample_comment = %Q{
+      #   # this is the content of the comment
+      #   #
+      #   # which may stretch across
+      #   # multiple lines
+      #   this is the subject
+      #   }
+      #   
+      # The subject of a comment is the first non-comment line following the
+      # content, and the content is an array of comment fragments organized 
+      # by line as they would be printed in an output:
+      #
+      #   c = Comment.parse(sample_comment)
+      #   c.subject      # => "this is the subject"
+      #   c.content      
+      #   # => [
+      #   # ["this is the content of the comment"], 
+      #   # [""], 
+      #   # ["which may stretch across", "multiple lines"]]
+      #
+      # When pulling comments out of a document, comments may be initialized
+      # to the line of the subject and then resolved using the document:
+      #
+      #   document = %Q{
+      #   module Sample
+      #     # this is the content of the comment
+      #     # for method_one
+      #     def method_one
+      #     end
+      #
+      #     # this is the content of the comment
+      #     # for method_two
+      #     def method_two
+      #     end
+      #   end}
+      #
+      #   # resolve will split the document, but 
+      #   # splitting once beforehand is more efficient
+      #   lines = document.split(/\r?\n/)
+      #
+      #   c1 = Comment.new(4).resolve(lines)
+      #   c1.subject     # => "  def method_one"
+      #   c1.content     # => [["this is the content of the comment", "for method_one"]]
+      #
+      #   c2 = Comment.new(9).resolve(lines)
+      #   c2.subject     # => "  def method_two"
+      #   c2.content     # => [["this is the content of the comment", "for method_two"]]
+      #   
+      class Comment
+    
+        class << self
+      
+          # Parses the input string into a comment, stopping at end_regexp
+          # or the first non-comment line.  Also parses the next non-comment
+          # line as the comment subject.  Takes a string or a StringScanner
+          # and returns the new comment.
+          #
+          #   comment_string = %Q{
+          #   # comments spanning multiple
+          #   # lines are collected
+          #   #
+          #   #   while indented lines
+          #   #   are preserved individually
+          #   #    
+          #   this is the subject line
+          #
+          #   # this line is not parsed as it
+          #   # is after a non-comment line
+          #   }
+          #
+          #   c = Comment.parse(comment_string)
+          #   c.content   
+          #   # => [
+          #   # ['comments spanning multiple', 'lines are collected'],
+          #   # [''],
+          #   # ['  while indented lines'],
+          #   # ['  are preserved individually'],
+          #   # [''],
+          #   # []]
+          #   c.subject   # => "this is the subject line"
+          #
+          # Parsing may be manually ended by providing a block; parse yields
+          # each line fragment to the block and stops parsing when the block
+          # returns true.  Note that no subject will be parsed under these
+          # circumstances.
+          #
+          #   c = Comment.parse(comment_string) {|frag| frag.strip.empty? }
+          #   c.content   
+          #   # => [
+          #   # ['comments spanning multiple', 'lines are collected']]
+          #   c.subject   # => nil
+          #
+          # Subject parsing may also be suppressed by setting parse_subject
+          # to false.
+          def parse(str, parse_subject=true) # :yields: fragment
+            scanner = case str
+            when StringScanner then str
+            when String then StringScanner.new(str)
+            else raise TypeError, "can't convert #{str.class} into StringScanner or String"
+            end
+        
+            comment = Comment.new
+            while scanner.scan(/\r?\n?[ \t]*#[ \t]?(([ \t]*).*?)\r?$/)
+              fragment = scanner[1]
+              indent = scanner[2]
+            
+              # collect continuous description line
+              # fragments and join into a single line
+              if block_given? && yield(fragment)
+                # break on comment if the description end is reached
+                parse_subject = false
+                break
+              else
+                categorize(fragment, indent) {|f| comment.push(f) }
+              end
+            end
+        
+            if parse_subject
+              scanner.skip(/\s+/)
+              unless scanner.peek(1) == '#'
+                comment.subject = scanner.scan(/.+?$/) 
+                comment.subject.strip! unless comment.subject == nil
+              end
+            end
+        
+            comment
+          end
+        
+          # Scan determines if and how to add a line fragment to a comment and
+          # yields the appropriate fragments to the block.  Returns true if
+          # fragments are yielded and false otherwise.  A comment's content 
+          # may be built from an array of lines using scan like so:
+          #
+          #   lines = [
+          #     "# comments spanning multiple",
+          #     "# lines are collected",
+          #     "#",
+          #     "#   while indented lines",
+          #     "#   are preserved individually",
+          #     "#    ",
+          #     "not a comment line",
+          #     "# skipped since the loop breaks",
+          #     "# at the first non-comment line"]
+          #
+          #   c = Comment.new
+          #   lines.each do |line|
+          #     break unless Comment.scan(line) do |fragment|
+          #       # c.unshift will also work if building in reverse
+          #       c.push(fragment)  
+          #     end
+          #   end
+          #
+          #   c.content   
+          #   # => [
+          #   # ['comments spanning multiple', 'lines are collected'],
+          #   # [''],
+          #   # ['  while indented lines'],
+          #   # ['  are preserved individually'],
+          #   # [''],
+          #   # []]
+          #
+          def scan(line) # :yields: fragment
+            return false unless line =~ /^[ \t]*#[ \t]?(([ \t]*).*?)\r?$/
+            categorize($1, $2) do |fragment|
+              yield(fragment)
+            end
+            true
+          end
+        
+          # Splits a line of text along whitespace breaks into fragments of cols
+          # width.  Tabs in the line will be expanded into tabsize spaces; 
+          # fragments are rstripped of whitespace.
+          # 
+          #   Comment.wrap("some line that will wrap", 10)       # => ["some line", "that will", "wrap"]
+          #   Comment.wrap("     line that will wrap    ", 10)   # => ["     line", "that will", "wrap"]
+          #   Comment.wrap("                            ", 10)   # => []
+          #
+          # The wrapping algorithm is slightly modified from:
+          # http://blog.macromates.com/2006/wrapping-text-with-regular-expressions/
+          def wrap(line, cols=80, tabsize=2)
+            line = line.gsub(/\t/, " " * tabsize) unless tabsize == nil
+            line.gsub(/(.{1,#{cols}})( +|$\r?\n?)|(.{1,#{cols}})/, "\\1\\3\n").split(/\s*?\n/)
+          end
+        
+          private
+        
+          # utility method used by scan to categorize and yield
+          # the appropriate objects to add the fragment to a
+          # comment
+          def categorize(fragment, indent) # :nodoc:
+             case
+             when fragment == indent
+               # empty comment line
+               yield [""]
+               yield []
+             when indent.empty?
+               # continuation line
+               yield fragment.rstrip
+             else 
+               # indented line
+               yield [fragment.rstrip]
+               yield []
+             end
+           end
+        end
+    
+        # An array of comment fragments organized into 
+        # lines as they would be printed in an output.
+        # Ex: [["fragments", "of line", "one"], 
+        #      ["fragments", "of line", "two"]]
+        attr_reader :content
+    
+        # The subject of the comment (normally set to the next 
+        # non-comment line after the content ends; ie the line 
+        # that would receive the comment in RDoc documentation).
+        attr_accessor :subject
+      
+        # Returns the line number for the subject line, if known.
+        # Although normally an integer, line_number may be
+        # set to a Regexp or Proc to dynamically determine
+        # itself during resolve.
+        attr_accessor :line_number
+      
+        def initialize(line_number=nil)
+          @content = []
+          @subject = nil
+          @line_number = line_number
+        end
+
+        # Pushes the fragment onto the last line array of content.  If the
+        # fragment is an array itself then it will be pushed onto content 
+        # as a new line.
+        #
+        #   c = Comment.new
+        #   c.push "some line"
+        #   c.push "fragments"
+        #   c.push ["a", "whole", "new line"]
+        #
+        #   c.content         
+        #   # => [
+        #   # ["some line", "fragments"], 
+        #   # ["a", "whole", "new line"]]
+        #
+        def push(fragment)
+          content << [] if content.empty?
+        
+          case fragment
+          when Array
+            if content[-1].empty? 
+              content[-1] = fragment
+            else
+              content.push fragment
+            end
+          else
+             content[-1].push fragment
+          end
+        end
+      
+        # Alias for push.
+        def <<(fragment)
+          push(fragment)
+        end
+      
+        # Scans the comment line using Comment.scan and pushes the appropriate
+        # fragments onto self.  Used to build a content by scanning down a set
+        # of lines.
+        #
+        #   lines = [
+        #     "# comment spanning multiple",
+        #     "# lines",
+        #     "#",
+        #     "#   indented line one",
+        #     "#   indented line two",
+        #     "#    ",
+        #     "not a comment line"]
+        #
+        #   c = Comment.new
+        #   lines.each {|line| c.append(line) }
+        #
+        #   c.content 
+        #   # => [
+        #   # ['comment spanning multiple', 'lines'],
+        #   # [''],
+        #   # ['  indented line one'],
+        #   # ['  indented line two'],
+        #   # [''],
+        #   # []]
+        #
+        def append(line)
+          Comment.scan(line) {|f| push(f) }
+        end
+      
+        # Unshifts the fragment to the first line array of content.  If the
+        # fragment is an array itself then it will be unshifted onto content
+        # as a new line.
+        #
+        #   c = Comment.new
+        #   c.unshift "some line"
+        #   c.unshift "fragments"
+        #   c.unshift ["a", "whole", "new line"]
+        #
+        #   c.content         
+        #   # => [
+        #   # ["a", "whole", "new line"], 
+        #   # ["fragments", "some line"]]
+        #
+        def unshift(fragment)
+          content << [] if content.empty?
+        
+          case fragment
+          when Array
+            if content[0].empty? 
+              content[0] = fragment
+            else
+              content.unshift fragment
+            end
+          else
+             content[0].unshift fragment
+          end
+        end
+      
+        # Scans the comment line using Comment.scan and unshifts the appropriate 
+        # fragments onto self.  Used to build a content by scanning up a set of
+        # lines.
+        #
+        #   lines = [
+        #     "# comment spanning multiple",
+        #     "# lines",
+        #     "#",
+        #     "#   indented line one",
+        #     "#   indented line two",
+        #     "#    ",
+        #     "not a comment line"]
+        #
+        #   c = Comment.new
+        #   lines.reverse_each {|line| c.prepend(line) }
+        #
+        #   c.content 
+        #   # => [
+        #   # ['comment spanning multiple', 'lines'],
+        #   # [''],
+        #   # ['  indented line one'],
+        #   # ['  indented line two'],
+        #   # ['']]
+        #
+        def prepend(line)
+          Comment.scan(line) {|f| unshift(f) }
+        end
+      
+        # Builds the subject and content of self using lines; resolve sets
+        # the subject to the line at line_number, and parses content up
+        # from there.  Any previously set subject and content is overridden.  
+        # Returns self.
+        #
+        #   document = %Q{
+        #   module Sample
+        #     # this is the content of the comment
+        #     # for method_one
+        #     def method_one
+        #     end
+        # 
+        #     # this is the content of the comment
+        #     # for method_two
+        #     def method_two
+        #     end
+        #   end}
+        #
+        #   c = Comment.new 4
+        #   c.resolve(document)
+        #   c.subject     # => "  def method_one"
+        #   c.content     # => [["this is the content of the comment", "for method_one"]]
+        #
+        # Notes:
+        # - resolve is a good hook for post-processing in subclasses
+        # - lines may be an array or a string; string inputs are split
+        #   into lines along newline boundaries.
+        #
+        # === late-evaluation line numbers
+        # The line_number used by resolve may be determined directly from
+        # lines by setting line_number to a Regexp and Proc. In the case
+        # of a Regexp, the first line matching the regexp is used:
+        #
+        #   c = Comment.new(/def method/)
+        #   c.resolve(document)
+        #   c.line_number = 4
+        #   c.subject     # => "  def method_one"
+        #   c.content     # => [["this is the content of the comment", "for method_one"]]
+        #
+        # Procs are called with lines and are expected to return the
+        # actual line number.  
+        #
+        #   c = Comment.new lambda {|lines| 9 }
+        #   c.resolve(document)
+        #   c.line_number = 9
+        #   c.subject     # => "  def method_two"
+        #   c.content     # => [["this is the content of the comment", "for method_two"]]
+        #
+        # As shown in the examples, in both cases the late-evaluation 
+        # line_number overwrites the Regexp or Proc.
+        def resolve(lines)
+          lines = lines.split(/\r?\n/) if lines.kind_of?(String)
+        
+          # resolve late-evaluation line numbers
+          n = case line_number
+          when Regexp then match_index(line_number, lines)
+          when Proc then line_number.call(lines)
+          else line_number
+          end
+         
+          # quietly exit if a line number was not found
+          return self unless n.kind_of?(Integer)
+          
+          unless n < lines.length
+            raise RangeError, "line_number outside of lines: #{line_number} (#{lines.length})"
+          end
+        
+          self.line_number = n
+          self.subject = lines[n]
+          self.content.clear
+        
+          # remove whitespace lines
+          n -= 1
+          n -= 1 while n >=0 && lines[n].strip.empty?
+
+          # put together the comment
+          while n >= 0
+            break unless prepend(lines[n])
+            n -= 1
+          end
+         
+          self
+        end
+      
+        # Removes leading and trailing lines from content that are
+        # empty ([]) or whitespace (['']).  Returns self.
+        def trim
+          content.shift while !content.empty? && (content[0].empty? || content[0].join.strip.empty?)
+          content.pop   while !content.empty? && (content[-1].empty? || content[-1].join.strip.empty?)
+          self
+        end
+      
+        # True if all lines in content are empty.
+        def empty?
+          !content.find {|line| !line.empty?}
+        end
+      
+        # Returns content as a string where line fragments are joined by
+        # fragment_sep and lines are joined by line_sep. 
+        def to_s(fragment_sep=" ", line_sep="\n", strip=true)
+          lines = content.collect {|line| line.join(fragment_sep)}
+        
+          # strip leading an trailing whitespace lines
+          if strip
+            lines.shift while !lines.empty? && lines[0].empty?
+            lines.pop while !lines.empty? && lines[-1].empty?
+          end
+        
+          line_sep ? lines.join(line_sep) : lines
+        end
+      
+        # Like to_s, but wraps the content to the specified number of cols
+        # and expands tabs to tabsize spaces.
+        def wrap(cols=80, tabsize=2, line_sep="\n", fragment_sep=" ", strip=true)
+          lines = Comment.wrap(to_s(fragment_sep, "\n", strip), cols, tabsize)
+          line_sep ? lines.join(line_sep) : lines
+        end
+      
+        # Returns true if another is a Comment with the same
+        # line_number, subject, and content as self
+        def ==(another)
+          another.kind_of?(Comment) && 
+          self.line_number == another.line_number &&
+          self.subject == another.subject &&
+          self.content == another.content
+        end
+      
+        private
+      
+        # utility method used to by resolve to find the index
+        # of a line matching a regexp line_number.
+        def match_index(regexp, lines) # :nodoc:
+          lines.each_with_index do |line, index|
+            return index if line =~ regexp
+          end
+          nil
+        end
+      end
+    end
+  end
+end