tap 0.9.1 → 0.10.0

data/lib/tap/support/comment.rb

@@ -0,0 +1,270 @@
+require 'strscan'
+
+module Tap
+  module Support 
+    # Comment represents a comment parsed by Lazydoc.
+    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
+        # lines 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.lines   
+        #   # => [
+        #   # ['comments spanning multiple', 'lines are collected'],
+        #   # [''],
+        #   # ['  while indented lines'],
+        #   # ['  are preserved individually'],
+        #   # [''],
+        #   # []]
+        #   c.subject   # => "this is the subject line"
+        #
+        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
+        
+        # Scans the line checking if it is a comment.  If so, scan
+        # yields the parse fragments to the block which correspond
+        # to the type of comment input (continuation, indent, etc).
+        # Returns true if the line is a comment, false otherwise.
+        #
+        # Scan may be used to build a comment from an array of lines:
+        #
+        #   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.lines   
+        #   # => [
+        #   # ['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
+        
+        def wrap(lines, cols=80, tabsize=2)
+          lines = lines.split(/\r?\n/) unless lines.kind_of?(Array)
+          
+          lines.collect do |line|
+            line = line.gsub(/\t/, " " * tabsize) unless tabsize == nil
+
+            if line.strip.empty? 
+              line
+            else
+              # wrapping algorithm is slightly modified from 
+              # http://blog.macromates.com/2006/wrapping-text-with-regular-expressions/
+              line.gsub(/(.{1,#{cols}})( +|$\r?\n?)|(.{1,#{cols}})/, "\\1\\3\n").split(/\s*\n/)
+            end
+          end.flatten
+        end
+        
+        private
+        
+        def categorize(fragment, indent)
+           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 line fragment arrays.
+      attr_reader :lines
+    
+      # The next non-comment line after the comment ends.
+      # This is the line that would receive the comment
+      # in RDoc documentation.
+      attr_accessor :subject
+      
+      # Returns the line number for the subject line, if known.
+      attr_accessor :line_number
+    
+      def initialize(line_number=nil)
+        @lines = []
+        @subject = nil
+        @line_number = line_number
+      end
+
+      # Pushes the fragment onto the last line array.  If fragment is an
+      # array itself, then fragment will be pushed onto lines.
+      #
+      #   c = Comment.new
+      #   c.push "some line"
+      #   c.push "fragments"
+      #   c.push ["a", "whole", "new line"]
+      #   c.lines         # => [["some line", "fragments"], ["a", "whole", "new line"]]
+      #
+      def push(fragment)
+        lines << [] if lines.empty?
+        
+        case fragment
+        when Array
+          if lines[-1].empty? 
+            lines[-1] = fragment
+          else
+            lines.push fragment
+          end
+        else
+           lines[-1].push fragment
+        end
+      end
+      
+      # Alias for push.
+      def <<(fragment)
+        push(fragment)
+      end
+      
+      # Unshifts the fragment to the first line array.  If fragment is an
+      # array itself, then fragment will be unshifted onto lines.
+      #
+      #   c = Comment.new
+      #   c.unshift "some line"
+      #   c.unshift "fragments"
+      #   c.unshift ["a", "whole", "new line"]
+      #   c.lines         # => [["a", "whole", "new line"], ["fragments", "some line"]]
+      #
+      def unshift(fragment)
+        lines << [] if lines.empty?
+        
+        case fragment
+        when Array
+          if lines[0].empty? 
+            lines[0] = fragment
+          else
+            lines.unshift fragment
+          end
+        else
+           lines[0].unshift fragment
+        end
+      end
+      
+      def prepend(comment_line)
+        Comment.scan(comment_line) {|f| unshift(f) }
+      end
+      
+      def append(comment_line)
+        Comment.scan(comment_line) {|f| push(f) }
+      end
+      
+      # Removes leading and trailing lines that are empty ([]) 
+      # or whitespace (['']).  Returns self.
+      def trim
+        lines.shift while !lines.empty? && (lines[0].empty? || lines[0].join.strip.empty?)
+        lines.pop while !lines.empty? && (lines[-1].empty? || lines[-1].join.strip.empty?)
+        self
+      end
+      
+      # True if there are no fragments in self.
+      def empty?
+        !lines.find {|array| !array.empty?}
+      end
+      
+      def wrap(cols=80, tabsize=2, line_sep="\n", fragment_sep=" ", strip=true)
+        resolved_lines = Comment.wrap(to_s(fragment_sep, nil, strip), cols, tabsize)
+        line_sep ? resolved_lines.join(line_sep) : resolved_lines
+      end
+    
+      # Returns lines 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)
+        resolved_lines = lines.collect {|line| line.join(fragment_sep)}
+        
+        # strip leading an trailing whitespace lines
+        if strip
+          resolved_lines.shift while !resolved_lines.empty? && resolved_lines[0].empty?
+          resolved_lines.pop while !resolved_lines.empty? && resolved_lines[-1].empty?
+        end
+        
+        line_sep ? resolved_lines.join(line_sep) : resolved_lines
+      end
+      
+      def ==(another)
+        another.kind_of?(Comment) && 
+        self.line_number == another.line_number &&
+        self.subject == another.subject &&
+        self.lines == another.lines
+      end
+
+    end
+  end
+end

data/lib/tap/support/configurable.rb

@@ -1,92 +1,113 @@
+require 'tap/support/configurable_class'
+
 module Tap
   module Support
     
-    # Configurable encapsulates all configuration-related methods used
-    # by Tasks.  When Configurable is included in a class, the class itself
-    # is extended with Tap::Support::ConfigurableMethods, such that configs
-    # can be declared within the class definition.
+    # Configurable enables the specification of configurations within a class definition.
     #
-    #   class ConfigurableClass
+    #   class ConfigClass
     #     include Configurable
     # 
     #     config :one, 'one'
     #     config :two, 'two'
     #     config :three, 'three'
+    #
+    #     def initialize(overrides={})
+    #       initialize_config(overrides)
+    #     end
+    #   end
+    #
+    #   c = ConfigClass.new
+    #   c.config.class         # => InstanceConfiguration
+    #   c.config               # => {:one => 'one', :two => 'two', :three => 'three'}
+    #
+    # The <tt>config</tt> object acts as a kind of forwarding hash; declared configurations
+    # map to accessors while undeclared configurations are stored internally:
+    #
+    #   c.config[:one] = 'ONE'
+    #   c.one                  # => 'ONE'
+    #
+    #   c.one = 1           
+    #   c.config               # => {:one => 1, :two => 'two', :three => 'three'}
+    #
+    #   c.config[:undeclared] = 'value'
+    #   c.config.store         # => {:undeclared => 'value'}
+    #
+    # The writer method for a configuration can be modified by providing a block to config.  
+    # The Validation module provides a number of common validation and string-transform 
+    # blocks which can be accessed through the class method 'c':
+    #
+    #   class SubClass < ConfigClass
+    #     config(:one, 'one') {|v| v.upcase }
+    #     config :two, 2, &c.integer
     #   end
     #
-    #   ConfigurableClass.new.config  # => {:one => 'one', :two => 'two', :three => 'three'}
+    #   s = SubClass.new
+    #   s.config               # => {:one => 'ONE', :two => 2, :three => 'three'}
+    #
+    #   s.one = 'aNothER'             
+    #   s.one                  # => 'ANOTHER'
+    #
+    #   s.two = -2
+    #   s.two                  # => -2
+    #   s.two = "3"
+    #   s.two                  # => 3
+    #   s.two = nil            # !> ValidationError
+    #   s.two = 'str'          # !> ValidationError
+    #
+    # As shown above, configurations are inherited from the parent and can be
+    # overridden in subclasses.  See ConfigurableClass for more details.
     #
-    # See the 'Configuration' section in the Tap::Task documentation for
-    # more details on how Configurable works in practice.
     module Configurable
-      include Batchable
-    
+      
+      # Extends including classes with ConfigurableClass
       def self.included(mod)
-        mod.extend Support::BatchableMethods
-        mod.extend Support::ConfigurableMethods
-        mod.instance_variable_set(:@configurations, Support::ClassConfiguration.new(mod))
-        mod.instance_variable_set(:@source_files, [])
+        mod.extend Support::ConfigurableClass if mod.kind_of?(Class)
       end
-    
-      # The application used to load config_file templates 
-      # (and hence, to initialize batched objects).
-      attr_reader :app
       
-      # The name used to determine config_file, via
-      # app.config_filepath(name).
-      attr_reader :name
-      
-      # The config file used to load config templates.
-      attr_reader :config_file
-      
-      # A configuration hash.
+      # The instance configurations for self
       attr_reader :config
       
-      # Initializes a new Configurable and associated batch objects.  Batch
-      # objects will be initialized for each configuration template specified
-      # in config_file, where config_file = app.config_filepath(name).  
-      def initialize(name=nil, config={}, app=App.instance)
-        @app = app
-        @batch = []
-        @config_file = app.config_filepath(name)
-        
-        config.symbolize_keys! unless config.empty?
-        app.each_config_template(config_file) do |template|
-          template_config = template.empty? ? config : template.symbolize_keys.merge(config)
-          initialize_batch_obj(name, template_config)
+      # Reconfigures self with the given configuration overrides.  Only
+      # the specified configs are modified.  Override keys are symbolized.
+      #
+      # Returns self.
+      def reconfigure(overrides={})
+        keys = (config.class_config.ordered_keys + overrides.keys) & overrides.keys
+        keys.each do |key|
+          config[key.to_sym] = overrides[key] 
         end
+
+        self
       end
-    
-      # Sets config with the given configuration overrides, merged with the class
-      # default configuration.  Configurations are symbolized before they are merged,
-      # and validated as specified in the config declarations.
-      def config=(overrides)
-        @config = self.class.configurations.default.dup
-        overrides.each_pair {|key, value| set_config(key.to_sym, value) } 
-        self.config
+      
+      # Reinitializes config with a copy of orig.config (this assures
+      # that duplicates have their own copy of configurations, 
+      # separate from the original object).
+      def initialize_copy(orig)
+        super
+        initialize_config(orig.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(name=nil, config={})
-        obj = super()
+      protected
       
-        obj.name = name.nil? ? self.class.default_name : name
-        obj.config = config
+      # Initializes config to an InstanceConfiguration specific for self.
+      # Default config values are assigned or overridden if specified in
+      # overrides. Override keys are symbolized.
+      def initialize_config(overrides={})
+        class_config = self.class.configurations
+        @config = class_config.instance_config
+        
+        overrides.each_pair do |key, value|
+          config[key.to_sym] = value
+        end
+        
+        class_config.each_pair do |key, value|
+          next if config.has_key?(key)
+          config[key] = value.default
+        end
 
-        obj
-      end
-    
-      protected
-    
-      attr_writer :name
-    
-      # Sets the specified configuration, processing the input value using
-      # the block specified in the config declaration.  The input key should
-      # be symbolized.
-      def set_config(key, value)
-        config[key] = self.class.configurations.process(key, value)
+        config.bind(self)
       end
     end
   end

data/lib/tap/support/configurable_class.rb

@@ -0,0 +1,296 @@
+require 'tap/support/class_configuration'
+require 'tap/support/validation'
+require 'tap/support/lazydoc'
+
+module Tap
+  module Support
+    autoload(:Templater, 'tap/support/templater')
+    
+    # ConfigurableClass encapsulates class methods used to declare class configurations. 
+    # When configurations are declared using the config method, ConfigurableClass 
+    # generates accessors in the class, much like attr_accessor.  
+    #
+    #   class ConfigurableClass
+    #     extend ConfigurableClass
+    #     config :one, 'one'
+    #   end
+    #
+    #   ConfigurableClass.configurations.to_hash   # => {:one => 'one'}
+    #
+    #   c = ConfigurableClass.new
+    #   c.respond_to?('one')                       # => true
+    #   c.respond_to?('one=')                      # => true
+    # 
+    # If a block is given, the block will be used to create the writer method
+    # for the config.  Used in this manner, config defines a <tt>config_key=</tt> method 
+    # wherein <tt>@config_key</tt> will be set to the return value of the block.
+    #
+    #   class AnotherConfigurableClass
+    #     extend ConfigurableClass
+    #     config(:one, 'one') {|value| value.upcase }
+    #   end
+    #
+    #   ac = AnotherConfigurableClass.new
+    #   ac.one = 'value'
+    #   ac.one               # => 'VALUE'
+    #
+    # The block has class-context in this case.  To have instance-context, use the
+    # config_attr method which defines the writer method using the block directly.
+    #
+    #   class YetAnotherConfigurableClass
+    #     extend ConfigurableClass
+    #     config_attr(:one, 'one') {|value| @one = value.reverse }
+    #   end
+    #
+    #   ac = YetAnotherConfigurableClass.new
+    #   ac.one = 'value'
+    #   ac.one               # => 'eulav'
+    #
+    module ConfigurableClass
+      
+      # A ClassConfiguration holding the class configurations.
+      attr_reader :configurations
+      
+      # The source_file for self.  By default the first file
+      # to define the class inheriting ConfigurableClass.
+      attr_accessor :source_file
+
+      # Sets the source_file for base and initializes base.configurations.
+      def self.extended(base)
+        caller.each_with_index do |line, index|
+          case line
+          when /\/configurable.rb/ then next
+          when /^(([A-z]:)?[^:]+):(\d+)/
+            base.instance_variable_set(:@source_file, File.expand_path($1))
+            break
+          end
+        end
+        
+        base.instance_variable_set(:@configurations, ClassConfiguration.new(base))
+      end
+
+      # When subclassed, the parent.configurations are duplicated and passed to 
+      # the child class where they can be extended/modified without affecting
+      # the configurations of the parent class.
+      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(:@configurations, ClassConfiguration.new(child, @configurations))
+        super
+      end
+      
+      # Returns the lazydoc for source_file
+      def lazydoc(resolve=false)
+        Lazydoc.resolve(configurations.code_comments) if resolve
+        Lazydoc[source_file]
+      end
+      
+      # Loads the contents of path as YAML.  Returns an empty hash if the path 
+      # is empty, does not exist, or is not a file.
+      def load_config(path)
+        return {} if path == nil || !File.exists?(path) || File.directory?(path)
+
+        YAML.load_file(path) || {}
+      end
+      
+      protected
+      
+      # Declares a class configuration and generates the associated accessors. 
+      # If a block is given, the <tt>key=</tt> method will set <tt>@key</tt> 
+      # to the return of the block, which executes in class-context.  
+      # Configurations are inherited, and can be overridden in subclasses. 
+      #
+      #   class SampleClass
+      #     include Tap::Support::Configurable
+      #
+      #     config :str, 'value'
+      #     config(:upcase, 'value') {|input| input.upcase } 
+      #   end
+      #
+      #   # An equivalent class to illustrate class-context
+      #   class EquivalentClass
+      #     attr_accessor :str
+      #     attr_reader :upcase
+      #
+      #     UPCASE_BLOCK = lambda {|input| input.upcase }
+      #
+      #     def upcase=(input)
+      #       @upcase = UPCASE_BLOCK.call(input)
+      #     end
+      #   end
+      #
+      def config(key, value=nil, options={}, &block)
+        if block_given?
+          # add arg_type implied by block, if necessary
+          options[:arg_type] = arg_type(block) if options[:arg_type] == nil
+          options[:arg_name] = arg_name(block) if options[:arg_name] == nil
+          
+          instance_variable = "@#{key}".to_sym
+          config_attr(key, value, options) do |input|
+            instance_variable_set(instance_variable, block.call(input))
+          end
+        else
+          config_attr(key, value, options)
+        end
+      end
+      
+      # Declares a class configuration and generates the associated accessors. 
+      # If a block is given, the <tt>key=</tt> method will perform the block with
+      # instance-context.  Configurations are inherited, and can be overridden 
+      # in subclasses. 
+      #
+      #   class SampleClass
+      #     include Tap::Support::Configurable
+      #
+      #     def initialize
+      #       initialize_config
+      #     end
+      #
+      #     config_attr :str, 'value'
+      #     config_attr(:upcase, 'value') {|input| @upcase = input.upcase } 
+      #   end
+      #
+      #   # An equivalent class to illustrate instance-context
+      #   class EquivalentClass
+      #     attr_accessor :str
+      #     attr_reader :upcase
+      #
+      #     def upcase=(input)
+      #       @upcase = input.upcase
+      #     end
+      #   end
+      #
+      # Instances of a Configurable class may set configurations through config.
+      # The config object is an InstanceConfiguration which forwards read/write 
+      # operations to the configuration accessors.  For example:
+      #
+      #   s = SampleClass.new
+      #   s.config.class            # => Tap::Support::InstanceConfiguration
+      #   s.str                     # => 'value'
+      #   s.config[:str]            # => 'value'
+      #
+      #   s.str = 'one'
+      #   s.config[:str]            # => 'one'
+      #   
+      #   s.config[:str] = 'two' 
+      #   s.str                     # => 'two'
+      # 
+      # Alternative reader and writer methods may be specified as an option;
+      # in this case config_attr assumes the methods are declared elsewhere
+      # and will not define the associated accessors.  
+      # 
+      #   class AlternativeClass
+      #     include Tap::Support::Configurable
+      #
+      #     config_attr :sym, 'value', :reader => :get_sym, :writer => :set_sym
+      #
+      #     def initialize
+      #       initialize_config
+      #     end
+      #
+      #     def get_sym
+      #       @sym
+      #     end
+      #
+      #     def set_sym(input)
+      #       @sym = input.to_sym
+      #     end
+      #   end
+      #
+      #   alt = AlternativeClass.new
+      #   alt.respond_to?(:sym)     # => false
+      #   alt.respond_to?(:sym=)    # => false
+      #   
+      #   alt.config[:sym] = 'one'
+      #   alt.get_sym               # => :one
+      #
+      #   alt.set_sym('two')
+      #   alt.config[:sym]          # => :two
+      #
+      # Idiosyncratically, true, false, and nil may also be provided as 
+      # reader/writer options. Specifying true is the same as using the 
+      # default.  Specifying false or nil prevents config_attr from 
+      # defining accessors, but the configuration still expects to use 
+      # the default reader/writer methods (ie <tt>key</tt> and <tt>key=</tt>) 
+      # which must be defined elsewhere.
+      def config_attr(key, value=nil, options={}, &block)
+        
+        # add arg_type implied by block, if necessary
+        options[:arg_type] = arg_type(block) if block_given? && options[:arg_type] == nil
+        options[:arg_name] = arg_name(block) if block_given? && options[:arg_name] == nil
+
+        # define the default public reader method
+        if !options.has_key?(:reader) || options[:reader] == true
+          attr_reader(key) 
+          public key
+        end
+        
+        # define the public writer method
+        case
+        when options.has_key?(:writer) && options[:writer] != true
+          raise ArgumentError.new("block may not be specified with writer") if block_given?
+        when block_given? 
+          define_method("#{key}=", &block)
+          public "#{key}="
+        else
+          attr_writer(key)
+          public "#{key}="
+        end
+
+        # remove any true, false, nil reader/writer declarations...
+        # implicitly reverting the option to the default reader
+        # and writer methods
+        [:reader, :writer].each do |option|
+          case options[option]
+          when true, false, nil then options.delete(option)
+          end
+        end
+        
+        # register with TDoc so that all extra documentation can be extracted
+        caller.each_with_index do |line, index|
+          case line
+          when /in .config.$/ then next
+          when /^(([A-z]:)?[^:]+):(\d+)/
+            options[:desc] = Lazydoc.register($1, $3.to_i - 1)
+            break
+          end
+        end if options[:desc] == nil
+        
+        configurations.add(key, value, options)
+      end
+
+      # Alias for Tap::Support::Validation
+      def c
+        Validation
+      end
+      
+      private
+      
+      # Returns special argument types for standard validation
+      # blocks, such as switch (Validation::SWITCH) and list
+      # (Validation::LIST).
+      def arg_type(block) # :nodoc:
+        case block
+        when Validation::SWITCH then :switch
+        when Validation::FLAG then :flag
+        when Validation::LIST then :list
+        else nil
+        end
+      end
+      
+      # Returns special argument names for standard validation
+      # blocks, such as switch (Validation::ARRAY) and list
+      # (Validation::HASH).
+      def arg_name(block) # :nodoc:
+        case block
+        when Validation::ARRAY then "'[a, b, c]'"
+        when Validation::HASH then "'{one: 1, two: 2}'"
+        else nil
+        end
+      end
+    end
+  end
+end