tap 0.7.9 → 0.8.0

data/lib/tap/support/batch_queue.rb

@@ -1,6 +1,3 @@
-require 'tap/support/audit'
-require 'monitor'
-
 module Tap
   module Support
     

data/lib/tap/support/logger.rb

@@ -2,20 +2,23 @@ require 'logger'
 
 module Tap
   module Support
+    
+    # == UNDER CONSTRUCTION
     # Logger provides methods to extend Logger objects.  
     #
     # The output format is designed to look nice in a command prompt, but provide useful information
     # if directed at a log file.  The Logger output format is like:
     #
-    #   I[datetime]           type message
-    #
+    #   I[datetime]    action  message
+    #--
     # The first letter ('I' - INFO) indicates the severity of the message, next comes the datetime of the
     # log, the type of log message, then the message itself.  Specify the log type and message like:
     #
     #   logger.type "message"
     #
     # Typed logging occurs through +method_missing+.  Any type is possible so long as the logger doesn't
-    #  already have a method of the input type.
+    # already have a method of the input type.
+    #++
     module Logger
       Format = "  %s[%s] %18s %s\n"
       

data/lib/tap/support/rake.rb

@@ -0,0 +1,54 @@
+require 'rake'
+
+module Rake # :nodoc:
+  # Modifies Rake::Task to behave like a Tap::Task.  
+  class Task # :nodoc:
+    alias_method(:tap_original_execute, :execute)
+    alias_method(:tap_original_invoke, :invoke)
+    alias_method(:tap_original_initialize, :initialize)
+    
+    def initialize(*args)
+      tap_original_initialize(*args)
+      self.extend Tap::Task::Base
+      self.extend InstanceMethods
+    end
+    
+    def invoke
+      @lock.synchronize do
+        if application.options.trace
+          puts "** Invoke #{name} #{format_trace_flags}"
+        end
+        return if @already_invoked
+        @already_invoked = true
+        invoke_prerequisites
+        tap_original_execute if needed?
+      end
+    end
+    
+    module InstanceMethods # :nodoc:
+      
+      def iterate=(input)
+        raise "iterate cannot be set to true for Rake tasks." if input == true
+      end
+      
+      protected 
+      
+      def on_execute(audited_inputs)
+        invoke
+        audited_inputs._record(self, nil)
+      end
+    end
+  end
+end
+
+module Tap
+  module Support
+    # == UNDER CONSTRUCTION
+    module Rake 
+      
+      def task(td, config=nil)
+        Object::Rake.application.lookup(td) || super
+      end
+    end
+  end
+end

data/lib/tap/support/task_configuration.rb

@@ -0,0 +1,169 @@
+module Tap
+  module Support
+    # == UNDER CONSTRUCTION
+    #
+    # TaskConfiguration holds the class configurations defined in a Tap::Task.
+    # The configurations are stored as an array of declarations like:
+    # [name, default, msg, declaration_class].  In addition, TaskConfiguration
+    # collapse the array of declarations into a hash, which acts as the default
+    # task configuration.
+    #
+    # Storing metadata about the configurations, such as the declaration_class, 
+    # allows the creation of more user-friendly configuration files and facilitates 
+    # incorporation into command-line applications.
+    #
+    # In general, users will not have to interact with TaskConfigurations directly.
+    #
+    # == Example
+    # 
+    #   class BaseTask < Tap::Task
+    #     class_configurations [:one, 1]
+    #   end
+    #
+    #   BaseTask.configurations.hash    # => {:one => 1}
+    #
+    #   class SubTask < BaseTask
+    #     class_configurations(
+    #       [:one, 'one', "the first configuration"],
+    #       [:two, 'two', "the second configuration"])
+    #   end
+    #
+    #   SubTask.configurations.hash    # => {:one => 'one', :two => 'two'}
+    #   
+    # Now you can see how the comments and declaring classes get used in the
+    # configuration files.  Note that configuration keys are stringified
+    # for clarity (this is ok -- they will be symbolized when loaded by a
+    # task).
+    #
+    #   [BaseTask.configurations.format_yaml]
+    #   # BaseTask configuration
+    #   one: 1        
+    #
+    #   [SubTask.configurations.format_yaml]
+    #   # BaseTask configuration
+    #   one: one             # the first configuration
+    #
+    #   # SubTask configuration
+    #   two: two             # the second configuration
+    #
+    class TaskConfiguration
+      attr_reader :declarations, :default, :attributes
+      
+      include Enumerable
+      
+      def initialize
+        @declarations = {}
+        @default = {}
+        @attributes = {}
+      end
+      
+      def dup
+        # ensure the duplication does not pass along 
+        # new references to the same objects
+        another = TaskConfiguration.new
+        another.declarations = self.declarations.dup
+        another.default = self.default.dup
+        another.attributes = self.attributes.dup
+        another
+      end
+      
+      def empty?
+        @declaration.empty?  
+      end
+      
+      def declared?(key)
+        default.has_key?(key.to_sym)
+      end
+      
+      def declare(key, declaration_class)
+        key = key.to_sym
+
+        # Check if the key is already declared...
+        return if declared?(key)
+
+        # Add a declaration array if no declaration have been
+        # created for the class and append the key
+        (declarations[declaration_class] ||= [declarations.length]) << key
+        default[key] = nil
+        attributes[key] = {}
+      end
+      
+      def set(key, value, attributes={})
+        key = key.to_sym
+        raise "configurations cannot be set until they are declared" unless declared?(key)
+        
+        default[key] = value
+        self.attributes[key].merge!(attributes)
+      end
+      
+      def each # :yields: declaration_class, key, default, attributes
+        declarations.each_pair do |declaration_class, keys|
+          keys[1..-1].each do |key|
+            yield(declaration_class, key, default[key], attributes[key])
+          end
+        end
+      end
+      
+      # Nicely formats the configurations into yaml with messages and
+      # declaration class divisions.
+      def format_yaml
+        lines = []
+        declarations.each_pair do |declaration_class, keys|
+          lines << "# #{declaration_class} configuration#{keys.length > 2 ? 's' : ''}"
+          
+          class_name = declaration_class.to_s
+          class_path = class_name.underscore
+          source_file = Dependencies.search_for_file(class_path)
+
+          Tap::Support::TDoc.document(source_file)
+          class_doc = Tap::Support::TDoc[declaration_class]
+          configurations = (class_doc == nil ? [] : class_doc.configurations)
+          
+          keys[1..-1].each do |key|
+            value = default[key]
+            attribs = attributes[key]
+            message = ""
+            configurations.each do |config|
+              if config.name == key.to_s
+                message = config.comment
+                break
+              end
+            end
+
+            # yaml adds a header and a final newline which should be removed:
+            #   {'key' => 'value'}.to_yaml           # => "--- \nkey: value\n"
+            #   {'key' => 'value'}.to_yaml[5...-1]   # => "key: value"
+            yaml = {key.to_s => value}.to_yaml[5...-1]
+            #yaml = "##{yaml}" if value.nil?
+
+            lines << case 
+            when message == nil || message.empty?  
+              # if there is no message, simply add the yaml
+              yaml
+            when yaml !~ /\r?\n/ && message !~ /\r?\n/ && yaml.length < 20 && message.length < 30
+              # shorthand ONLY if the config and message can be expressed in a single line
+              message = message.gsub(/^#\s*/, "")
+              "%-20s # %s" % [yaml, message]
+            else
+              # comment out new lines and add the message
+              message = message.gsub(/\n#\s*/, "\n# ")
+              lines << "# #{message}"
+              yaml
+            end
+          end
+          
+          # add a spacer line
+          lines << ""
+        end
+        
+        lines.join("\n")
+      end
+      
+
+      protected
+      
+      attr_writer :declarations, :default, :attributes 
+
+    end
+  end
+end

data/lib/tap/support/tdoc.rb

@@ -0,0 +1,198 @@
+require 'tap/support/tdoc/config_attr'
+require 'singleton'
+
+module Tap
+  module Support
+    
+    # == Overview
+    # TDoc hooks into and extends RDoc to make task documentation available for command line
+    # applications as well as for inclusion in RDoc html.  In particular, TDoc makes available
+    # documentation for Task configurations, when they are present.  TDoc provides an extension
+    # to the standard RDoc HTMLGenerator and template.  
+    #
+    # == Usage
+    # To generate task documentation with configuration information, TDoc must be loaded and 
+    # the appropriate flags passed to rdoc .  Essentially what you want is:
+    #
+    #   % rdoc --fmt tdoc --template tap/support/tdoc/tdoc_html_template [file_names....]
+    #
+    # Unfortunately, there is no way to load or require a file into the rdoc utility directly; the 
+    # above code causes an 'Invalid output formatter' error.  However, TDoc is easy to utilize 
+    # from a Rake::RDocTask:
+    #
+    #   require 'rake'
+    #   require 'rake/rdoctask'
+    #
+    #   desc 'Generate documentation.'
+    #   Rake::RDocTask.new(:rdoc) do |rdoc|
+    #     require 'tap/support/tdoc'
+    #     rdoc.template = 'tap/support/tdoc/tdoc_html_template' 
+    #     rdoc.options << '--fmt' << 'tdoc'
+    #  
+    #     # specify whatever else you need
+    #     # rdoc.rdoc_files.include(...)
+    #   end
+    #
+    # Now execute the rake task like:
+    #
+    #   % rake rdoc
+    #
+    # TDoc may also be utilized programatically, but you should be aware that RDoc in Ruby
+    # can raise errors and/or cause namespace conflicts (see below).
+    #
+    # == Implementation
+    # RDoc is a beast to utilize in a  non-standard way.  One way to make RDoc parse unexpected
+    # flags like 'config_accessor' or the 'c' config specifier is to use the '--accessor' option
+    # (see 'rdoc --help' or the RDoc documentation for more details).  
+    #
+    # TDoc hooks into the '--accessor' parsing process to pull out configuration attributes and
+    # format them into their own Configuration section on an RDoc html page.  When 'tdoc' is
+    # specified as an rdoc option, TDoc in effect sets accessor flags for all the standard Task
+    # configuration methods, and then extends the RDoc::RubyParser handle these specially.  
+    #
+    # If 'tdoc' is not specified as the rdoc format, TDoc does not affect the RDoc output.
+    # Similarly, the configuration attributes will not appear in the output unless you specify a 
+    # template that utilizes them.
+    #
+    # == Namespace conflicts
+    # RDoc creates a namespace conflict with other libraries that define RubyToken and RubyLex
+    # in the Object namespace (the prime example being IRB).  TDoc checks for such a conflict
+    # and redfines the RDoc RubyToken and RubyLex within the RDoc namespace. Essentially:
+    #
+    #   RubyToken => RDoc::RubyToken
+    #   RubyLex => RDoc::RubyLex
+    #
+    # The redefinition should not affect the existing RubyToken and RubyLex constants, but if 
+    # you directly use the RDoc versions after loading TDoc, you should be aware that they must 
+    # be accessed through the new constants.  Unfortunatley the trick is not seamless.  The RDoc 
+    # RubyLex makes a few calls to the RubyLex class method 'debug?'... these will be issued to 
+    # the existing RubyLex method and not RDoc::RubyLex.debug?
+    #
+    # In addition, because of the RubyLex calls, the RDoc::RubyLex cannot be fully hidden when 
+    # TDoc is loaded before the conflicting RubyLex; you cannot load TDoc before loading IRB 
+    # without raising warnings.  I hope to submit a patch for RDoc to stop this nonsense in the 
+    # future.
+    #
+    # On the plus side, you can now access/use RDoc within irb by requiring 'tap/support/tdoc'.
+    # 
+    class TDoc 
+      include Singleton
+      
+      attr_accessor :stats, :options, :documented_files, :load_paths
+      
+      def initialize
+        reinitialize  
+      end
+      
+      def reinitialize(argv=['--fmt', 'tdoc', '--quiet'])
+        @documented_files = []
+        @tl = RDoc::TopLevel::reset
+        @stats = RDoc::Stats.new
+        @options = Options.instance
+        @options.parse(argv, RDoc::RDoc::GENERATORS)
+        @load_paths = $:
+      end
+      
+      class << self
+        
+        def search_for_files(path_suffix)
+          # modified from 'activesupport/dependencies'
+          path_suffix = path_suffix + '.rb' unless path_suffix.ends_with? '.rb'
+         
+          files = instance.load_paths.collect do |root|
+            path = File.join(root, path_suffix)
+            File.file?(path) ? path : nil
+          end.compact
+        end
+        
+        def search_for_source_files(klass)
+          source_files = search_for_files(klass.to_s.underscore)
+          while klass.superclass.kind_of?(Tap::Task)
+            klass = klass.superclass
+            break if klass.configurations.empty?
+            source_files.concat(search_for_files(klass.to_s.underscore))
+          end
+          
+          source_files.uniq
+        end
+        
+        def document(*filepaths)
+          filepaths.each do |filepath|
+            next if filepath == nil || instance.documented_files.include?(filepath) || !File.exists?(filepath)
+
+            tl = RDoc::TopLevel.new(filepath)
+            parser = RDoc::RubyParser.new(tl, filepath, File.read(filepath), instance.options, instance.stats)
+            parser.scan
+            instance.documented_files << filepath
+          end
+        end
+        
+        def find_class_or_module_named(name)
+          RDoc::TopLevel.all_classes_and_modules.each do |c|
+            res = c.find_class_or_module_named(name) 
+            return res if res
+          end
+          nil
+        end
+      
+        def [](klass)      
+          name = klass.to_s
+          res = find_class_or_module_named(name)
+
+          # If no result was found, try to document a sourcefile
+          # from the standard filepath and search again 
+          if res == nil 
+            source_files = klass.respond_to?(:source_files) ? klass.source_files : []
+            source_files = search_for_source_files(klass) if source_files.empty?
+    
+            unless source_files.empty?
+              document(*source_files) 
+              res = find_class_or_module_named(name)
+            end
+          end
+          
+          res
+        end
+
+        def usage(program_file, sections=[], keep_section_headers=false)
+          comment = []
+          File.open(program_file) do |file|
+            while line = file.gets
+              case line
+              when /^\s*$/ 
+                # skip leading blank lines
+                comment.empty? ? next : break
+              when /^\s*# ?(.*)/m
+                comment << $1
+              end
+            end
+          end
+          
+          unless sections.empty?
+            sections_hash = {}
+            current_section = nil
+            comment.each do |line|
+              case line
+              when /^s*=+(.*)/
+                current_section = []
+                current_section << line if keep_section_headers
+                sections_hash[$1.strip] = current_section
+              else
+                current_section << line unless current_section.nil?
+              end
+            end
+            
+            comment = []
+            sections.each do |section|
+              next unless sections_hash.has_key?(section)
+              comment.concat(sections_hash[section])
+            end
+          end
+          
+          comment.join('')
+        end
+      end
+    end
+  end
+end
+