lazydoc 0.2.0 → 0.3.0

data/README

@@ -6,107 +6,80 @@ Tap[http://tap.rubyforge.org] framework.
 
 == Description
 
-Lazydoc can find two types of documentation: constant attributes and 
-code comments.  To illustrate, consider the following:
+Lazydoc allows you to define lazy attributes that act as markers for
+documentation in a source file.  When you call the lazy attribute,
+Lazydoc pulls out the documentation:
 
   # Sample::key <value>
   # This is the comment content.  A content
   # string can span multiple lines...
-  #
-  #   code.is_allowed
-  #   much.as_in RDoc
-  #
-  # and stops at the next non-comment
-  # line, the next constant attribute,
-  # or an end key
   class Sample
     extend Lazydoc::Attributes
-    self.source_file = __FILE__
-
     lazy_attr :key
-
-    # comment content for a code comment
-    # may similarly span multiple lines
-    def method_one
-    end
   end
-
-When a lazy attribute is called, Lazydoc scans <tt>source_file</tt> for
-the corresponding constant attribute and makes it available as a
-Lazydoc::Comment.
-
+  
   comment = Sample::key
-  comment.value       
-  # => "<value>"
+  comment.value      # => "<value>"
+  comment.comment    # => "This is the comment content.  A content string can span multiple lines..."
 
-  comment.content       
-  # => [
-  # ["This is the comment content.  A content", "string can span multiple lines..."],
-  # [""],
-  # ["  code.is_allowed"],
-  # ["  much.as_in RDoc"],
-  # [""],
-  # ["and stops at the next non-comment", "line, the next constant attribute,", "or an end key"]]
-
-  "\n#{'.' * 30}\n" + comment.wrap(30) + "\n#{'.' * 30}\n"
+Comments support wrapping, allowing for easy presentation:
+
+  thirtydots = "\n#{'.' * 30}\n"
+  
+  "#{thirtydots}#{comment.wrap(30)}#{thirtydots}"
   # => %q{
   # ..............................
   # This is the comment content.
   # A content string can span
   # multiple lines...
-  # 
-  #   code.is_allowed
-  #   much.as_in RDoc
-  # 
-  # and stops at the next
-  # non-comment line, the next
-  # constant attribute, or an end
-  # key
   # ..............................
   # }
 
-In addition, individual lines of code may be registered and resolved by Lazydoc:
-
-  doc = Sample.lazydoc.reset
-  comment = doc.register(/method_one/)
-  
-  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:
+In addition, Lazydoc provides helpers to register individual lines of code, 
+particularly method definitions:
 
   class Helpers
     extend Lazydoc::Attributes
     
-    register_method___
-    # method_one was registered by the
-    # helper
+    lazy_register(:method_one)
+    
+    # method_one is registered whenever it 
+    # gets defined
     def method_one(a, b='str', &c)
     end
     
-    # method_two illustrates registration
-    # of the line that *calls* method_two
+    # register_caller will register 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
+  # *THIS* is the line that gets
+  # registered by method_two
+  Helpers.const_attrs[: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"
+  one = Helpers.const_attrs[:method_one]
+  one.method_name            # => "method_one"
+  one.arguments              # => ["a", "b='str'", "&c"]
+  one.to_s                   # => "method_one is registered whenever it gets defined"
   
-  comment = doc.comments[1]
-  comment.subject       # => "Helpers.new.method_two"
-  comment.to_s          # => "*THIS* is the line that gets registered by method_two"
+  two = Helpers.const_attrs[:method_two]
+  two.subject                # => "Helpers.const_attrs[:method_two] = Helpers.new.method_two"
+  two.to_s                   # => "*THIS* is the line that gets registered by method_two"
+
+Lazy accessors may be defined to map the registered lines as well:
+
+  class Helpers
+    lazy_attr(:one, :method_one)
+    lazy_attr(:two, :method_two)
+  end
+  
+  Helpers.one.method_name    # => "method_one"
+  Helpers.two.subject        # => "Helpers.const_attrs[:method_two] = Helpers.new.method_two"
 
 Check out these links for development, and bug tracking.
 
@@ -117,6 +90,10 @@ Check out these links for development, and bug tracking.
 
 == Usage
 
+Lazydoc can find two types of documentation, constant attributes and code
+comments.  The distinction is primarily how they are found and parsed; both
+are represented by Comment objects.
+
 === Constant Attributes
 
 Constant attributes are like constants in Ruby, but with an extra 'key' 
@@ -134,8 +111,8 @@ While these are not:
   # Const::Name::k@y
 
 Lazydoc parses a Lazydoc::Comment for each constant attribute by using the 
-remainder of the line as a value (ie subject) and scanning down for content.
-Scanning continues until a non-comment line, an end key, or a new attribute
+remainder of the line as a value (ie subject) and parsing down for content.
+Parsing continues until a non-comment line, an end key, or a new attribute
 is reached; the comment is then stored by constant name and key.
 
   str = %Q{
@@ -155,7 +132,7 @@ is reached; the comment is then stored by constant name and key.
   doc = Lazydoc::Document.new
   doc.resolve(str)
 
-  doc.to_hash {|comment| [comment.value, comment.to_s] } 
+  doc.summarize {|c| [c.value, c.comment] } 
   # => {
   # 'Const::Name' => {
   #   'key' =>     ['value for key', 'comment for key parsed until a non-comment line'],
@@ -176,7 +153,7 @@ attribute parsing for a section of documentation, use start/stop keys:
 
   doc = Lazydoc::Document.new
   doc.resolve(str)
-  doc.to_hash {|comment| comment.value }   # => {'Const::Name' => {'parsed' => 'value'}}
+  doc.summarize {|comment| comment.value }   # => {'Const::Name' => {'parsed' => 'value'}}
 
 To hide attributes from RDoc, make use of the RDoc <tt>:startdoc:</tt> 
 document modifier like this (note that spaces are added to prevent RDoc
@@ -194,10 +171,9 @@ from hiding the example):
   #
   # * This line is also visible in RDoc.
 
-As a side note, <tt>Const::Name::key</tt> is not a reference to the 'key' 
-constant (as that would be invalid).  In *very* idiomatic ruby
-<tt>Const::Name::key</tt> is equivalent to the method call 
-<tt>Const::Name.key</tt>.
+As a side note, 'Const::Name::key' is not a reference to the 'key' 
+constant (that would be invalid).  In *very* idiomatic ruby
+'Const::Name::key' is equivalent to the method call 'Const::Name.key'.
 
 === Code Comments
 
@@ -224,7 +200,7 @@ the behavior of RDoc).
   doc.register(9)
   doc.resolve(str)
 
-  doc.comments.collect {|comment| [comment.subject, comment.to_s] } 
+  doc.comments.collect {|c| [c.subject, c.comment] } 
   # => [
   # ['def method', 'comment lines for the method'],
   # ['def another_method', 'as in RDoc, the comment can be separated from the method']]
@@ -233,7 +209,7 @@ Comments may be registered to specific line numbers, or with a Proc or
 Regexp that will determine the line number during resolution.  In the case
 of a Regexp, the first matching line is used; Procs receive an array of
 lines and should return the line number that should be used.  See 
-Lazydoc::Comment#resolve for more details.
+{Comment#parse_up}[link://classes/Lazydoc/Comment.html] for more details.
 
 == Installation
 

data/lib/lazydoc.rb

@@ -1,58 +1,50 @@
 require 'lazydoc/document'
 
 module Lazydoc
-  autoload(:Attributes, 'lazydoc/attributes')
-  
-  # A regexp matching an attribute start or end.  After a match:
-  #
-  # $1:: const_name
-  # $3:: key
-  # $4:: end flag
-  #
-  ATTRIBUTE_REGEXP = /([A-Z][A-z]*(::[A-Z][A-z]*)*)?::([a-z_]+)(-?)/
-
-  # A regexp matching constants from the ATTRIBUTE_REGEXP leader
-  CONSTANT_REGEXP = /#.*?([A-Z][A-z]*(::[A-Z][A-z]*)*)?$/
-  
-  # A regexp matching a caller line, to extract the calling file
-  # and line number.  After a match:
-  #
-  # $1:: file
-  # $3:: line number (as a string, obviously)
-  #
-  # Note that line numbers in caller start at 1, not 0.
-  CALLER_REGEXP = /^(([A-z]:)?[^:]+):(\d+)/
-  
   module_function
   
-  # A hash of (source_file, lazydoc) pairs tracking the
-  # Lazydoc instance for the given source file.
+  # An array of documents registered with Lazydoc.
   def registry
     @registry ||= []
   end
   
-  # Returns the lazydoc in registry for the specified source file.
-  # If no such lazydoc exists, one will be created for it.
+  # Returns the Document in registry for the specified source file.
+  # If no such Document exists, one will be created for it.
   def [](source_file)
+    source_file = File.expand_path(source_file.to_s)
+    registry.find {|doc| doc.source_file == source_file } || register_file(source_file)
+  end
+  
+  # Generates a Document the source_file and default_const_name and adds it to
+  # registry, or returns the document already registered to source_file.  An
+  # error is raised if you try to re-register a source_file with an inconsistent
+  # default_const_name.
+  def register_file(source_file, default_const_name=nil)
     source_file = File.expand_path(source_file.to_s)
     lazydoc = registry.find {|doc| doc.source_file == source_file }
-    if lazydoc == nil
-      lazydoc = Document.new(source_file)
+    
+    unless lazydoc
+      lazydoc = Document.new(source_file, default_const_name)
       registry << lazydoc
     end
+    
+    if lazydoc.default_const_name != default_const_name
+      raise ArgumentError, "inconsistent default_const_name specified for #{source_file}: #{lazydoc.default_const_name.inspect} != #{default_const_name.inspect}"
+    end
+    
     lazydoc
   end
 
-  # Register the specified line numbers to the lazydoc for source_file.
-  # Returns a comment_class instance corresponding to the line.
+  # Registers the line number to the document for source_file and
+  # returns the corresponding comment.
   def register(source_file, line_number, comment_class=Comment)
     Lazydoc[source_file].register(line_number, comment_class)
   end
   
-  # Registers the method at the specified index in the call stack, to
+  # 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:
+  # register_caller is called (whew!).  For instance:
   #
   #   module Sample
   #     module_function
@@ -62,141 +54,42 @@ module Lazydoc
   #   end
   #
   #   # this is the line that gets registered
-  #   Sample.method
+  #   c = Sample.method
+  #
+  #   c.resolve
+  #   c.subject   # => "c = Sample.method"
+  #   c.comment   # => "this is the line that gets registered"
   #
   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|
-      next if (comments & doc.comments).empty?
-      doc.resolve
-    end
-  end
-  
-  # Scans the specified file for attributes keyed by key and stores 
-  # the resulting comments in the source_file lazydoc. Returns the
-  # lazydoc.
-  def scan_doc(source_file, key)
-    lazydoc = nil
-    scan(File.read(source_file), key) do |const_name, attr_key, comment|
-      lazydoc = self[source_file] unless lazydoc
-      lazydoc[const_name][attr_key] = comment
-    end
-    lazydoc
-  end
-  
-  # Scans the string or StringScanner for attributes matching the key
-  # (keys may be patterns, they are incorporated into a regexp). Yields 
-  # each (const_name, key, value) triplet to the mandatory block and
-  # skips regions delimited by the stop and start keys <tt>:-</tt> 
-  # and <tt>:+</tt>.
-  #
-  #   str = %Q{
-  #   # Const::Name::key value
-  #   # ::alt alt_value
+  # Parses the usage for a file (ie the first comment in the file 
+  # following an optional bang line), wrapped to n cols.  For 
+  # example, with this:
+  #
+  #   [hello_world.rb]
+  #   #!/usr/bin/env ruby
+  #   # This is your basic hello world
+  #   # script:
   #   #
-  #   # Ignored::Attribute::not_matched value
-  #   # :::-
-  #   # Also::Ignored::key value
-  #   # :::+
-  #   # Another::key another value
-  #
-  #   Ignored::key value
-  #   }
-  #
-  #   results = []
-  #   Lazydoc.scan(str, 'key|alt') do |const_name, key, value|
-  #     results << [const_name, key, value]
-  #   end
-  #
-  #   results    
-  #   # => [
-  #   # ['Const::Name', 'key', 'value'], 
-  #   # ['', 'alt', 'alt_value'], 
-  #   # ['Another', 'key', 'another value']]
-  #
-  # Returns the StringScanner used during scanning.
-  def scan(str, key) # :yields: const_name, key, value
-    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
-
-    regexp = /^(.*?)::(:-|#{key})/
-    while !scanner.eos?
-      break if scanner.skip_until(regexp) == nil
-
-      if scanner[2] == ":-"
-        scanner.skip_until(/:::\+/)
-      else
-        next unless scanner[1] =~ CONSTANT_REGEXP
-        key = scanner[2]
-        yield($1.to_s, key, scanner.matched.strip) if scanner.scan(/[ \r\t].*$|$/)
-      end
-    end
-  
-    scanner
-  end
-
-  # Parses constant attributes from the string or StringScanner.  Yields 
-  # each (const_name, key, comment) triplet to the mandatory block 
-  # and skips regions delimited by the stop and start keys <tt>:-</tt> 
-  # and <tt>:+</tt>.
-  #
-  #   str = %Q{
-  #   # Const::Name::key subject for key
-  #   # comment for key
+  #   #   % ruby hello_world.rb
   #
-  #   # :::-
-  #   # Ignored::key value
-  #   # :::+
+  #   puts 'hello world'
   #
-  #   # Ignored text before attribute ::another subject for another
-  #   # comment for another
-  #   }
+  # You get this:
   #
-  #   results = []
-  #   Lazydoc.parse(str) do |const_name, key, comment|
-  #     results << [const_name, key, comment.subject, comment.to_s]
-  #   end
-  #
-  #   results    
-  #   # => [
-  #   # ['Const::Name', 'key', 'subject for key', 'comment for key'], 
-  #   # ['', 'another', 'subject for another', 'comment for another']]
+  #   "\n" + Lazydoc.usage('hello_world.rb')  
+  #   # => %Q{
+  #   # This is your basic hello world script:
+  #   #
+  #   #   % ruby hello_world.rb}
   #
-  # Returns the StringScanner used during scanning.
-  def parse(str) # :yields: const_name, key, comment
-    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
-    
-    scan(scanner, '[a-z_]+') do |const_name, key, value|
-      comment = Comment.parse(scanner, false) do |line|
-        if line =~ ATTRIBUTE_REGEXP
-          # rewind to capture the next attribute unless an end is specified.
-          scanner.unscan unless $4 == '-' && $3 == key && $1.to_s == const_name
-          true
-        else false
-        end
-      end
-      comment.subject = value
-      yield(const_name, key, comment)
-    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(/^#!.*?$/)
-    Comment.parse(scanner, false).wrap(cols, 2).strip
+    scanner.scan(/#!.*?\r?\n/)
+    scanner.scan(/\s*#/m)
+    Comment.new.parse_down(scanner, nil, false).wrap(cols, 2).strip
   end
 end