bahuvrihi-tap 0.11.2 → 0.12.0

data/lib/tap/generator/arguments.rb

@@ -0,0 +1,9 @@
+module Tap
+  module Generator
+    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,95 @@
 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.  The 
+    # template function 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.
       def process(*argv)
         actions = []
         manifest(Manifest.new(actions), *argv)
@@ -35,38 +97,45 @@ 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)
+      # Peforms each of the input actions.  Overridden by one of the
+      # action mixins (ex Generate or Destory).
+      def iterate(actions)
         raise NotImplementedError
       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).  Must be
+      # overridden by one of the action mixins (ex Generate or Destroy).
       def file(target, options={})
         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 +145,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,34 +1,51 @@
 module Tap
   module Generator
+    
+    # A mixin defining how to run manifest actions in reverse.
     module Destroy
+      
+      # Iterates over the actions in reverse.
       def iterate(actions)
         actions.reverse_each {|action| yield(action) }
       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
       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
       end
       

data/lib/tap/generator/generate.rb

@@ -1,66 +1,82 @@
 module Tap
-  module Generator 
+  module Generator
+    
+    # A mixin defining how to run manifest actions.
     module Generate
+      
+      # Iterates over the actions in order.
       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
       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
+      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
+        prompt_out.print "overwrite #{target}? [Ynaiq] "
+        prompt_out.flush
+        case prompt_in.gets
         when /a/i
           self.force = true
         when /i/i
           self.skip = true
         when /q/i
-          $stdout.puts "aborting #{name}"
+          prompt_out.puts "aborting #{name}"
           raise SystemExit
         when /n/i then false
         when /y/i then true

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

@@ -17,10 +17,41 @@ module Tap::Generator::Generators
       task_class = const.constantize or raise "unknown task: #{name}"
       
       m.directory app['config']
-      m.file app.filepath('config', config_name + '.yml') do |file|
-        task_class.configurations.inspect((doc ? :doc : :nodoc), file)
-      end
+      dump(m, app.filepath('config', config_name), task_class.configurations)
+    end
+    
+    def template
+      path = File.expand_path(doc ? 'doc.erb' : 'nodoc.erb', template_dir)
+      File.read(path)
     end
     
+    def dump(m, path, configurations, &block)
+      non_nested_configurations = configurations.to_a.sort_by do |(key, config)|
+        config.attributes[:declaration_order] || 0
+      end.collect do |(key, config)|
+        default = config.default(false)
+        
+        if default.kind_of?(Configurable::DelegateHash)
+          # nest nested configs
+          dump(m, File.join(path, key), default, &block)
+          nil
+        else
+          # duplicate config so that any changes to it
+          # during templation will not propogate back
+          # into configurations
+          [key, config.dup]
+        end
+      end.compact
+      
+      if block_given?
+        yield(non_nested_configurations)
+      end
+      
+      m.file "#{path}.yml" do |file|
+        templater = Tap::Support::Templater.new(template)
+        templater.configurations = non_nested_configurations
+        file << templater.build
+      end
+    end
   end
 end