tap-tasks 0.1.0 → 0.2.0

data/History

@@ -1,3 +1,9 @@
+== 0.2.0 / 2009-05-25
+
+Updates for use with Tap-0.17.0
+
+* added configurable inspect method to inspect
+
 == 0.1.0 / 2009-03-23
 
 Initial release with:

data/README

@@ -1,14 +1,31 @@
-= Tap Tasks
+= {Tap Tasks}[http://tap.rubyforge.org/tap-tasks]
 
+  task n. a piece of work to be done or undertaken
+  
 A set of standard Tap tasks.
 
 == Description
 
-Tap Tasks is a standard library of utility tasks.
+A standard library of utility tasks, for example tasks to dump/load results as
+{YAML}[http://www.yaml.org/]. {Tap-Tasks}[http://tap.rubyforge.org/tap-tasks]
+is a part of the {Tap-Suite}[http://tap.rubyforge.org/tap-suite]. Check out
+these links for documentation, development, and bug tracking.
+
+* Website[http://tap.rubyforge.org] 
+* Lighthouse[http://bahuvrihi.lighthouseapp.com/projects/9908-tap-task-application/tickets]
+* Github[http://github.com/bahuvrihi/tap/tree/master] 
+* {Google Group}[http://groups.google.com/group/ruby-on-tap]
+
+== Usage
+
+Usage is the same as for any tasks.
+
+  % tap run -- load/yaml "{key: value}" --: inspect
+  {"key" => "value"}
 
 == Installation
 
-Tap Tasks is available as a gem on RubyForge[http://rubyforge.org/projects/tap].  Use:
+Tap-Tasks is available as a gem on RubyForge[http://rubyforge.org/projects/tap].  Use:
 
   % gem install tap-tasks
   

data/lib/tap/tasks/argv.rb

@@ -1,6 +1,8 @@
+require 'tap/task'
+
 module Tap
   module Tasks
-    # :startdoc::manifest provides a handle to ARGV
+    # :startdoc::task provides a handle to ARGV
     #
     # Simply returns ARGV.  This task can be a useful hook when executing
     # saved workflows via run (given that all arguments after the workflow

data/lib/tap/tasks/dump/inspect.rb

@@ -1,22 +1,28 @@
-require 'tap/dump'
+require 'tap/tasks/dump'
 
 module Tap
   module Tasks
-    module Dump
+    class Dump < Tap::Task
       
-      # :startdoc::manifest inspect and dump an object
+      # :startdoc::task inspect and dump an object
       #
-      # Dumps objects to a file or IO using object.inspect.  See the default
-      # tap dump task for more details.
+      # Dumps objects to a file or IO using object.inspect.  An alternate
+      # method can be specified for inspection using the inspect_method
+      # config.
       #
       #   % tap run -- load/yaml "{key: value}" --: inspect
       #   {"key"=>"value"}
       #
-      class Inspect < Tap::Dump
+      #   % tap run -- load string --: inspect -m length
+      #   6
+      #
+      class Inspect < Dump
+        
+        config :inspect_method, 'inspect', :short => :m    # The inspection method
         
         # Dumps the object to io using obj.inspect
         def dump(obj, io)
-          io.puts obj.inspect
+          io.puts obj.send(inspect_method)
         end
       end
     end

data/lib/tap/tasks/dump/yaml.rb

@@ -1,19 +1,18 @@
-require 'tap/dump'
+require 'tap/tasks/dump'
 
 module Tap
   module Tasks
-    module Dump
+    class Dump < Tap::Task
       
-      # :startdoc::manifest dumps data as YAML
+      # :startdoc::task dumps data as YAML
       #
-      # Dumps workflow results to a file or IO as YAML.  See the default tap
-      # dump task for more details.
+      # Dumps workflow results to a file or IO as YAML.
       #
       #   % tap run -- load/yaml "{key: value}" --: dump/yaml
-      #   ---
+      #   --- 
       #   key: value
       #
-      class Yaml < Tap::Dump
+      class Yaml < Dump
         
         # Dumps the object to io as YAML.
         def dump(obj, io)

data/lib/tap/tasks/file_task.rb

@@ -0,0 +1,383 @@
+require 'tap/tasks/file_task/shell_utils'
+
+module Tap
+  module Tasks
+    # FileTask is a base class for tasks that work with a file system.  FileTask
+    # tracks changes it makes so they may be rolled back to their original state.
+    # Rollback automatically occurs on an execute error.
+    #
+    #   File.open("file.txt", "w") {|file| file << "original content"}
+    #  
+    #   t = FileTask.intern do |task, raise_error|
+    #     task.mkdir_p("some/dir")              # marked for rollback
+    #     task.prepare("file.txt") do |file|    # marked for rollback
+    #       file << "new content"
+    #     end
+    #
+    #     # raise an error to start rollback
+    #     raise "error!" if raise_error
+    #   end
+    #
+    #   begin
+    #     t.execute(true)
+    #   rescue
+    #     $!.message                            # => "error!"
+    #     File.exists?("some/dir")              # => false
+    #     File.read("file.txt")                 # => "original content"
+    #   end
+    #
+    #   t.execute(false)
+    #   File.exists?("some/dir")                # => true
+    #   File.read("file.txt")                   # => "new content"
+    #
+    class FileTask < Task
+      include ShellUtils
+      
+      # The backup directory
+      config_attr :backup_dir, 'backup'            # The backup directory
+    
+      # A flag indicating whether or track changes
+      # for rollback on execution error
+      config :rollback_on_error, true, &c.switch   # Rollback changes on error
+    
+      def initialize(config={}, app=Tap::App.instance)
+        super
+        @actions = []
+      end
+    
+      # Initializes a copy that will rollback independent of self.
+      def initialize_copy(orig)
+        super
+        @actions = []
+      end
+    
+      # Returns the path, exchanging the extension with extname.  
+      # A false or nil extname removes the extension, while true 
+      # preserves the existing extension (and effectively does
+      # nothing).
+      #
+      #   t = FileTask.new
+      #   t.basepath('path/to/file.txt')           # => 'path/to/file'
+      #   t.basepath('path/to/file.txt', '.html')  # => 'path/to/file.html'
+      #
+      #   t.basepath('path/to/file.txt', false)    # => 'path/to/file'
+      #   t.basepath('path/to/file.txt', true)     # => 'path/to/file.txt'
+      #
+      # Compare to basename.
+      def basepath(path, extname=false)
+        case extname
+        when false, nil then path.chomp(File.extname(path))
+        when true then path
+        else Root::Utils.exchange(path, extname)
+        end
+      end
+    
+      # Returns the basename of path, exchanging the extension 
+      # with extname.  A false or nil extname removes the
+      # extension, while true preserves the existing extension.
+      #
+      #   t = FileTask.new
+      #   t.basename('path/to/file.txt')           # => 'file.txt'
+      #   t.basename('path/to/file.txt', '.html')  # => 'file.html'
+      #
+      #   t.basename('path/to/file.txt', false)    # => 'file'
+      #   t.basename('path/to/file.txt', true)     # => 'file.txt'
+      #
+      # Compare to basepath.
+      def basename(path, extname=true)
+        basepath(File.basename(path), extname)
+      end
+    
+      # Constructs a filepath using the dir and the specified paths.
+      #
+      #   t = FileTask.new
+      #   t.filepath('data', "result.txt")      # => File.expand_path("data/tap/tasks/file_task/result.txt")
+      #
+      def filepath(dir, *paths)
+        File.expand_path(File.join(dir, *paths))
+      end
+    
+      # Makes a backup filepath relative to backup_dir by using name, the
+      # basename of filepath, and an index. 
+      #
+      #   t = FileTask.new({:backup_dir => "/backup"}, "name")
+      #   t.backup_filepath("path/to/file.txt", time)     # => "/backup/name/file.0.txt"
+      #   
+      def backup_filepath(path)
+        extname = File.extname(path)
+        backup_path = filepath(backup_dir, File.basename(path).chomp(extname))
+        next_indexed_path(backup_path, 0, extname)
+      end
+
+      # Returns true if all of the targets are up to date relative to all of the
+      # listed sources. Single values or arrays can be provided for both targets
+      # and sources.
+      #
+      # Returns false (ie 'not up to date') if app.force is true.
+      #
+      #--
+      # TODO: add check vs date reference (ex config_file date)
+      def uptodate?(targets, sources=[])
+        if app && app.force
+          log_basename(:force, targets)
+          false
+        else
+          targets = [targets] unless targets.kind_of?(Array)
+          sources = [sources] unless sources.kind_of?(Array)
+        
+          targets.each do |target|
+            return false unless FileUtils.uptodate?(target, sources)
+          end 
+          true
+        end
+      end
+    
+      # Makes a backup of path to backup_filepath(path) and returns the backup path.
+      # If backup_using_copy is true, the backup is a copy of path, otherwise the
+      # file or directory at path is moved to the backup path.  Raises an error if
+      # the backup path already exists.
+      #
+      # Backups are restored on rollback.
+      #
+      #   file = "file.txt"
+      #   File.open(file, "w") {|f| f << "file content"}
+      #
+      #   t = FileTask.new
+      #   backup_file = t.backup(file)
+      #       
+      #   File.exists?(file)                       # => false
+      #   File.exists?(backup_file)                # => true
+      #   File.read(backup_file)                   # => "file content"
+      #
+      #   File.open(file, "w") {|f| f << "new content"}
+      #   t.rollback
+      #
+      #   File.exists?(file)                       # => true
+      #   File.exists?(backup_file   )             # => false
+      #   File.read(file)                          # => "file content"
+      #
+      def backup(path, backup_using_copy=false)
+        return nil unless File.exists?(path)
+        
+        source = File.expand_path(path)
+        target = backup_filepath(source)
+        raise "backup already exists: #{target}" if File.exists?(target)
+      
+        mkdir_p File.dirname(target)
+      
+        log :backup, "#{source} to #{target}", Logger::DEBUG
+        if backup_using_copy
+          FileUtils.cp(source, target)
+        else
+          FileUtils.mv(source, target)
+        end
+      
+        actions << [:backup, source, target]
+        target
+      end
+    
+      # Creates a directory and all its parent directories. Directories created
+      # by mkdir_p removed on rollback.
+      def mkdir_p(dir)
+        dir = File.expand_path(dir)
+        
+        dirs = []
+        while !File.exists?(dir)
+          dirs.unshift(dir)
+          dir = File.dirname(dir)
+        end
+        
+        dirs.each {|d| mkdir(d) }
+      end
+    
+      # Creates a directory. Directories created by mkdir removed on rollback.
+      def mkdir(dir)
+        dir = File.expand_path(dir)
+      
+        unless File.exists?(dir)
+          log :mkdir, dir, Logger::DEBUG
+          FileUtils.mkdir(dir)
+          actions << [:make, dir]
+        end
+      end
+    
+      # Prepares the path by backing up any existing file and ensuring that
+      # the parent directory for path exists.  If a block is given, a file
+      # is opened and yielded to it (as in File.open).  Prepared paths are
+      # removed and the backups restored on rollback.
+      #
+      # Returns the expanded path.
+      def prepare(path, backup_using_copy=false) 
+        raise "not a file: #{path}" if File.directory?(path)
+        path = File.expand_path(path)
+
+        if File.exists?(path)
+         # backup or remove existing files
+          backup(path, backup_using_copy)
+        else
+          # ensure the parent directory exists
+          # for non-existant files 
+          mkdir_p File.dirname(path)
+        end
+        log :prepare, path, Logger::DEBUG
+        actions << [:make, path]
+      
+        if block_given?
+          File.open(path, "w") {|file| yield(file) }
+        end
+      
+        path
+      end
+    
+      # Removes a file.  If a directory is provided, it's contents are removed
+      # recursively.  Files and directories removed by rm_r are restored
+      # upon an execution error.
+      def rm_r(path) 
+        path = File.expand_path(path)
+      
+        backup(path, false)
+        log :rm_r, path, Logger::DEBUG
+      end
+    
+      # Removes an empty directory.  Directories removed by rmdir are restored
+      # upon an execution error.
+      def rmdir(dir)
+        dir = File.expand_path(dir)
+      
+        unless Root::Utils.empty?(dir)
+          raise "not an empty directory: #{dir}"
+        end
+      
+        backup(dir, false)
+        log :rmdir, dir, Logger::DEBUG
+      end
+    
+      # Removes a file.  Directories cannot be removed by this method.
+      # Files removed by rm are restored upon an execution error.
+      def rm(path) 
+        path = File.expand_path(path)
+      
+        unless File.file?(path)
+          raise "not a file: #{path}"
+        end
+      
+        backup(path, false)
+        log :rm, path, Logger::DEBUG
+      end
+    
+      # Copies source to target.  Files and directories copied by cp are
+      # restored upon an execution error.
+      def cp(source, target)
+        target = File.join(target, File.basename(source)) if File.directory?(target)
+        prepare(target)
+      
+        log :cp, "#{source} to #{target}", Logger::DEBUG
+        FileUtils.cp(source, target)
+      end
+    
+      # Copies source to target.  If source is a directory, the contents
+      # are copied recursively.  If target is a directory, copies source
+      # to target/source.  Files and directories copied by cp are restored
+      # upon an execution error.
+      def cp_r(source, target)
+        target = File.join(target, File.basename(source)) if File.directory?(target)
+        prepare(target)
+      
+        log :cp_r, "#{source} to #{target}", Logger::DEBUG
+        FileUtils.cp_r(source, target)
+      end
+    
+      # Moves source to target.  Files and directories moved by mv are
+      # restored upon an execution error.
+      def mv(source, target, backup_source=true)
+        backup(source, true) if backup_source
+        prepare(target)
+      
+        log :mv, "#{source} to #{target}", Logger::DEBUG
+        FileUtils.mv(source, target)
+      end
+    
+      # Rolls back any actions capable of being rolled back.
+      #
+      # Rollback is forceful.  For instance if you make a folder using
+      # mkdir, rollback will remove the folder and all files within it
+      # even if they were not added by self.
+      def rollback
+        while !actions.empty?
+          action, source, target = actions.pop
+
+          case action
+          when :make
+            log :rollback, "#{source}", Logger::DEBUG
+            FileUtils.rm_r(source)
+          when :backup
+            log :rollback, "#{target} to #{source}", Logger::DEBUG
+            dir = File.dirname(source)
+            FileUtils.mkdir_p(dir) unless File.exists?(dir)
+            FileUtils.mv(target, source, :force => true)
+          else
+            raise "unknown action: #{[action, source, target].inspect}"
+          end
+        end
+      end
+    
+      # Removes backup files. Cleanup cannot be rolled back and prevents
+      # rollback of actions up to when cleanup is called.  If cleanup_dirs
+      # is true, empty directories containing the backup files will be
+      # removed.
+      def cleanup(cleanup_dirs=true)
+        actions.each do |action, source, target|
+          if action == :backup
+            log :cleanup, target, Logger::DEBUG
+            FileUtils.rm_r(target) if File.exists?(target)
+            cleanup_dir(File.dirname(target)) if cleanup_dirs
+          end
+        end
+        actions.clear
+      end
+    
+      # Removes the directory if empty, and all empty parent directories. This
+      # method cannot be rolled back.
+      def cleanup_dir(dir)
+        while Root::Utils.empty?(dir)
+          log :rmdir, dir, Logger::DEBUG
+          FileUtils.rmdir(dir)
+          dir = File.dirname(dir)
+        end
+      end
+    
+      # Logs the given action, with the basenames of the input paths.  
+      def log_basename(action, paths, level=Logger::INFO)
+        msg = [paths].flatten.collect {|path| File.basename(path) }.join(',')
+        log(action, msg, level)
+      end
+    
+      def call(*_inputs)
+        actions.clear
+      
+        begin
+          super
+        rescue(Exception)
+          rollback if rollback_on_error
+          raise
+        end
+      end
+    
+      protected
+    
+      # An array tracking actions (backup, rm, mv, etc) performed by self,
+      # allowing rollback on an execution error.  Not intended to be
+      # modified manually.
+      attr_reader :actions
+    
+      private 
+
+      # utility method for backup_filepath; increments index until the
+      # path base.indexext does not exist.
+      def next_indexed_path(base, index, ext) # :nodoc:
+        path = sprintf('%s.%d%s', base, index, ext)
+        File.exists?(path) ? next_indexed_path(base, index + 1, ext) : path
+      end
+    end
+  end
+end

data/lib/tap/tasks/file_task/shell_utils.rb

@@ -0,0 +1,71 @@
+require 'tap/task'
+autoload(:Tempfile, 'tempfile')
+
+module Tap
+  module Tasks
+    class FileTask < Tap::Task
+      
+      # Provides several shell utility methods for calling programs.
+      #
+      # == Windows 
+      # MSDOS has command line length limits specific to the version of Windows being
+      # run (from http://www.ss64.com/nt/cmd.html):
+      #
+      # Windows NT:: 256 characters
+      # Windows 2000::  2046 characters
+      # Windows XP:: 8190 characters
+      #
+      # Commands longer than these limits fail, usually with something like: 'the input
+      # line is too long'
+      module ShellUtils
+
+        # Run the system command +cmd+, passing the result to the block, if given.
+        # Raises an error if the command fails. Uses the same semantics as 
+        # Kernel::exec and Kernel::system.
+        #
+        # Based on FileUtils#sh from Rake.
+        def sh(*cmd) # :yields: ok, status
+          ok = system(*cmd)
+
+          if block_given?
+            yield(ok, $?)
+          else
+            ok or raise "Command failed with status (#{$?.exitstatus}): [#{ cmd.join(' ')}]"
+          end
+        end
+      
+        # Runs the system command +cmd+ using sh, redirecting the output to the 
+        # specified file path.  Uses the redirection command:
+        #
+        #   "> \"#{path}\" 2>&1 #{cmd}"
+        #
+        # This redirection has been tested on Windows, OS X, and Fedora.  See 
+        # http://en.wikipedia.org/wiki/Redirection_(Unix) for pointers on
+        # redirection.  This style of redirection SHOULD NOT be used with
+        # commands that contain other redirections.  
+        def redirect_sh(cmd, path, &block) # :yields: ok, status
+          sh( "> \"#{path}\" 2>&1 #{cmd}", &block)
+        end
+      
+        # Runs the system command +cmd+ and returns the output as a string.
+        def capture_sh(cmd, quiet=false, &block) # :yields: ok, status, tempfile_path
+          tempfile = Tempfile.new('shell_utils')
+          tempfile.close
+          redirect_sh(cmd, tempfile.path) do |ok, status|
+            if block_given?
+              yield(ok, $?, tempfile.path)
+            else
+              ok or raise %Q{Command failed with status (#{$?.exitstatus}): [#{cmd}]
+-------------- command output -------------------
+#{File.read(tempfile.path)}
+-------------------------------------------------
+}
+            end
+          end
+        
+          quiet == true ? "" : File.read(tempfile.path)
+        end
+      end
+    end
+  end
+end

data/lib/tap/tasks/glob.rb

@@ -0,0 +1,38 @@
+require 'tap/task'
+
+module Tap
+  module Tasks
+    # :startdoc::task globs for files
+    #
+    # Globs the input patterns for matching patterns.  Matching files are
+    # returned as an array.
+    #
+    #   % tap run -- glob * --: dump/yaml
+    #
+    class Glob < Tap::Task
+      
+      config :filters, [], &c.list(&c.regexp)     # regexp filters for results
+      config :unique, true, &c.switch             # ensure results are unique
+      config :files, true, &c.switch              # glob for files
+      config :dirs, false, &c.switch              # glob for directories
+      
+      def process(*patterns)
+        results = []
+        patterns.each do |pattern|
+          Dir[pattern].each do |path|
+            next if !files && File.file?(path)
+            next if !dirs && File.directory?(path)
+            
+            case path
+            when *filters then next
+            else results << path
+            end
+          end
+        end
+        
+        results.uniq! if unique
+        results
+      end
+    end
+  end
+end

data/lib/tap/tasks/load/yaml.rb

@@ -1,19 +1,18 @@
-require 'tap/load'
+require 'tap/tasks/load'
 
 module Tap
   module Tasks
-    module Load
+    class Load < Tap::Task
       
-      # :startdoc::manifest loads data as YAML
+      # :startdoc::task loads data as YAML
       #
-      # Loads data from the input IO as YAML.  See the default tap load task
-      # for more details.
+      # Loads data from the input IO as YAML.
       #
       #   % tap run -- load/yaml "{key: value}" --: dump/yaml
-      #   ---
+      #   --- 
       #   key: value
       #
-      class Yaml < Tap::Load
+      class Yaml < Load
         
         # Loads data from io as YAML.
         def load(io)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: tap-tasks
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Simon Chiang
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-23 00:00:00 -06:00
+date: 2009-05-25 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -20,7 +20,17 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.12.4
+        version: 0.17.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: tap-test
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.0
     version: 
 description: 
 email: simon.a.chiang@gmail.com
@@ -33,10 +43,13 @@ extra_rdoc_files:
 - README
 - MIT-LICENSE
 files: 
+- lib/tap/tasks/file_task/shell_utils.rb
 - lib/tap/tasks/argv.rb
 - lib/tap/tasks/dump/inspect.rb
 - lib/tap/tasks/dump/yaml.rb
 - lib/tap/tasks/load/yaml.rb
+- lib/tap/tasks/glob.rb
+- lib/tap/tasks/file_task.rb
 - tap.yml
 - History
 - README
@@ -50,7 +63,7 @@ rdoc_options:
 - -S
 - -N
 - --title
-- Tap Tasks
+- Tap-Tasks
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement