tap 0.9.1 → 0.10.0

data/lib/tap/support/framework.rb

@@ -0,0 +1,71 @@
+require 'tap/support/batchable'
+require 'tap/support/executable'
+require 'tap/support/framework_class'
+
+module Tap
+  module Support
+    
+    # Framework encapsulates the basic framework functionality (batching,
+    # configuration, documentation, etc) used by Task and Workflow. Note 
+    # that Framework does NOT encapsulate the functionality needed to
+    # make a class useful in workflows, such as enq and on_complete.
+    module Framework
+      include Batchable
+      include Configurable
+    
+      def self.included(mod)
+        mod.extend Support::BatchableClass
+        mod.extend Support::ConfigurableClass
+        mod.extend Support::FrameworkClass
+      end
+    
+      # The application used to load config_file templates 
+      # (and hence, to initialize batched objects).
+      attr_reader :app
+      
+      # The name of self.
+      attr_accessor :name
+      
+      # Initializes a new instance and associated batch objects.  Batch
+      # objects will be initialized for each configuration template 
+      # specified by app.each_config_template(config_file) where 
+      # config_file = app.config_filepath(name).  
+      def initialize(config={}, name=nil, app=App.instance)
+        super()
+        @app = app
+        @name = name || self.class.default_name
+        initialize_config(config)
+      end
+      
+      # Creates a new batched object and adds the object to batch. The batched object 
+      # will be a duplicate of the current object but with a new name and/or 
+      # configurations.
+      def initialize_batch_obj(overrides={}, name=nil)
+        obj = super().reconfigure(overrides)
+        obj.name = name if name
+        obj 
+      end
+      
+      # Logs the inputs to the application logger (via app.log)
+      def log(action, msg="", level=Logger::INFO)
+        # TODO - add a task identifier?
+        app.log(action, msg, level)
+      end
+
+      # Raises a TerminateError if app.state == State::TERMINATE.
+      # check_terminate may be called at any time to provide a 
+      # breakpoint in long-running processes.
+      def check_terminate
+        if app.state == App::State::TERMINATE
+          raise App::TerminateError.new
+        end
+      end
+      
+      # Returns self.name
+      def to_s
+        name
+      end
+      
+    end
+  end
+end

data/lib/tap/support/framework_class.rb

