tap 0.8.0 → 0.9.0

data/lib/tap/file_task.rb

@@ -1,15 +1,17 @@
 module Tap
   
+  # == Overview
+  #
   # FileTask provides methods for creating/modifying files such that you can
   # rollback changes if an error occurs.  In addition, FileTask provides a 
   # method to infer filepaths within the standard Tap directory structure.  
   #
-  # == Creating Files/Rolling Back Changes
+  # === Creating Files/Rolling Back Changes
   #
   # FileTask tracks which files to roll back using the added_files array
   # and the backed_up_files hash.  On an execute error, all added files are
-  # removed and then all backed up files (backed_up_files keys) are restored  
-  # using the corrsponding backup files (backed_up_files values). 
+  # removed and then all backed up files (backed_up_files.keys) are restored  
+  # using the corresponding backup files (backed_up_files.values). 
   # 
   # For consistency, all filepaths in added_files and backed_up_files should 
   # be expanded using File.expand_path.  The easiest way to ensure files are
@@ -19,7 +21,7 @@ module Tap
   #   # this file will be backed up and restored
   #   File.open("file.txt", "w") {|f| f << "original content"}
   #  
-  #   t = FileTask.new do |task, inputs|
+  #   t = FileTask.new do |task|
   #     task.mkdir("some/dir")                         # marked for rollback
   #     task.prepare("file.txt", "path/to/file.txt")   # marked for rollback
   #
@@ -41,71 +43,39 @@ module Tap
   #     File.read("file.txt")                 # => "original content"
   #   end
   #
-  #--
-  # TODO - make cleanup into remove_backup_files and simply remove this 
-  # configuration. People will figure it out themselves if they want that to happen.
-  #
-  # The FileTask configurations modify the default backup and restore behavior.
-  # 
-  # backup_dir:: The app directory alias for backups (default :backup)
-  # backup_timestamp::  A strftime format string used as a timestamp for backup
-  #                     files (default "%Y%m%d_%H%M%S")
-  # rollback_on_error:: Controls whether or not added and backed up files are
-  #                     rolled back on error (default true)
-  # cleanup_after_execute:: If true, backed up files will be removed after a 
-  #                          successful execution (default false)
-  #++
   class FileTask < Task
+    include Tap::Support::ShellUtils
+    
     autoload(:FileUtils, "fileutils")
     
-    class << self
-      
-      # A batch File.open method.  If a block is given, each file in the list will be 
-      # opened the open files passed to the block.  Files are automatically closed when 
-      # the block returns.  If no block is given, the open files are returned.
-      #
-      #   FileTask.open(["one.txt", "two.txt"], "w") do |one, two|
-      #     one << "one"
-      #     two << "two"
-      #   end
-      #
-      #   File.read("one.txt")                 # => "one"
-      #   File.read("two.txt")                 # => "two"
-      #
-      # Note that open normally takes and passes a list (ie an Array).  If you provide
-      # a single argument, it will be translated into an Array, and passed AS AN ARRAY
-      # to the block.
-      #
-      #   FileTask.open("file.txt", "w") do |array|
-      #     array.first << "content"
-      #   end
-      #
-      #   File.read("file.txt")                # => "content"
-      def open(list, mode="rb")
-        open_files = []
-        begin
-          [list].flatten.map {|path| path.to_str }.each do |filepath| 
-            open_files << File.open(filepath, mode)
-          end
-
-          block_given? ? yield(open_files) : open_files
-        ensure
-          open_files.each {|file| file.close } if block_given?
-        end
-      end
-    end
-      
-    write_inheritable_attribute(:backup_dir, :backup)  
-    class_inheritable_accessor(:backup_dir)
+    # A block used to infer filepaths. (see FileTask#filepath)
+    attr_reader :inference_block
     
-    write_inheritable_attribute(:backup_timestamp, "%Y%m%d_%H%M%S")  
-    class_inheritable_accessor(:backup_timestamp)
+    # A hash of backup (source, target) pairs, such that the
+    # backed-up files are backed_up_files.keys and the actual
+    # backup files are backed_up_files.values.  All filepaths
+    # in backed_up_files should be expanded.
+    attr_reader :backed_up_files
     
