lazydoc 0.2.0 → 0.3.0

data/lib/lazydoc/trailer.rb

@@ -0,0 +1,19 @@
+module Lazydoc
+  
+  # A special type of self-resolving Comment that whose to_s returns the
+  # trailer, or an empty string if trailer is nil.
+  #
+  #   t = Trailer.new
+  #   t.subject = "def method  # trailer string"
+  #   t.to_s               # => "trailer string"
+  #
+  class Trailer < Comment
+    
+    # Self-resolves and returns trailer, or an empty 
+    # string if trailer is nil.
+    def to_s
+      resolve
+      trailer.to_s
+    end
+  end
+end

data/lib/lazydoc/utils.rb

@@ -0,0 +1,232 @@
+require 'strscan'
+
+module Lazydoc
+  
+  # A number of utility methods used by Comment, factored out for
+  # testing and re-use.
+  module Utils
+    module_function
+    
+    def split_lines(str)
+      (str.empty? ? [""] : str.split(/\r?\n/))
+    end
+    
+    # Converts str to a StringScanner (or returns str if it already is
+    # a StringScanner).  Raises a TypeError if str is not a String
+    # or a StringScanner.
+    def convert_to_scanner(str)
+      case str
+      when String then StringScanner.new(str)
+      when StringScanner then str
+      else raise TypeError, "can't convert #{str.class} into StringScanner"
+      end
+    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.  
+    #
+    # 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 Utils.scan(line) do |fragment|
+    #       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
+    
+    # Parses an argument string (anything following the method name in a
+    # standard method definition, including parenthesis, comments, default
+    # values, etc) into an array of strings.
+    #
+    #   Utils.parse_args("(a, b='default', *c, &block)")  
+    #   # => ["a", "b='default'", "*c", "&block"]
+    #
+    # Note the %-syntax for strings and arrays is not fully supported,
+    # ie %w, %Q, %q, etc. may not parse correctly.  The same is true
+    # for multiline argument strings.
+    #
+    # Accepts a String or a StringScanner.
+    def scan_args(str)
+      scanner = convert_to_scanner(str)
+      str = scanner.string
+      
+      # skip whitespace and leading LPAREN
+      scanner.skip(/\s*\(?\s*/) 
+      
+      args = []
+      brakets = braces = parens = 0
+      start = scanner.pos
+      broke = while scanner.skip(/.*?['"#,\(\)\{\}\[\]]/)
+        pos = scanner.pos - 1
+        
+        case str[pos]
+        when ?,,nil
+          # skip if in brakets, braces, or parenthesis
+          next if parens > 0 || brakets > 0 || braces > 0
+          
+          # ok, found an arg
+          args << str[start, pos-start].strip
+          start = pos + 1
+        
+        when ?# then break(true)                # break on a comment
+        when ?' then skip_quote(scanner, /'/)   # parse over quoted strings
+        when ?" then skip_quote(scanner, /"/)   # parse over double-quoted string
+          
+        when ?( then parens += 1                # for brakets, braces, and parenthesis
+        when ?)                                 # simply track the nesting EXCEPT for
+          break(true) if parens == 0            # RPAREN.  If the closing parenthesis
+          parens -= 1                           # is found, break.
+        when ?[ then braces += 1
+        when ?] then braces -= 1
+        when ?{ then brakets += 1
+        when ?} then brakets -= 1
+        end
+      end
+      
+      # parse out the final arg.  if the loop broke (ie 
+      # a comment or the closing parenthesis was found) 
+      # then the end position is determined by the 
+      # scanner, otherwise take all that remains
+      pos = broke ? scanner.pos-1 : str.length
+      args << str[start, pos-start].strip unless pos == start
+
+      args
+    end
+    
+    # Scans a stripped trailing comment off the input.  Returns nil for 
+    # strings without a trailing comment.
+    #
+    #   Utils.scan_trailer "str with # trailer"           # => "trailer"
+    #   Utils.scan_trailer "'# in str' # trailer"         # => "trailer"
+    #   Utils.scan_trailer "str with without trailer"     # => nil
+    # 
+    # Note the %Q and %q syntax for defining strings is not supported
+    # within the leader and may not parse correctly:
+    #
+    #   Utils.scan_trailer "%Q{# in str} # trailer"       # => "in str} # trailer"
+    #
+    # Accepts a String or a StringScanner.
+    def scan_trailer(str)
+      scanner = convert_to_scanner(str)
+
+      args = []
+      brakets = braces = parens = 0
+      start = scanner.pos
+      while scanner.skip(/.*?['"#]/)
+        pos = scanner.pos - 1
+        
+        case str[pos]
+        when ?# then return scanner.rest.strip     # return the trailer
+        when ?' then skip_quote(scanner, /'/)      # parse over quoted strings
+        when ?" then skip_quote(scanner, /"/)      # parse over double-quoted string
+        end
+      end
+      
+      return nil
+    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.
+    # 
+    #   Utils.wrap("some line that will wrap", 10)       # => ["some line", "that will", "wrap"]
+    #   Utils.wrap("     line that will wrap    ", 10)   # => ["     line", "that will", "wrap"]
+    #   Utils.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
+    
+    # Returns the line at which scanner currently resides.  The position
+    # of scanner is not modified.
+    def determine_line_number(scanner)
+      scanner.string[0, scanner.pos].count("\n")
+    end
+    
+    # Returns the index of the line where scanner ends up after the first
+    # match to regexp (starting at position 0).  The existing position of
+    # scanner is not modified by this method.  Returns nil if the scanner
+    # cannot match regexp.
+    #
+    #   scanner = StringScanner.new %Q{zero\none\ntwo\nthree}
+    #   Utils.scan_index(scanner, /two/)         # => 2
+    #   Utils.scan_index(scanner, /no match/)    # => nil
+    #
+    def scan_index(scanner, regexp)
+      pos = scanner.pos
+      scanner.pos = 0
+      n = scanner.skip_until(regexp) ? determine_line_number(scanner) : nil
+      scanner.pos = pos
+      n
+    end
+    
+    # Returns the index of the line in lines matching regexp,
+    # or nil if no line matches regexp.
+    def match_index(lines, regexp)
+      index = 0
+      lines.each do |line|
+        return index if line =~ regexp
+        index += 1
+      end
+      nil
+    end
+    
+    # helper method to skip to the next non-escaped instance
+    # matching the quote regexp (/'/ or /"/).
+    def skip_quote(scanner, regexp) # :nodoc:
+      scanner.skip_until(regexp)
+      scanner.skip_until(regexp) while scanner.string[scanner.pos-2] == ?\\
+    end
+    
+    # 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
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: lazydoc
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Simon Chiang
@@ -9,19 +9,10 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-12-07 00:00:00 -07:00
+date: 2008-12-31 00:00:00 -07:00
 default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: tap
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: 0.11.1
-    version: 
+dependencies: []
+
 description: 
 email: simon.a.chiang@gmail.com
 executables: []
@@ -33,17 +24,26 @@ extra_rdoc_files:
 - MIT-LICENSE
 files: 
 - lib/lazydoc.rb
+- lib/lazydoc/arguments.rb
 - lib/lazydoc/attributes.rb
 - lib/lazydoc/comment.rb
 - lib/lazydoc/document.rb
 - lib/lazydoc/method.rb
+- lib/lazydoc/subject.rb
+- lib/lazydoc/trailer.rb
+- lib/lazydoc/utils.rb
 - README
 - MIT-LICENSE
 has_rdoc: true
 homepage: http://tap.rubyforge.org/lazydoc
 post_install_message: 
-rdoc_options: []
-
+rdoc_options: 
+- --title
+- Lazydoc
+- --main
+- README
+- --line-numbers
+- --inline-source
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement