tap 0.11.1 → 0.12.0

data/lib/tap/generator/arguments.rb

@@ -0,0 +1,13 @@
+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,33 +1,98 @@
+require 'tap'
 require 'tap/generator/manifest'
+require 'tap/generator/arguments'
 
 module Tap
-  module Generator 
+  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
-      class << self
-        def lazydoc(resolve=true)
-          lazydoc = super(false)
-          lazydoc[self.to_s]['args'] ||= lazydoc.register_method(:manifest, Task::Args)
-          super
-        end
-      end
-      
-      Constant = Tap::Support::Constant
-      
-      lazy_attr :manifest, :generator
+      lazy_attr :manifest, 'generator'
+      lazy_attr :args, :manifest
+      lazy_register :manifest, Arguments
       
       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.
       
-      attr_accessor :file_task, :template_dir, :target_dir
+      # The generator-specific templates directory.  By default:
+      # 'path/to/name/templates' for 'path/to/name/name_generator.rb'
+      attr_accessor :template_dir
       
-      def initialize(config={}, name=nil, app=App.instance)
-        super(config, name, app)
-
-        @file_task = Tap::FileTask.new
+      # 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)
@@ -35,38 +100,47 @@ module Tap
         iterate(actions) do |action, args, block|
           send(action, *args, &block)
         end
-        
-        @target_dir = nil
-        file_task.added_files
-      end
-      
-      def log_relative(action, path)
-        log(action, app.relative_filepath(Dir.pwd, path))
       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
       
-      def iterate(action)
-        raise NotImplementedError
+      # 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
-    
+      
+      # 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
     
-      def file(target, options={})
+      # 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)
+        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)
@@ -76,13 +150,21 @@ module Tap
         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

data/lib/tap/generator/destroy.rb

@@ -1,35 +1,58 @@
 module Tap
   module Generator
+    
+    # A mixin defining how to run manifest actions in reverse.
     module Destroy
+      
+      # Iterates over the actions in reverse, and collects the results.
       def iterate(actions)
-        actions.reverse_each {|action| yield(action) }
+        results = []
+        actions.reverse_each {|action| results << yield(action) }
+        results
       end
       
+      # Removes the target directory if it exists.  Missing, non-directory and 
+      # non-empty targets are simply logged and not removed.  When pretend is
+      # true, removal is logged but does not actually happen.
+      #
+      # No options currently affect the behavior of this method. 
       def directory(target, options={})
-        target = File.expand_path(target, target_dir)
+        target = File.expand_path(target)
         
         case
         when !File.exists?(target)
           log_relative :missing, target
-        when !file_task.dir_empty?(target)
+        when !File.directory?(target)
+          log_relative 'not a directory', target
+        when !Root.empty?(target)
           log_relative 'not empty', target
         else
           log_relative :rm, target
-          file_task.added_files << File.expand_path(target)
-          file_task.rmdir(target) unless pretend    
+          FileUtils.rmdir(target) unless pretend
         end
+        
+        target
       end
       
+      # Removes the target file if it exists.  Missing and non-file and targets
+      # are simply logged and not removed.  When pretend is true, removal is 
+      # logged but does not actually happen.
+      #
+      # No options currently affect the behavior of this method.
       def file(target, options={})
-        target = File.expand_path(target, target_dir)
-        
-        if File.exists?(target)
-          log_relative :rm, target
-          file_task.added_files << File.expand_path(target)
-          file_task.rm(target) unless pretend
-        else
-          log_relative :missing, target
+        target = File.expand_path(target)
+        
+        case
+        when File.file?(target)
+          log_relative :rm, target
+          FileUtils.rm(target) unless pretend
+        when File.directory?(target)
+          log_relative 'not a file', target
+        else
+          log_relative :missing, target
         end
+        
+        target
       end
       
     end

data/lib/tap/generator/generate.rb

@@ -1,70 +1,91 @@
+autoload(:Tempfile, 'tempfile')
+
 module Tap