-    write_inheritable_attribute(:rollback_on_error, true)  
-    class_inheritable_accessor(:rollback_on_error)
+    # An array of files added during task execution.  
+    attr_reader :added_files
     
-    attr_reader :inference_block, :backed_up_files, :added_files
-    attr_accessor :dirname, :backup_dir, :backup_timestamp, :rollback_on_error
+    # The directory name used when infering filepaths.  By
+    # default dirname for an unbatched task is task.name,
+    # or "#{task.name}_#{batch_index}" for a batched task.
+    # (see FileTask#default_dirname)
+    attr_accessor :dirname
+    
+    # The backup directory, defaults to the class backup_dir 
+    config :backup_dir, :backup
+    
+    # A timestamp format used to mark backup files, defaults 
+    # to the class backup_timestamp 
+    config :backup_timestamp, "%Y%m%d_%H%M%S"
+    
+    # A flag indicating whether or not to rollback changes on 
+    # error, defaults to the class rollback_on_error 
+    config :rollback_on_error, true
     
     def initialize(*args)
       super
@@ -114,10 +84,56 @@ module Tap
         task.dirname = task.default_dirname
         task.backed_up_files = {}
         task.added_files = []
-        task.backup_dir = self.class.backup_dir
-        task.backup_timestamp = self.class.backup_timestamp
-        task.rollback_on_error = self.class.rollback_on_error
+        task.inference_block = nil
+      end
+    end
+    
+    # A batch File.open method.  If a block is given, each file in the list will be 
+    # opened the open files passed to the block.  Files are automatically closed when 
+    # the block returns.  If no block is given, the open files are returned.
+    #
+    #   task.open(["one.txt", "two.txt"], "w") do |one, two|
+    #     one << "one"
+    #     two << "two"
+    #   end
+    #
+    #   File.read("one.txt")                 # => "one"
+    #   File.read("two.txt")                 # => "two"
+    #
+    # Note that open normally takes and passes a list (ie an Array).  If you provide
+    # a single argument, it will be translated into an Array, and passed AS AN ARRAY
+    # to the block.
+    #
+    #   task.open("file.txt", "w") do |array|
+    #     array.first << "content"
+    #   end
+    #
+    #   File.read("file.txt")                # => "content"
+    def open(list, mode="rb")
+      open_files = []
+      begin
+        [list].flatten.map {|path| path.to_str }.each do |filepath| 
+          open_files << File.open(filepath, mode)
+        end
+
+        block_given? ? yield(open_files) : open_files
+      ensure
+        open_files.each {|file| file.close } if block_given?
+      end
+    end
+    
+    # Returns the basename of path, exchanging the extension 
+    # with extname, if provided.
+    #
+    #   task.basename('path/to/file.txt')           # => 'file.txt'
+    #   task.basename('path/to/file.txt', '.html')  # => 'file.html'
+    def basename(path, extname=nil)
+      basename = File.basename(path)
+      unless extname == nil
+        extname = $1 if extname =~ /^\.?(.*)/
+        basename = "#{basename.chomp(File.extname(basename))}.#{extname}"
       end
+      basename
     end
     
     # Sets a block to perform path inference.  Raises an error if inference_block 
@@ -191,7 +207,7 @@ module Tap
       else
         targets = [targets] unless targets.kind_of?(Array)
         sources = [sources] unless sources.kind_of?(Array)
-        sources << config_file 
+        sources << config_file unless config_file == nil
         targets.each do |target|
           return false unless FileUtils.uptodate?(target, sources)
         end 
@@ -330,10 +346,10 @@ module Tap
           dir = File.dirname(dir)
         end
       
-        make_paths.reverse_each do |dir|
-          log :mkdir, dir, Logger::DEBUG 
-          FileUtils.mkdir(dir) 
-          added_files << dir 
+        make_paths.reverse_each do |path|
+          log :mkdir, path, Logger::DEBUG 
+          FileUtils.mkdir(path) 
+          added_files << path 
         end
       end
     end
@@ -467,8 +483,12 @@ module Tap
       end
       removed
     end