@@ -0,0 +1,199 @@
+require 'tap/support/command_line'
+
+module Tap
+  module Support
+  
+    # FrameworkClass encapsulates class methods related to Framework.
+    module FrameworkClass
+       
+      # Returns the default name for the class: to_s.underscore
+      attr_accessor :default_name
+           
+      def self.extended(base)
+        caller.each_with_index do |line, index|
+          case line
+          when /\/framework.rb/ then next
+          when /^(([A-z]:)?[^:]+):(\d+)/
+            base.instance_variable_set(:@source_file, File.expand_path($1))
+            break
+          end
+        end
+        
+        base.instance_variable_set(:@default_name, base.to_s.underscore)
+      end
+      
+      def inherited(child)
+        unless child.instance_variable_defined?(:@source_file)
+          caller.first =~ /^(([A-z]:)?[^:]+):(\d+)/
+          child.instance_variable_set(:@source_file, File.expand_path($1)) 
+        end
+        
+        child.instance_variable_set(:@default_name, child.to_s.underscore)
+        super
+      end
+
+      def subclass(const_name, configs={}, options={}, &block)
+        # Generate the nesting module
+        current, constants = const_name.to_s.constants_split
+        raise ArgumentError, "#{current} is already defined!" if constants.empty?
+         
+        subclass_const = constants.pop
+        constants.each {|const| current = current.const_set(const, Module.new)}
+        
+        # Generate the subclass
+        subclass = Class.new(self)
+        configs = configs[0] if configs.kind_of?(Array) && configs.length == 1 && configs[0].kind_of?(Hash)
+        
+        case configs
+        when Hash
+          subclass.send(:attr_accessor, *configs.keys)
+          configs.each_pair do |key, value|
+            subclass.configurations.add(key, value)
+          end
+        when Array
+          configs.each do |method, key, value, opts, config_block| 
+            subclass.send(method, key, value, opts, &config_block)
+          end
+        end
+        
+        block_method = options[:block_method] || :process
+        subclass.send(:define_method, block_method, &block)
+        subclass.default_name = const_name
+
+        const_name = current == Object ? subclass_const : "#{current}::#{subclass_const}"
+        caller.each_with_index do |line, index|
+          case line
+          when /\/tap\/support\/declarations.rb/ then next
+          when /^(([A-z]:)?[^:]+):(\d+)/
+            subclass.source_file = File.expand_path($1)
+            subclass.lazydoc[const_name, false]['manifest'] = subclass.lazydoc.register($3.to_i - 1)
+            break
+          end
+        end
+        
+        arity = options[:arity] || block.arity
+        comment = Comment.new
+        comment.subject = case
+        when arity > 0
+          Array.new(arity, "INPUT").join(' ')
+        when arity < 0
+          array = Array.new(-1 * arity - 1, "INPUT")
+          array << "INPUTS..."
+          array.join(' ')
+        else ""
+        end
+        subclass.lazydoc[const_name, false]['args'] ||= comment
+        
+        # Set the subclass constant
+        current.const_set(subclass_const, subclass)
+      end
+      
+      DEFAULT_HELP_TEMPLATE = %Q{<%= task_class %><%= manifest.subject.to_s.strip.empty? ? '' : ' -- ' %><%= manifest.subject %>
+
+<% unless manifest.empty? %>
+<%= '-' * 80 %>
+
+<% manifest.wrap(77, 2, nil).each do |line| %>
+  <%= line %>
+<% end %>
+<%= '-' * 80 %>
+<% end %>
+
+}
+
+      def instantiate(argv, app=Tap::App.instance) # => instance, argv
+        opts = OptionParser.new
+ 
+        # Add configurations
+        config = {}
+        unless configurations.empty?
+          opts.separator ""
+          opts.separator "configurations:"
+        end
+
+        configurations.each do |receiver, key, configuration|
+          opts.on(*CommandLine.configv(configuration)) do |value|
+            config[key] = value
+          end
+        end
+
+        # Add options on_tail, giving priority to configurations
+        opts.separator ""
+        opts.separator "options:"
+
+        opts.on_tail("-h", "--help", "Print this help") do
+          args = lazydoc(true)[to_s]['args'] || Tap::Support::Comment.new
+
+          opts.banner = "#{help}usage: tap run -- #{to_s.underscore} #{args.subject}"
+          puts opts
+          exit
+        end
+
+        # Add option for name
+        name = default_name
+        opts.on_tail('--name NAME', /^[^-].*/, 'Specify a name') do |value|
+          name = value
+        end
+
+        # Add option to add args
+        use_args = []
+        opts.on_tail('--use FILE', /^[^-].*/, 'Loads inputs from file') do |value|
+          obj = YAML.load_file(value)
+          case obj
+          when Hash 
+            obj.values.each do |array|
+              # error if value isn't an array
+              use_args.concat(array)
+            end
+          when Array 
+            use_args.concat(obj)
+          else
+            use_args << obj
+          end
+        end
+
+        opts.parse!(argv)
+        obj = new({}, name, app)
+
+        path_configs = load_config(app.config_filepath(name))
+        if path_configs.kind_of?(Array)
+          path_configs.each_with_index do |path_config, i|
+            obj.initialize_batch_obj(path_config, "#{name}_#{i}") unless i == 0
+          end
+          path_configs = path_configs[0]
+        end
+
+        [obj.reconfigure(path_configs).reconfigure(config), argv + use_args]
+      end
+      
+      def lazydoc(resolve=false, args_method=:process)
+        if resolve
+          lazydoc = super(false)
+          lazydoc.resolve(nil, /^\s*def\s+#{args_method}(\((.*?)\))?/) do |comment, match|
+            comment.subject = match[2].to_s.split(',').collect do |arg|
+              arg = arg.strip.upcase
+              case arg
+              when /^&/ then nil
+              when /^\*/ then arg[1..-1] + "..."
+              else arg
+              end
+            end.join(', ')
+
+            lazydoc.default_attributes['args'] ||= comment
+          end
+          
+          super(true)
+        else       
+          super(false)
+        end
+      end
+      
+      def help
+        Tap::Support::Templater.new(DEFAULT_HELP_TEMPLATE, 
+          :task_class => self, 
+          :manifest => lazydoc(true)[to_s]['manifest'] || Tap::Support::Comment.new
+        ).build
+      end
+    end
+  end
+end

data/lib/tap/support/instance_configuration.rb

@@ -0,0 +1,147 @@
+module Tap
+  module Support
+    
+    # InstanceConfiguration serves as a forwarding hash, where get and set operations
+    # for configurations are sent to instance methods rather than to an underlying data 
+    # store.  
+    #
+    #   class Sample
+    #     attr_accessor :key
+    #   end
+    #   sample = Sample.new
+    #
+    #   class_config = ClassConfiguration.new(Sample)
+    #   class_config.add(:key)
+    #
+    #   config = InstanceConfiguration.new(class_config)
+    #   config.bind(sample)
+    #
+    #   sample.key = 'value'
+    #   config[:key]                # => 'value'
+    #
+    #   config[:key] = 'another'
+    #   sample.key                  # => 'another'
+    #
+    # Non-config keys are simply stored:
+    #
+    #   config[:not_a_key] = 'value'
+    #   config[:not_a_key]          # => 'value'
+    #
+    #   config.store                # => {:not_a_key => 'value'}
+    #   config.to_hash              # => {:key => 'another', :not_a_key => 'value'}
+    #
+    class InstanceConfiguration
+      
+      # The bound receiver
+      attr_reader :receiver
+      
+      # The underlying data store for non-config keys
+      attr_reader :store
+      
+      # The ClassConfiguration specifying config keys
+      attr_reader :class_config
+      
+      def initialize(class_config, receiver=nil)
+        @receiver = receiver
+        @store = {}
+        @class_config = class_config
+      end
+      
+      # Binds self to the specified receiver.  Mapped keys are
+      # removed from store and sent to their writer method on 
+      # receiver.
+      def bind(receiver)
+        raise ArgumentError.new("receiver cannot be nil") if receiver == nil
+        
+        class_config.each_pair do |key, config|
+          receiver.send(config.writer, store.delete(key))
+        end
+        @receiver = receiver
+        
+        self
+      end
+      
+      # Returns true if self is bound to a receiver
+      def bound?
+        receiver != nil
+      end
+      
+      # Unbinds self from the specified receiver.  Mapped values
+      # are stored in store.  Returns the unbound receiver.
+      def unbind
+        class_config.each_pair do |key, config|
+          store[key] = receiver.send(config.reader)
+        end
+        r = receiver
+        @receiver = nil
+        
+        r
+      end
+      
+      # Duplicates self, returning an unbound InstanceConfiguration.
+      def dup
+        duplicate = super()
+        duplicate.instance_variable_set(:@receiver, nil)
+        duplicate.instance_variable_set(:@store, @store.dup)
+        duplicate
+      end
+      
+      # Associates the value the key.  If bound? and the key
+      # is a class_config key, then the value will be forwarded
+      # to the class_config.writer method on the receiver.
+      def []=(key, value)
+        case 
+        when bound? && config = class_config.map[key.to_sym]
+          receiver.send(config.writer, value)
+        else store[key] = value
+        end
+      end
+      
+      # Retrieves the value corresponding to the key. If bound? 
+      # and the key is a class_config key, then the value is
+      # obtained from the :key method on the receiver.
+      def [](key)
+        case 
+        when bound? && config = class_config.map[key.to_sym]
+          receiver.send(config.reader)
+        else store[key]
+        end
+      end
+      
+      # True if the key is assigned in self.
+      def has_key?(key)
+        (bound? && class_config.key?(key)) || store.has_key?(key) 
+      end
+      
+      # Calls block once for each key-value pair stored in self.
+      def each_pair # :yields: key, value
+        class_config.each_pair do |key, config|
+          yield(key, receiver.send(config.reader))
+        end if bound?
+        
+        store.each_pair do |key, value|
+          yield(key, value)
+        end
+      end
+      
+      # Equal if the to_hash values of self and another are equal.
+      def ==(another)
+        to_hash == another.to_hash
+      end
+      
+      # Returns self as a hash. 
+      def to_hash
+        hash = store.dup
+        class_config.keys.each do |key|
+          hash[key] = self[key]
+        end if bound?
+        hash
+      end
+      
+      # Overrides default inspect to show the to_hash values.
+      def inspect
+        "#<#{self.class}:#{object_id} to_hash=#{to_hash.inspect}>"
+      end
+    end
+  end
+end

data/lib/tap/support/lazydoc.rb

@@ -0,0 +1,428 @@
+require 'tap/support/comment'
+
+module Tap
+  module Support
+    
+    # Lazydoc scans source files to pull out documentation.  Lazydoc can find two
+    # types of documentation, constant attributes and code comments.
+    #
+    # === Constant Attributes
+    #
+    # Constant attributes are designated the same as constants in Ruby, but with
+    # an extra 'key' constant that must consist of only lowercase letters and/or
+    # underscores.  This format assures that attributes are sytactically invalid
+    # outside of comments.
+    #
+    # When Lazydoc finds an attribute it parses a Comment value where the subject
+    # is the remainder of the line, and comment lines are parsed down until a
+    # non-comment line, an end key, or a new attribute is reached.
+    #
+    #   str = %Q{
+    #   # Const::Name::key subject for key
+    #   # comment for key
+    #   # parsed until a non-comment line
+    #
+    #   # Const::Name::another subject for another
+    #   # comment for another
+    #   # parsed to an end key
+    #   # Const::Name::another-
+    #   #
+    #   # ignored comment
+    #   }
+    #
+    #   lazydoc = Lazydoc.new
+    #   lazydoc.resolve(str)
+    #
+    #   lazydoc.to_hash {|comment| [comment.subject, comment.to_s] } 
+    #   # => {'Const::Name' => {
+    #   #  'key' =>     ['subject for key', 'comment for key parsed until a non-comment line'],
+    #   #  'another' => ['subject for another', 'comment for another parsed to an end key']
+    #   # }}
+    #
+    # A constant name does not need to be specified; when no constant name is
+    # specified, Lazydoc will store the key as a default for the document. To
+    # turn off attribute parsing for a section of documentation, use start/stop
+    # keys:
+    #
+    #   str = %Q{
+    #   # :::-
+    #   # Const::Name::not_parsed
+    #   # :::+
+    #
+    #   # Const::Name::parsed subject
+    #   }
+    #
+    #   lazydoc = Lazydoc.new
+    #   lazydoc.resolve(str)
+    #   lazydoc.to_hash {|comment| comment.subject }   # => {'Const::Name' => {'parsed' => 'subject'}}
+    #
+    # ==== startdoc
+    #
+    # Lazydoc is completely separate from RDoc, but the syntax of Lazydoc was developed
+    # with RDoc in mind.  To hide attributes in one line, make use of the RDoc 
+    # <tt>:startdoc:</tt> document modifier like this (spaces added to keep them in the
+    # example):
+    #
+    #   # :start doc::Const::Name::one hidden in RDoc
+    #   # * This line is visible in RDoc.
+    #   # :start doc::Const::Name::one-
+    #   # 
+    #   #-- 
+    #   # Const::Name::two
+    #   # You can hide attribute comments like this.
+    #   # Const::Name::two-
+    #   #++
+    #   #
+    #   # * This line is also visible in RDoc.
+    #
+    # Here is the same text, actually in RDoc:
+    #
+    # :startdoc::Const::Name::one hidden in RDoc
+    # * This line is visible in RDoc.
+    # :startdoc::Const::Name::one-
+    # 
+    #-- 
+    # Const::Name::two
+    # You can hide attribute comments like this.
+    # Const::Name::two-
+    #++
+    #
+    # * This line is also visible in RDoc.
+    #
+    # === Code Comments
+    #
+    # Code comments are lines marked for parsing if and when a Lazydoc gets resolved.
+    # Unlike constant attributes, the line is the subject of a code comment and
+    # comment lines are parsed up from it (effectively mimicking the behavior of
+    # RDoc).
+    #
+    #   str = %Q{
+    #   # comment lines for
+    #   # the method
+    #   def method
+    #   end
+    #
+    #   # as in RDoc, the comment can be
+    #   # separated from the method
+    #
+    #   def another_method
+    #   end
+    #   }
+    #
+    #   lazydoc = Lazydoc.new
+    #   lazydoc.register(3)
+    #   lazydoc.register(9)
+    #   lazydoc.resolve(str)
+    #
+    #   lazydoc.code_comments.collect {|comment| [comment.subject, comment.to_s] } 
+    #   # => [
+    #   # ['def method', 'comment lines for the method'],
+    #   # ['def another_method', 'as in RDoc, the comment can be separated from the method']]
+    #
+    class Lazydoc
+      
+      # A regexp matching an attribute start or end.  For the match:
+      #
+      # $1:: const_name
+      # $3:: key
+      # $4:: end flag
+      #
+      ATTRIBUTE_REGEXP = /(::|([A-Z][A-z]*::)+)([a-z_]+)(-?)/
+      
+      # A regexp matching constants.
+      CONSTANT_REGEXP = /(::|([A-Z][A-z]*::)+)/
+      
+      class << self
+        
+        # A hash of (source_file, lazydoc) pairs tracking the
+        # Lazydoc instance for the given source file.
+        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.
+        def [](source_file)
+          source_file = File.expand_path(source_file.to_s)
+          lazydoc = registry.find {|doc| doc.source_file == source_file }
+          if lazydoc == nil
+            lazydoc = new(source_file)
+            registry << lazydoc
+          end
+          lazydoc
+        end
+
+        # Register the specified line numbers to the lazydoc for source_file.
+        # Returns a CodeComment corresponding to the line.
+        def register(source_file, line_number)
+          Lazydoc[source_file].register(line_number)
+        end
+        
+        # Resolves all lazydocs which include the specified code comments.
+        def resolve(code_comments)
+          registry.each do |doc|
+            next if (code_comments & doc.code_comments).empty?
+            doc.resolve
+          end
+        end
+        
+        # Scans the specified file for attributes keyed by key and stores 
+        # the resulting comments in the corresponding 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.attributes(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
+        #
+        #   Ignored::Attribute::not_matched value
+        #   :::-
+        #   Also::Ignored::key value
+        #   :::+
+        #   Another::key another 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})([ \r\t-].*$|$)/
+          while !scanner.eos?
+            break if scanner.skip_until(CONSTANT_REGEXP) == nil
+            const_name = scanner[1]
+            
+            case
+            when scanner.scan(regexp)
+              yield(const_name.chomp('::'), scanner[1], scanner[2].strip)
+            when scanner.scan(/:-/)
+              scanner.skip_until(/:\+/)
+            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
+        #
+        #   # :::-
+        #   # Ignored::key value
+        #   # :::+
+        #
+        #   # Ignored text before attribute ::another subject for another
+        #   # comment for another
+        #   }
+        #
+        #   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']]
+        #
+        # 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 =~ /::/ && line =~ ATTRIBUTE_REGEXP
+                # rewind to capture the next attribute unless an end is specified.
+                scanner.unscan unless !$4.empty? && $1.chomp("::") == const_name && $3 == key
+                true
+              else false
+              end
+            end
+            comment.subject = value
+            yield(const_name, key, comment)
+          end
+        end
+      end
+      
+      include Enumerable
+      
+      # The source file for self, used in resolving comments and
+      # attributes.
+      attr_reader :source_file
+      
+      # An array of Comment objects identifying lines resolved or
+      # to-be-resolved for self.
+      attr_reader :code_comments
+      
+      # A hash of (const_name, attributes) pairs tracking the constant 
+      # attributes resolved or to-be-resolved for self.  Attributes
+      # are hashes of (key, comment) pairs.
+      attr_reader :const_attrs
+
+      def initialize(source_file=nil)
+        self.source_file = source_file
+        @code_comments = []
+        @const_attrs = {}
+        @resolved = false
+      end
+      
+      # Sets the source file for self.  Expands the source file path if necessary.
+      def source_file=(source_file)
+        @source_file = source_file == nil ? nil : File.expand_path(source_file)
+      end
+
+      # Returns the attributes for the specified const_name.
+      def attributes(const_name)
+        const_attrs[const_name] ||= {}
+      end
+      
+      # Returns default document attributes (ie attributes(''))
+      def default_attributes
+        attributes('')
+      end
+      
+      # Returns the attributes for const_name merged to default_attributes.  
+      # Set merge_defaults to false to get just the attributes for const_name.
+      def [](const_name, merge_defaults=true)
+        merge_defaults ? default_attributes.merge(attributes(const_name)) : attributes(const_name)
+      end
+      
+      # Yields each (const_name, attributes) pair to the block; const_names where
+      # the attributes are empty are skipped.
+      def each
+        const_attrs.each_pair do |const_name, attrs|
+          yield(const_name, attrs) unless attrs.empty?
+        end
+      end
+      
+      # Returns true if the attributes for const_name are not empty.
+      def has_const?(const_name)
+        const_attrs.each_pair do |constname, attrs|
+          next unless constname == const_name
+          return !attrs.empty?
+        end
+        
+        false
+      end
+      
+      # Returns an array of the constant names in self, for which
+      # the constant attributes are not empty.
+      def const_names
+        names = []
+        const_attrs.each_pair do |const_name, attrs|
+          names << const_name unless attrs.empty?
+        end
+        names
+      end
+
+      # Register the specified line number to self.  Returns a 
+      # Comment object corresponding to the line.
+      def register(line_number)
+        comment = code_comments.find {|c| c.line_number == line_number }
+
+        if comment == nil
+          comment = Comment.new(line_number)
+          code_comments << comment
+        end
+
+        comment
+      end
+      
+      # Returns true if the code_comments for source_file are frozen.
+      def resolved?
+        @resolved
+      end
+      
+      attr_writer :resolved
+      
+      def resolve(str=nil, comment_regexp=nil) # :yields: comment, match
+        return(false) if resolved?
+        
+        if str == nil 
+          raise ArgumentError, "no source file specified" unless source_file && File.exists?(source_file)
+          str = File.read(source_file)
+        end
+        
+        Lazydoc.parse(str) do |const_name, key, comment|
+          attributes(const_name)[key] = comment
+        end
+        
+        lines = str.split(/\r?\n/)
+        lines.each_with_index do |line, line_number|
+          next unless line =~ comment_regexp
+          comment = register(line_number)
+          yield(comment, $~) if block_given?
+        end unless comment_regexp == nil
+          
+        code_comments.collect! do |comment|
+          line_number = comment.line_number
+          comment.subject = lines[line_number] if comment.subject == nil
+
+          # remove whitespace lines
+          line_number -= 1
+          while lines[line_number].strip.empty?
+            line_number -= 1
+          end
+
+          # put together the comment
+          while line_number >= 0
+            break unless comment.prepend(lines[line_number])
+            line_number -= 1
+          end
+
+          comment
+        end
+        
+        @resolved = true
+      end
+      
+      def to_hash
+        const_hash = {}
+        const_names.sort.each do |const_name|
+          attr_hash = {}
+          self[const_name, false].each_pair do |key, comment|
+            attr_hash[key] = (block_given? ? yield(comment) : comment)
+          end
+          const_hash[const_name] = attr_hash
+        end
+        const_hash
+      end
+    end
+  end
+end