lazydoc 0.1.0 → 0.2.0

data/README

@@ -63,7 +63,7 @@ Lazydoc::Comment.
   # constant attribute, or an end
   # key
   # ..............................
-  #}
+  # }
 
 In addition, individual lines of code may be registered and resolved by Lazydoc:
 
@@ -73,11 +73,46 @@ In addition, individual lines of code may be registered and resolved by Lazydoc:
   doc.resolve
   comment.subject       # => "  def method_one"
   comment.content       # => [["comment content for a code comment", "may similarly span multiple lines"]]
+  
+A variety of helper methods exist to register methods, in particular:
+
+  class Helpers
+    extend Lazydoc::Attributes
+    
+    register_method___
+    # method_one was registered by the
+    # helper
+    def method_one(a, b='str', &c)
+    end
+    
+    # method_two illustrates registration
+    # of the line that *calls* method_two
+    def method_two
+      Lazydoc.register_caller
+    end
+  end
+  
+  # *THIS* is the line that gets registered
+  # by method_two
+  Helpers.new.method_two
+  
+  doc = Helpers.lazydoc
+  doc.resolve
+  
+  m1 = doc.comments[0]
+  m1.method_name        # => "method_one"
+  m1.arguments          # => ["a", "b='str'", "&c"]
+  m1.to_s               # => "method_one was registered by the helper"
+  
+  comment = doc.comments[1]
+  comment.subject       # => "Helpers.new.method_two"
+  comment.to_s          # => "*THIS* is the line that gets registered by method_two"
 
 Check out these links for development, and bug tracking.
 
 * Website[http://tap.rubyforge.org/lazydoc]
 * Github[http://github.com/bahuvrihi/lazydoc/tree/master]
+* Lighthouse[http://bahuvrihi.lighthouseapp.com/projects/19948-lazydoc/tickets?q=all]
 * {Google Group}[http://groups.google.com/group/ruby-on-tap]
 
 == Usage

data/lib/lazydoc/attributes.rb

@@ -1,24 +1,30 @@
+require 'lazydoc'
+
 module Lazydoc
-  # Attributes adds methods to declare class-level accessors
-  # for Lazydoc attributes.  The source_file for the class must
-  # be set manually.
+  # Attributes adds methods to declare class-level accessors for Lazydoc 
+  # attributes.
   #
   #   # ConstName::key value
   #   class ConstName
-  #     class << self
-  #       include Lazydoc::Attributes
-  #     end
+  #     extend Lazydoc::Attributes
   #
-  #     self.source_file = __FILE__
   #     lazy_attr :key
   #   end
   #
+  #   ConstName.source_file            # =>  __FILE__
   #   ConstName::key.subject           # => 'value'
   # 
   module Attributes
 
-    # The source_file for self.  Must be set independently.
+    # The source_file for self.  By default set to the file where
+    # Attributes extends a class (if you include Attributes, you
+    # must set source_file manually).
     attr_accessor :source_file
+    
+    def self.extended(base) # :nodoc:
+      caller[1] =~ CALLER_REGEXP
+      base.source_file ||= $1
+    end
 
     # Returns the lazydoc for source_file
     def lazydoc(resolve=true)
@@ -37,6 +43,11 @@ end
 def #{key}=(comment)
   Lazydoc[source_file][to_s]['#{attribute}'] = comment
 end}
-    end 
+    end
+    
+    # Registers the next method.
+    def register_method___(comment_class=Method)
+      lazydoc(false).register___(comment_class, 1)
+    end
   end
 end

data/lib/lazydoc/comment.rb

@@ -105,7 +105,7 @@ module Lazydoc
         else raise TypeError, "can't convert #{str.class} into StringScanner or String"
         end
     
-        comment = Comment.new
+        comment = self.new
         while scanner.scan(/\r?\n?[ \t]*#[ \t]?(([ \t]*).*?)\r?$/)
           fragment = scanner[1]
           indent = scanner[2]
@@ -124,8 +124,10 @@ module Lazydoc
         if parse_subject
           scanner.skip(/\s+/)
           unless scanner.peek(1) == '#'
-            comment.subject = scanner.scan(/.+?$/) 
-            comment.subject.strip! unless comment.subject == nil
+            if subject = scanner.scan(/.+?$/) 
+              subject.strip!
+            end
+            comment.subject = subject
           end
         end
     
@@ -172,7 +174,40 @@ module Lazydoc
         end
         true
       end
-    
+      
+      # Scans a stripped trailing comment off of str, tolerant to a leader
+      # that uses '#' within a string.  Returns nil for strings without a 
+      # trailing comment.
+      #
+      #   Comment.scan_trailer "str with # trailer"           # => "trailer"
+      #   Comment.scan_trailer "'# in str' # trailer"         # => "trailer"
+      #   Comment.scan_trailer "str with without trailer"     # => nil
+      # 
+      # Note the %-syntax for strings is not fully supported, ie %Q, %q,
+      # etc. may not parse correctly.  Accepts Strings or a StringScanner.
+      def scan_trailer(str)
+        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
+
+        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.
@@ -208,6 +243,13 @@ module Lazydoc
           yield []
         end
       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
     end
 
     # An array of comment fragments organized into lines
@@ -421,10 +463,12 @@ module Lazydoc
       # quietly exit if a line number was not found
       return self unless n.kind_of?(Integer)
       
+      # update negative line numbers
+      n += lines.length if n < 0
       unless n < lines.length
-        raise RangeError, "line_number outside of lines: #{line_number} (#{lines.length})"
+        raise RangeError, "line_number outside of lines: #{n} (#{lines.length})"
       end
-    
+      
       self.line_number = n
       self.subject = lines[n]
       self.content.clear
@@ -455,6 +499,11 @@ module Lazydoc
       !content.find {|line| !line.empty?}
     end
   
+    # Returns a comment trailing the subject.
+    def trailer
+      subject ? Comment.scan_trailer(subject) : nil
+    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)

data/lib/lazydoc/document.rb

@@ -1,4 +1,5 @@
 require 'lazydoc/comment'
+require 'lazydoc/method'
 
 module Lazydoc
   
@@ -100,12 +101,36 @@ module Lazydoc
       comment
     end
     
-    # Registers a regexp matching methods by the specified
-    # name.
-    def register_method(method, comment_class=Comment)
-      register(/^\s*def\s+#{method}(\W|$)/, comment_class)
+    # Registers a regexp matching the first method by the specified name.
+    def register_method(method_name, comment_class=Method)
+      register(Method.method_regexp(method_name), comment_class)
     end
-  
+    
+    # Registers the next comment.
+    #
+    #   lazydoc = Document.new(__FILE__)
+    #
+    #   lazydoc.register___
+    #   # this is the comment
+    #   # that is registered
+    #   def method(a,b,c)
+    #   end
+    #
+    #   lazydoc.resolve
+    #   m = lazydoc.comments[0]
+    #   m.subject      # => "def method(a,b,c)"
+    #   m.to_s         # => "this is the comment that is registered"
+    #
+    def register___(comment_class=Comment, caller_index=0)
+      caller[caller_index] =~ CALLER_REGEXP
+      block = lambda do |lines|
+        n = $3.to_i
+        n += 1 while lines[n] =~ /^\s*(#.*)?$/
+        n
+      end
+      register(block, comment_class)
+    end
+      
     # Scans str for constant attributes and adds them to to self.  Code
     # comments are also resolved against str.  If no str is specified,
     # the contents of source_file are used instead.

data/lib/lazydoc/method.rb

@@ -0,0 +1,128 @@
+module Lazydoc
+  
+  # Method represents a code comment for a standard method definition.
+  # Methods give access to the method name, the arguments, and the 
+  # trailing comment, if present.
+  #
+  #   sample_method = %Q{
+  #   # This is the comment body
+  #   def method_name(a, b='default', &c) # trailing comment
+  #   end
+  #   }
+  #
+  #   m = Method.parse(sample_method)
+  #   m.method_name          # => "method_name"
+  #   m.arguments            # => ["a", "b='default'", "&c"]
+  #   m.trailer              # => "trailing comment"
+  #   m.to_s                 # => "This is the comment body"
+  #
+  class Method < Comment
+    class << self
+      
+      # Generates a regexp matching a standard definition of the
+      # specified method.
+      #
+      #   m = Method.method_regexp("method")
+      #   m =~ "def method"                       # => true
+      #   m =~ "def method(with, args, &block)"   # => true
+      #   m !~ "def some_other_method"            # => true
+      #
+      def method_regexp(method_name)
+        /^\s*def\s+#{method_name}(\W|$)/
+      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.
+      #
+      #   Method.parse_args("(a, b='default', &block)")  
+      #   # => ["a", "b='default'", "&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.
+      def parse_args(str)
+        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
+        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
+
+        args
+      end
+    end
+    
+    # Matches a standard method definition.  After the match:
+    #
+    #   $1:: the method name
+    #   $2:: the argument string, which may be parsed by parse_args
+    #
+    METHOD_DEF = /^\s*def (\w+)(.*)$/
+    
+    # The resolved method name
+    attr_reader :method_name
+    
+    # An array of the resolved arguments for the method
+    attr_reader :arguments
+    
+    def initialize(*args)
+      super
+      @method_name = nil
+      @arguments = []
+    end
+    
+    # Overridden to parse and set the method_name, arguments, and 
+    # trailer in addition to setting the subject.
+    def subject=(value)
+      unless value =~ METHOD_DEF
+        raise ArgumentError, "not a method definition: #{value}"
+      end
+      
+      @method_name = $1
+      @arguments = Method.parse_args($2)
+  
+      super
+    end
+  end
+end

data/lib/lazydoc.rb

@@ -49,6 +49,26 @@ module Lazydoc
     Lazydoc[source_file].register(line_number, comment_class)
   end
   
+  # Registers the method at the specified index in the call stack, to
+  # the file where the method was called.  Using the default index of
+  # 1, register_caller registers the caller of the method where 
+  # register_caller is called.  For instance:
+  #
+  #   module Sample
+  #     module_function
+  #     def method
+  #       Lazydoc.register_caller
+  #     end
+  #   end
+  #
+  #   # this is the line that gets registered
+  #   Sample.method
+  #
+  def register_caller(comment_class=Comment, caller_index=1)
+    caller[caller_index] =~ CALLER_REGEXP
+    Lazydoc[$1].register($3.to_i - 1, comment_class)
+  end
+  
   # Resolves all lazydocs which include the specified code comments.
   def resolve_comments(comments)
     registry.each do |doc|
@@ -172,6 +192,8 @@ module Lazydoc
     end
   end
   
+  # Parses the usage for a file, ie the first comment in the file 
+  # following an optional bang line.
   def usage(path, cols=80)
     scanner = StringScanner.new(File.read(path))
     scanner.scan(/^#!.*?$/)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: lazydoc
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Simon Chiang
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-11-12 00:00:00 -07:00
+date: 2008-12-07 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -36,6 +36,7 @@ files:
 - lib/lazydoc/attributes.rb
 - lib/lazydoc/comment.rb
 - lib/lazydoc/document.rb
+- lib/lazydoc/method.rb
 - README
 - MIT-LICENSE
 has_rdoc: true
@@ -60,9 +61,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: tap
-rubygems_version: 1.2.0
+rubygems_version: 1.3.1
 signing_key: 
 specification_version: 2
-summary: lazydoc
+summary: Lazily pull documentation out of source files.
 test_files: []