-
-    def rollback
+    
+    # Rolls back changes by removing added_files and restoring backed_up_files.
+    # Rollback is performed on an execute error if rollback_on_error == true,
+    # but is provided as a separate method for flexibility when needed.
+    # Yields errors to the block, which must be provided.
+    def rollback # :yields: error
       added_files.dup.each do |filepath| 
         begin
           case
@@ -495,9 +515,10 @@ module Tap
       end
     end
     
-    def cleanup(pattern=nil)
+    # Removes backed-up files matching the pattern.
+    def cleanup(pattern=/.*/)
       backed_up_files.each do |filepath, target|
-        next unless pattern == nil || target =~ pattern
+        next unless target =~ pattern
         
         # the filepath needs to be added to added_files
         # before it can be removed by rm
@@ -507,39 +528,17 @@ module Tap
       end 
     end
     
-    # Run the system command +cmd+. If multiple arguments are given the command
-    # is not run with the shell (same semantics as Kernel::exec and Kernel::system).
-    #
-    # Example:
-    #   sh %{ls -ltr}
-    #
-    #   sh 'ls', 'file with spaces'
-    #
-    #   # check exit status after command runs
-    #   sh %{grep pattern file} do |ok, res|
-    #     if ! ok
-    #       puts "pattern not found (status = #{res.exitstatus})"
-    #     end
-    #   end
-    #
-    def sh(*cmd, &block)
-      # based on sh from Rake
-      unless block_given?
-        block = lambda { |ok, status|
-          ok or raise "Command failed with status (#{status.exitstatus}): [#{cmd.join(" ")}]"
-        }
-      end
-      log :sh, cmd.join(" ")
-      res = system(*cmd)
-      block.call(res, $?)
-    end
-    
     # Logs the given action, with the basenames of the input filepaths.  
     def log_basename(action, filepaths, level=Logger::INFO)
-      msg = filepaths.collect {|filepath| File.basename(filepath) }.join(',')
+      msg = case filepaths
+      when Array then filepaths.collect {|filepath| File.basename(filepath) }.join(',')
+      else
+        File.basename(filepaths)
+      end
+      
       log(action, msg, level)
     end
-     
+    
     protected
 
     attr_writer :inference_block, :backed_up_files, :added_files
@@ -574,17 +573,15 @@ module Tap
       end
 
       # Re-raise the error if no rollback errors occured,
-      # otherwise, raise a RunError tracking the restore
-      # errors.
+      # otherwise, raise a RunError tracking the errors.
       if rollback_errors.empty?
         raise original_error
       else
-        raise Support::RunError.new(original_error, rollback_errors)
+        rollback_errors.unshift(original_error)
+        raise Support::RunError.new(rollback_errors)
       end
     end
     
-    protected
-    
     # Lifted from FileUtils
     def fu_list(arg)  
       [arg].flatten.map {|path| path.to_str }

data/lib/tap/generator.rb

@@ -21,7 +21,10 @@ module Rails # :nodoc:
       def self.use_tap_sources!
         reset_sources
         sources << PathSource.new(:builtin, "#{File.dirname(__FILE__)}/generator/generators")
-        sources << PathSource.new(:builtin, Tap::App.instance.filepath(:generators))
+        
+        Tap::Env.instance.config['generator_paths'].each do |path|
+          sources << PathSource.new(:builtin, path)
+        end
       end
     end
     

data/lib/tap/generator/generators/command/USAGE

@@ -0,0 +1,6 @@
+Description:
+    Generates a new Tap command under the cmd directory. Pass 
+    the command name, either CamelCased or under_scored.  The  
+    new command can be run from the command line using:
+    
+    % tap run <command name>

data/lib/tap/generator/generators/command/command_generator.rb

@@ -0,0 +1,17 @@
+module Tap::Generator::Generators
+  class CommandGenerator < Rails::Generator::NamedBase # :nodoc:
+    def initialize(*args)
+      super(*args)    
+      @destination_root  = Tap::App.instance[:root]
+      @app = Tap::App.instance
+  	end
+
+    def manifest
+      record do |m|
+        command_path = @app.relative_filepath(:root, @app[:cmd])
+        m.directory class_path.empty? ? command_path : File.join(command_path, class_path)
+        m.template "command.erb", File.join(command_path, class_name.underscore + ".rb")
+      end
+    end
+  end
+end

data/lib/tap/generator/generators/{script/templates/script.erb → command/templates/command.erb}

@@ -1,16 +1,12 @@
 # = Usage
-# tap <%= file_name %> {options} OTHER_ARGS...
+# tap <%= file_name %> {options} ARGS...
 #
 # = Description
-# Some informative description...
-#
-# = Information
-#
-# Developer:: <your name>
-# Homepage:: <your homepage>
-# Copyright (c):: <%= Time.now.strftime("%Y") %>, <copyright holders>
-# License:: MIT-LICENSE (http://www.opensource.org/licenses/mit-license.php) <or some other license...>
+# The default command simply prints the input arguments 
+# and application information, then exits.
 #
+
+require 'tap'
 require 'tap/script'
 
 app = Tap::App.instance   
@@ -21,13 +17,14 @@ app = Tap::App.instance
 
 opts = [
   ['--help', '-h', GetoptLong::NO_ARGUMENT, "Print this help."],
-  ['--debug', nil, GetoptLong::NO_ARGUMENT, "Specifes debug mode."]]
+  ['--debug', nil, GetoptLong::NO_ARGUMENT, "Specifies debug mode."]]
   
 Tap::Script.handle_options(*opts) do |opt, value| 
   case opt
   when '--help'
     puts Tap::Script.usage(__FILE__, "Usage", "Description", "Information", :keep_headers => false)
     puts
+    puts "Options:"
     puts Tap::Script.usage_options(opts)
     exit
     
@@ -40,3 +37,6 @@ end
 #
 # add your script code here
 #
+
+puts "Received: #{ARGV.join(', ')}"
+puts app.info

data/lib/tap/generator/generators/config/USAGE

@@ -0,0 +1,21 @@
+Description:
+    Generates a new config file for a Task.  The configurations, defaults, 
+    and documentation is determined from the task.rb file.  Pass the task 
+    name, either CamelCased or under_scored.
+    
+    Versioned config files can be generated as well.  Specify a version by 
+    appending the version to the task name.
+    
+Examples:
+    # generates the config file 'config/sample_task'  
+    # for SampleTask from 'lib/sample_task.rb'
+    % tap generate config SampleTask  
+    
+    # same, with alternate syntax
+    % tap generate config sample_task               
+    
+    # now with a version, the output config 
+    # file is 'config/sample_task-0.1.yml'
+    % tap generate config sample_task-0.1             
+    
+    

data/lib/tap/generator/generators/config/config_generator.rb

@@ -2,24 +2,34 @@ module Tap::Generator::Generators
   class ConfigGenerator < Rails::Generator::NamedBase # :nodoc:
     attr_accessor :formatted_yaml
 
-    def initialize(*args)
-      super(*args)    
-      @destination_root  = Tap::App.instance[:root]
+    def initialize(argv, options)
       @app = Tap::App.instance
+      name, @version = @app.deversion(argv[0])
+      argv[0] = name
+      
+      super(argv, options)    
+      
+      @destination_root  = Tap::App.instance[:root]
   	end
 
     def manifest
       record do |m|
-        task_name = class_path.empty? ? class_name : File.join(class_path, class_name)
-        task = @app.task(task_name)
+        task = @app.task(class_name)
         self.formatted_yaml = task.class.configurations.format_yaml
     
         config_path = @app.relative_filepath(:root, @app[:config])
+        
+        if @version == nil
+          # then get the next increment?
+          # Tap::App.vglob(File.join(config_path, class_name.underscore + '.yml'))
+        end
+        version = @version == nil ? '' : "-#{@version}"
+        
         m.directory File.join(config_path, class_path)
-        m.template "config.erb", File.join(config_path, class_name.underscore + ".yml")
+        m.template "config.erb", File.join(config_path, class_name.underscore + "#{version}.yml")
         
-        # TODO -- add versioning
       end
     end
+    
   end
 end