-  module Generator 
+  module Generator
+    
+    # A mixin defining how to run manifest actions.
     module Generate
-      def iterate(actions)
-        actions.each {|action| yield(action) }
-      end
-  
+      
+      # Creates the target directory if it doesn't exist.  When pretend is
+      # true, creation is logged but does not actually happen.
+      #
+      # No options currently affect the behavior of this method.
       def directory(target, options={})
-        target = File.expand_path(target, target_dir)
+        target = File.expand_path(target)
         
-        if File.exists?(target)
+        case
+        when File.exists?(target)
           log_relative :exists, target
         else
           log_relative :create, target
-          file_task.mkdir(target) unless pretend
+          FileUtils.mkdir_p(target) unless pretend
         end
+        
+        target
       end
-    
-      def file(target, options={})
-        source_file = Tempfile.new('generate')
-        yield(source_file) if block_given?
-        source_file.close
-        
-        source = source_file.path
-        target = File.expand_path(target, target_dir)
-        
-        copy_file = case
-        when !File.exists?(target)
-          log_relative :create, target
-          true
-        when FileUtils.cmp(source, target)
-          log_relative :exists, target
-          false
-        when force_file_collision?(target)
-          log_relative :force, target
-          true
-        else
-          log_relative :skip, target
-          false
-        end
-        
-        if copy_file && !pretend
-          file_task.prepare(target) 
-          FileUtils.mv(source, target)
+      
+      # Creates the target file; content may be added to the file by providing
+      # block.  If the target file already exists, the new and existing content
+      # is compared and the user will be prompted for how to handle collisions.
+      # All activity is logged.  When pretend is true, creation is logged but
+      # does not actually happen.
+      #
+      # No options currently affect the behavior of this method.
+      def file(target, options={})
+        source_file = Tempfile.new('generate')
+        yield(source_file) if block_given?
+        source_file.close
+        
+        source = source_file.path
+        target = File.expand_path(target)
+        
+        copy_file = true
+        msg = case
+        when !File.exists?(target)
+          :create
+        when FileUtils.cmp(source, target)
+          :exists
+        when force_file_collision?(target)
+          :force
+        else
+          copy_file = false
+          :skip
+        end
+        
+        log_relative msg, target
+        if copy_file && !pretend
+          dir = File.dirname(target)
+          FileUtils.mkdir_p(dir) unless File.exists?(dir) 
+          FileUtils.mv(source, target, :force => true)
         end
-      end
-      
-      protected
+        
+        target
+      end
+      
+      protected
       
       # Ask the user interactively whether to force collision.
       def force_file_collision?(target)
         return false if skip
         return true if force
         
-        $stdout.print "overwrite #{target}? [Ynaiq] "
-        $stdout.flush
-        case $stdin.gets
-        when /a/i
+        prompt_out.print "overwrite #{target}? [Ynaiq] "
+        prompt_out.flush
+        case prompt_in.gets.strip
+        when /^y(es)?$/i
+          true
+        when /^n(o)?$/i
+          false
+        when /^a(ll)?$/i
           self.force = true
-        when /i/i
+          true
+        when /^i(gnore)?$/i
           self.skip = true
-        when /q/i
-          $stdout.puts "aborting #{name}"
+          false
+        when /^q(uit)?$/i
+          prompt_out.puts "aborting"
           raise SystemExit
-        when /n/i then false
-        when /y/i then true
-        else force_file_collision?(destination)
+        else force_file_collision?(target)
         end
       end
     end

data/lib/tap/generator/generators/command/templates/command.erb

@@ -11,12 +11,12 @@ app = Tap::App.instance
 # handle options
 #
 
-OptionParser.new do |opts|
+ConfigParser.new do |opts|
   opts.separator ""
   opts.separator "options:"
 
   opts.on("-h", "--help", "Show this message") do
-    opts.banner = Tap::Support::Lazydoc.usage(__FILE__)
+    puts Lazydoc.usage(__FILE__)
     puts opts
     exit
   end
@@ -29,4 +29,4 @@ end.parse!(ARGV)
 #
 
 puts "Received: #{ARGV.join(', ')}"
-puts app.info
+puts app.info

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

@@ -6,21 +6,93 @@ module Tap::Generator::Generators
   # and documentation is determined from the task source file.
   class ConfigGenerator < Tap::Generator::Base
     
-    config :doc, true, &c.switch  # include documentation in the config
+    # Dumps a nested configuration.
+    DUMP_DELEGATES = lambda do |leader, delegate, block|
+      nested_delegates = delegate.default(false).delegates
+      indented_dump = Configurable::Utils.dump(nested_delegates, &block).gsub(/^/, "  ")
+      "#{leader}: \n#{indented_dump}"
+    end
+    
+    # Dumps configurations as YAML with documentation,
+    # used when the doc config is true.
+    DOC_FORMAT = lambda do |key, delegate|
+      # get the description
+      desc = delegate.attributes[:desc]
+      doc = desc.to_s
+      doc = desc.comment if doc.empty?
     
-    def env
-      Tap::Env.instance
+      # wrap as lines
+      lines = Lazydoc::Utils.wrap(doc, 50).collect {|line| "# #{line}"}
+      lines << "" unless lines.empty?
+      
+      if delegate.is_nest?
+        leader = "#{lines.join("\n")}#{key}"
+        DUMP_DELEGATES[leader, delegate, DOC_FORMAT]
+      else
+        default = delegate.default
+        
+        # setup formatting
+        leader = default == nil ? '# ' : ''
+        config = {key => default}.to_yaml[5..-1]
+        "#{lines.join("\n")}#{leader}#{config.strip}\n\n"
+      end
     end
-
-    def manifest(m, name, config_name=name)
-      const = env.tasks.search(name) or raise "unknown task: #{name}"
-      task_class = const.constantize or raise "unknown task: #{name}"
+    
+    # Dumps configurations as YAML without documentation, 
+    # used when the doc config is false.
+    NODOC_FORMAT = lambda do |key, delegate|
+      if delegate.is_nest?
+        DUMP_DELEGATES[key, delegate, NODOC_FORMAT]
+      else
+        default = delegate.default
       
-      m.directory app['config']
-      m.file app.filepath('config', config_name + '.yml') do |file|
-        task_class.configurations.inspect((doc ? :doc : :nodoc), file)
+        # setup formatting
+        leader = default == nil ? '# ' : ''
+        config = {key => default}.to_yaml[5..-1]
+        "#{leader}#{config.strip}\n"
       end
     end
     
+    config :doc, true, &c.switch        # include documentation in the config
+    config :nest, false, &c.switch      # generate nested config files
+    config :blanks, true, &c.switch     # allow generation of empty config files
+    
+    # Lookup the named task class.  Lookup happens through the active Env 
+    # instance, specifically using:
+    #
+    #   Env.instance.tasks.search(name)
+    #
+    # Raises an error if the name cannot be resolved to a task.
+    def lookup(name)
+      const = Tap::Env.instance.tasks.search(name) or raise "unknown task: #{name}"
+      const.constantize
+    end
+    
+    def manifest(m, name, config_name=nil)
+      # setup
+      tasc = lookup(name)
+      config_name ||= tasc.default_name
+      config_file = app.filepath('config', config_name)
+      config_file += ".yml" if File.extname(config_file).empty?
+      
+      # generate the dumps
+      dumps = Configurable::Utils.dump_file(tasc.configurations, config_file, nest, true, &format_block)
+      
+      # now put the dumps to the manifest
+      m.directory(app['config'])
+      
+      dumps.each do |path, content|
+        next if content.empty? && !blanks
+        m.file(path) do |file|
+          file << content
+        end
+      end
+    end
+    
+    # A hook to set a formatting block.  By default format_blocks
+    # returns DOC_FORMAT or NODOC_FORMAT as per the doc config.
+    def format_block
+      doc ? DOC_FORMAT : NODOC_FORMAT
+    end
   end
 end