tap 0.12.4 → 0.17.0

data/lib/tap/file_task.rb

@@ -1,384 +0,0 @@
-require 'tap/support/shell_utils'
-
-module Tap
-  
-  # 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 Tap::Support::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={}, name=nil, app=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.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, name, and the specified paths.
-    #
-    #   t = FileTask.new
-    #   t.name                                # => "tap/file_task"
-    #   t.filepath('data', "result.txt")      # => File.expand_path("data/tap/file_task/result.txt")
-    #
-    def filepath(dir, *paths)
-      File.expand_path(File.join(dir, name, *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.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.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.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
-    
-    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
-    
-    # Clears actions so that a failure will not affect previous executions
-    def before_execute
-      actions.clear
-    end
-    
-    # Removes made files/dirs and restores backed-up files upon 
-    # an execute error.
-    def on_execute_error(original_error)
-      rollback if rollback_on_error
-      raise original_error
-    end
-    
-    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

data/lib/tap/generator/arguments.rb

@@ -1,13 +0,0 @@
-module Tap
-  module Generator
-    
-    # A special type of Lazydoc::Arguments that shifts off the standard 'm'
-    # argument on generator manifest methods, to properly reflect how may
-    # arguments the generator should receive.
-    class Arguments < Lazydoc::Arguments
-      def arguments(shift_manifest_arg=true)
-        shift_manifest_arg ? @arguments[1..-1] : @arguments
-      end
-    end
-  end
-end

data/lib/tap/generator/base.rb

@@ -1,176 +0,0 @@
-require 'tap'
-require 'tap/generator/manifest'
-require 'tap/generator/arguments'
-
-module Tap
-  module Generator
-    
-    # :startdoc:::-
-    # Base provides the basic structure of a generator and custom generators
-    # inherit from it.  Base is patterned after the {Ruby on Rails}[http://rubyonrails.org/] 
-    # generators, but obviously takes on all the advantages of Tasks.
-    #
-    # === Usage
-    #
-    # Tap generators define a manifest method that defines what files and
-    # directories are created by the generator.  Then, at execution time,
-    # a mixin with the appropriate funtion (ie Generate or Destory) is 
-    # overlaid to figure out how to roll those actions forward or backwards.
-    #
-    # Unlike typical tasks, generators must be named like '<Name>Generator' and
-    # are identified using the ::generator flag rather than ::manifest.  These
-    # requirements make generators available to the generate/destroy commands
-    # and not run.
-    #
-    # Typically, generators live in a directory structure like this:
-    #
-    #   sample
-    #   |- sample_generator.rb
-    #   `- templates
-    #       `- template_file.erb
-    #
-    # And take the form:
-    #
-    #   [sample/sample_generator.rb]
-    #   require 'tap/generator/base'
-    #
-    #   # SampleGenerator::generator generates a directory, and two files
-    #   #
-    #   # An extended description of the
-    #   # generator goes here...
-    #   #
-    #   class SampleGenerator < Tap::Generator::Base
-    #
-    #     config :key, 'value'       # a sample config
-    #
-    #     def manifest(m, *args)
-    #       # make a directory
-    #       m.directory('path/to/dir')
-    #
-    #       # make a file
-    #       m.file('path/to/file.txt') do |file|
-    #         file << "some content"
-    #       end
-    #
-    #       # template a file using config
-    #       m.template('path/to/result.txt', 'template_file.erb', config.to_hash)
-    #     end
-    #   end
-    #
-    # As with any task, generators can have configurations and take arguments
-    # specified by manifest (minus the 'm' argument which is standard).  
-    # Creating directories and files is straightforward, as above.  Template
-    # generates a target file using the source file in the templates' directory;
-    # any attributes specified by the last argument will be available in the erb
-    # template.
-    # :startdoc:::+
-    class Base < Tap::Task
-      lazy_attr :manifest, 'generator'
-      lazy_attr :args, :manifest
-      lazy_register :manifest, Arguments
-      
-      config :destination_root, Dir.pwd       # The destination root directory
-      config :pretend, false, &c.flag         # Run but rollback any changes.
-      config :force, false, &c.flag           # Overwrite files that already exist.
-      config :skip, false, &c.flag            # Skip files that already exist.
-      
-      # The generator-specific templates directory.  By default:
-      # 'path/to/name/templates' for 'path/to/name/name_generator.rb'
-      attr_accessor :template_dir
-      
-      # The IO used to pull prompt inputs (default: $stdin)
-      attr_accessor :prompt_in
-      
-      # The IO used to prompt users for input (default: $stdout)
-      attr_accessor :prompt_out
-      
-      def initialize(*args)
-        super
-        @prompt_in = $stdin
-        @prompt_out = $stdout
-        @template_dir = File.dirname(self.class.source_file) + '/templates'
-      end
-      
-      # Builds the manifest, then executes the actions of the manifest.
-      # Process returns the results of iterate, which normally will be
-      # an array of files and directories created (or destroyed) by self.
-      def process(*argv)
-        actions = []
-        manifest(Manifest.new(actions), *argv)
-        
-        iterate(actions) do |action, args, block|
-          send(action, *args, &block)
-        end
-      end
-      
-      # Overridden in subclasses to add actions to the input Manifest.
-      # Any arguments passed to process will be passed to manifest
-      # unchanged.
-      def manifest(m, *argv)
-        raise NotImplementedError
-      end
-      
-      # Peforms each of the input actions in order, and collects the
-      # results.  The process method returns these results.
-      def iterate(actions)
-        actions.collect {|action| yield(action) }
-      end
-      
-      # Constructs a path relative to destination_root.
-      def path(*paths)
-        File.expand_path(File.join(*paths), destination_root)
-      end
-      
-      # Peforms a directory action (ex generate or destroy).  Must be
-      # overridden by one of the action mixins (ex Generate or Destroy).
-      def directory(target, options={})
-        raise NotImplementedError
-      end
-    
-      # Peforms a file action (ex generate or destroy).  Calls to file specify
-      # input for a target by providing a block; the block recieves an IO and
-      # pushes content to it.  Must be overridden by one of the action mixins
-      # (ex Generate or Destroy).
-      def file(target, options={}) # :yields: io
-        raise NotImplementedError
-      end
-      
-      # Makes (or destroys) the root and each of the targets, relative
-      # to root.  Options are passed onto directory.
-      def directories(root, targets, options={})
-        directory(root, options)
-        targets.each do |target|
-          directory(File.join(root, target), options)
-        end
-      end
-      
-      # Makes (or destroys) the target by templating the source using
-      # the specified attributes.  Source is expanded relative to
-      # template_dir.  Options are passed onto file.
-      def template(target, source, attributes={}, options={})
-        template_path = File.expand_path(source, template_dir)
-        templater = Support::Templater.new(File.read(template_path), attributes)
-        
-        file(target, options) do |file| 
-          file << templater.build
-        end
-      end
-      
-      # Yields each source file under template_dir to the block, with
-      # a target path of the source relative to template_dir.
-      def template_files
-        Dir.glob(template_dir + "/**/*").sort.each do |source|
-          next unless File.file?(source)
-          
-          target = Tap::Root.relative_filepath(template_dir, source)
-          yield(source, target)
-        end
-      end
-      
-      # Logs the action with the relative filepath from Dir.pwd to path.
-      def log_relative(action, path)
-        log(action, Root.relative_filepath(Dir.pwd, path))
-      end
-    end
-  end
-end