templater 0.1.1 → 0.1.2

data/README

@@ -2,12 +2,24 @@
 
 Templater is a system for generating files. Templater has the ability to both copy files from A to B and also to render templates using ERB. Templater consists of four parts:
 
-- Actions (Files and Templates)
-- Generators
-- Manifolds
-- The command line interface
+- Actions (File copying routines, templates generation and directories creation routines).
+- Generators (set of rules).
+- Manifolds (generator suites).
+- The command line interface.
+
+Hierarchy is pretty simple: manifold has one or many public and private generators. Public ones are supposed to be called
+by end user. Generators have one or more action that specify what they do, where they take files, how they name resulting
+files and so forth.
+
+
+== Idea behind Templater
+
+Templater keeps declarations of generator inside it's body. You vary source and destinations of each action the way you want.
+There's no magical %variables% in filenames sprinkled across your generator, generator rules are simple, readable, concise
+and are in one place making it easy to take existing generator as example.
+
+This is how Templater is different from some other code/components generation frameworks.
 
-Each manifold has many generator, and each generator has many actions.
 
 == Example
 
@@ -18,14 +30,24 @@ This is how to create a very simple system for generating things:
       extend Templater::Manifold
 
       class BlogGenerator < Templater::Generator
-
+        # directory this generator uses as source root when searching
+				# for files, directories, templates
         def self.source_root
           File.join(File.dirname(__FILE__), 'templates')
         end
 
+				# uses blog.rbt template (note conventional trailing t)
+				# placing resulting file to blog.rb relatively to
+				# destination root
         template :blog, 'blog.rb'
+
+				# does simple copy of me.jpg placing resulting file to me.jpg relatively to
+				# destination root
         file :me, 'me.jpg'
 
+				# creates empty directory public/javascripts relatively to
+				# destination root
+				empty_directory :javascripts, File.join("public", "javascripts")
       end
 
       class WikiGenerator < Templater::Generator
@@ -38,17 +60,19 @@ This is how to create a very simple system for generating things:
         file :img, 'wiki.jpg'
 
       end
-      
+
+			# The generators are added to the manifold, and assigned the names 'wiki' and 'blog'.
+			# So you can call them <script name> blog merb-blog-in-10-minutes and
+			# <script name> blog merb-wiki-in-10-minutes, respectively
       add :blog, BlogGenerator
       add :wiki, WikiGenerator
 
     end
 
+		# registers manifold with command line interface
     MyGenerators.run_cli Dir.pwd, 'my_generators', '0.1', ARGV
   
-The generator classes override the source_root method to specify where templates will be located. All subclasses of Templater::Generator that have any actions must do this. The +template+ and +file+ methods add actions to the generator. In the first case, a template that is rendered with ERB and then put in its destination location, in the other case a file that is copied.
-
-The generators are added to the manifold, and assigned the names 'wiki' and 'blog'.
+The generator classes override the source_root method to specify where templates will be located. All subclasses of Templater::Generator that have any actions must do this. The +template+ and +file+ methods add actions to the generator. In the first case, a template that is rendered with ERB and then put in its destination location, in the other case a file that is copied. +empty_directory+ action creates empty directory under destination root.
 
 Neither manifolds or generators actually do anything by themselves, they are just abstract represenations. The last line invokes the command-line-interface, which fetches the desired generator, tells it to render its templates and checks with the user if there are any problems. The generators can easily be used without the command-line-interface, so it is easy to construct an alternative interface.
 
@@ -91,6 +115,9 @@ This will search the source root and add all files as actions.
 
 == Templates
 
+Templates are processed using generator instance scope as binding, so every instance method available on your
+generator is available in template body.
+
 There are a lot of ways of adding templates:
 
     template :one_argument, 'source_and_destination.rb'
@@ -135,17 +162,20 @@ A generator for creating a model class, such as it used by Merb or Rails, could
         def self.source_root
           File.join(super, 'model')
         end
-    
+
+				# description end users see next to generator name
         desc <<-DESC
           This is a model generator
         DESC
-    
+
+				# options generator takes, their metadata, like description or arguments type
         option :testing_framework, :desc => 'Specify which testing framework to use (spec, test_unit)'
         option :orm, :desc => 'Specify which Object-Relation Mapper to use (none, activerecord, datamapper, sequel)'
-    
+
+				# you may use shortcuts for first 4 option positions
         first_argument :name, :required => true
         second_argument :attributes, :as => :hash, :default => {}
-    
+
         invoke :migration do |generator|
           generator.new(destination_root, options.merge(:model => true), name, attributes)
         end

data/Rakefile

@@ -12,6 +12,11 @@ EMAIL = "jonas.nicklas@gmail.com"
 HOMEPAGE = "http://templater.rubyforge.org/"
 SUMMARY = "File generation system"
 
+
+#
+# ==== Gemspec and installation
+#
+
 spec = Gem::Specification.new do |s|
   s.name = NAME
   s.version = Templater::VERSION
@@ -38,9 +43,15 @@ Rake::GemPackageTask.new(spec) do |pkg|
   pkg.gem_spec = spec
 end
 
+desc "removes any generated content"
+task :clean do
+  FileUtils.rm_rf "clobber/*"
+  FileUtils.rm_rf "pkg/*"
+end
+
 desc "install the plugin locally"
-task :install => [:package] do
-  sh %{sudo gem install pkg/#{NAME}-#{VERSION} --no-update-sources}
+task :install => [:clean, :package] do
+  sh %{sudo gem install pkg/#{NAME}-#{Templater::VERSION} --no-update-sources}
 end
 
 desc "create a gemspec file"
@@ -54,11 +65,15 @@ namespace :jruby do
 
   desc "Run :package and install the resulting .gem with jruby"
   task :install => :package do
-    sh %{#{SUDO} jruby -S gem install pkg/#{NAME}-#{Merb::VERSION}.gem --no-rdoc --no-ri}
+    sh %{#{SUDO} jruby -S gem install pkg/#{NAME}-#{Templater::VERSION}.gem --no-rdoc --no-ri}
   end
   
 end
 
+#
+# ==== RDoc
+#
+
 desc 'Generate documentation for Templater.'
 Rake::RDocTask.new(:doc) do |rdoc|
   rdoc.rdoc_dir = 'doc'
@@ -67,4 +82,23 @@ Rake::RDocTask.new(:doc) do |rdoc|
   rdoc.rdoc_files.include('README')
   rdoc.rdoc_files.include('LICENSE')
   rdoc.rdoc_files.include('lib/**/*.rb')
-end
+end
+
+#
+# ==== RCov
+#
+
+desc "Run coverage suite"
+task :rcov do
+  require 'fileutils'
+  FileUtils.rm_rf("coverage") if File.directory?("coverage")
+  FileUtils.mkdir("coverage")
+  path = File.expand_path(Dir.pwd)
+  files = Dir["spec/**/*_spec.rb"]
+  files.each do |spec|
+    puts "Getting coverage for #{File.expand_path(spec)}"
+    command = %{rcov #{File.expand_path(spec)} --aggregate #{path}/coverage/data.data}
+    command += " --no-html" unless spec == files.last
+    `#{command} 2>&1`
+  end
+end

data/lib/templater.rb

@@ -10,6 +10,7 @@ require 'facets'
 require path + 'capture_helpers'
 require path + 'template'
 require path + 'file'
+require path + 'empty_directory'
 require path + 'generator'
 require path + 'proxy'
 require path + 'manifold'
@@ -39,6 +40,6 @@ module Templater
   class MalformattedArgumentError < ArgumentError #:nodoc:
   end
   
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
   
-end
+end

data/lib/templater/cli/generator.rb

@@ -57,8 +57,12 @@ module Templater
         # Try to instantiate a generator, if the arguments to it were incorrect: show a help message
         begin
           @generator = @generator_class.new(@destination_root, @options, *arguments)
-        rescue Templater::ArgumentError
-          self.help
+        rescue Templater::ArgumentError => e
+          if @options[:debug]
+            raise e
+          else
+            self.help
+          end
         end
 
         if @options[:pretend] 

data/lib/templater/cli/parser.rb

@@ -71,6 +71,10 @@ module Templater
           opts.on("--version", "Show the version") do
             options[:version] = true
           end
+          
+          opts.on("--debug", "Do not catch errors") do
+            options[:debug] = true
+          end
 
         end
       

data/lib/templater/empty_directory.rb

@@ -0,0 +1,53 @@
+module Templater
+  class EmptyDirectory
+
+    attr_reader :name, :destination
+    
+    def initialize(name, destination)
+      @name, @destination = name, destination
+    end
+
+    # Returns the destination path relative to Dir.pwd. This is useful for prettier output in interfaces
+    # where the destination root is Dir.pwd.
+    #
+    # === Returns
+    # String:: The destination relative to Dir.pwd
+    def relative_destination
+      @destination.sub(::Dir.pwd + ::File::SEPARATOR, '')
+    end
+
+    # Returns the contents of the source file as a String
+    #
+    # === Returns
+    # String:: The source file.
+    def render
+      ::File.read(source)
+    end
+
+    # Checks if the destination file already exists.
+    #
+    # === Returns
+    # Boolean:: true if the file exists, false otherwise.
+    def exists?
+      ::File.exists?(destination)
+    end
+  
+    # For empty directory this is in fact alias for exists? method.
+    # 
+    # === Returns
+    # Boolean:: true if it is identical, false otherwise.
+    def identical?
+      exists?
+    end
+  
+    # Renders the template and copies it to the destination.
+    def invoke!
+      ::FileUtils.mkdir_p(destination)
+    end
+    
+    # removes the destination file
+    def revoke!
+      ::FileUtils.rm_rf(::File.expand_path(destination))
+    end
+  end # EmptyDirectory
+end # Templater

data/lib/templater/file.rb

@@ -21,7 +21,7 @@ module Templater
     # === Returns
     # String:: The destination relative to Dir.pwd
     def relative_destination
-      @destination.sub(::Dir.pwd + '/', '')
+      @destination.sub(::Dir.pwd + ::File::SEPARATOR, '')
     end
 
     # Returns the contents of the source file as a String
@@ -60,4 +60,4 @@ module Templater
     end
   
   end
-end
+end

data/lib/templater/generator.rb

@@ -38,6 +38,16 @@ module Templater
       # Array[Hash{Symbol=>Object}]:: A list of invocations
       def invocations; @invocations ||= []; end
       
+      # Returns an array of hashes, where each hash describes a single empty directory created by generator.
+      #
+      # ==== Returns
+      # Array[Hash{Symbol=>Object}]:: A list of empty directories created by generator.
+      def empty_directories; @empty_directories ||= []; end
+
+
+
+      
+      
       # A shorthand method for adding the first argument, see +Templater::Generator.argument+
       def first_argument(*args); argument(0, *args); end
 
@@ -50,6 +60,10 @@ module Templater
       # A shorthand method for adding the fourth argument, see +Templater::Generator.argument+
       def fourth_argument(*args); argument(3, *args); end
 
+
+
+
+      
       # If the argument is omitted, simply returns the description for this generator, otherwise
       # sets the description to the passed string.
       #
@@ -244,6 +258,15 @@ module Templater
           :render => false
         }
       end
+      
+      def empty_directory(name, path = nil)
+        path = name.to_s unless path
+        
+        self.empty_directories << {
+          :name        => name,
+          :destination => path
+        }
+      end
                        
       # An easy way to add many templates to a generator, each item in the list is added as a
       # template. The provided list can be either an array of Strings or a Here-Doc with templates
@@ -304,11 +327,12 @@ module Templater
       # template_destination<Array[String]>:: A list of extensions. If a file has one of these
       #     extensions, it is considered a template and will be rendered with ERB.
       # options<Hash{Symbol=>Object}>:: A list of options.
-      def glob!(dir = nil, template_extensions = %w(rb css js erb html yml), options={})
+      def glob!(dir = nil, template_extensions = %w(rb css js erb html yml Rakefile TODO LICENSE README), options={})
         ::Dir[::File.join(source_root, dir.to_s, '**/*')].each do |action|
           unless ::File.directory?(action)
             action = action.sub("#{source_root}/", '')
-            if template_extensions.include?(::File.extname(action)[1..-1])
+            
+            if template_extensions.include?(::File.extname(action)[1..-1]) or template_extensions.include?(::File.basename(action))
               template(action.downcase.gsub(/[^a-z0-9]+/, '_').to_sym, action, action)
             else
               file(action.downcase.gsub(/[^a-z0-9]+/, '_').to_sym, action, action)
@@ -342,7 +366,12 @@ module Templater
         raise Templater::SourceNotSpecifiedError, "Subclasses of Templater::Generator must override the source_root method, to specify where source templates are located."
       end
       
-    end
+    end # end of eigenclass
+
+
+    #
+    # ==== Instance methods
+    #
     
     attr_accessor :destination_root, :arguments, :options
     
@@ -394,6 +423,14 @@ module Templater
     def file(name)
       self.files.find { |f| f.name == name }
     end
+
+    # Finds and returns all empty directories whose options match the generator options.
+    #
+    # === Returns
+    # [Templater::EmptyDirectory]:: The found empty directories that generator creates.
+    def empty_directory(name)
+      self.empty_directories.find { |d| d.name == name }
+    end
     
     # Finds and returns all templates whose options match the generator options.
     #
@@ -418,6 +455,16 @@ module Templater
       end
       files.compact
     end
+
+    # Finds and returns all empty directories generator creates.
+    #
+    # === Returns
+    # [Templater::File]:: The found files.
+    def empty_directories
+      self.class.empty_directories.map do |t|
+        Templater::Proxy.new(self, t[:name], nil, t[:destination], &t[:block]).to_empty_directory
+      end.compact
+    end    
     
     # Finds and returns all templates whose options match the generator options.
     #
@@ -445,7 +492,7 @@ module Templater
     # === Returns
     # [Templater::File, Templater::Template]:: The found templates and files.
     def actions
-      actions = templates + files
+      actions = templates + files + empty_directories
       actions += invocations.map { |i| i.actions }
       actions.flatten
     end
@@ -557,4 +604,4 @@ module Templater
     end
   end
   
-end
+end

data/lib/templater/proxy.rb

@@ -24,6 +24,11 @@ module Templater
       instance_eval(&@block) if @block
       Templater::File.new(@name, get_source, get_destination)
     end
+
+    def to_empty_directory
+      instance_eval(&@block) if @block
+      Templater::EmptyDirectory.new(@name, get_destination)
+    end
     
     def method_missing(method, *args, &block)
       if @generator
@@ -52,4 +57,4 @@ module Templater
     
   end
   
-end
+end

data/lib/templater/template.rb

@@ -25,7 +25,7 @@ module Templater
     # === Returns
     # String:: The destination relative to Dir.pwd
     def relative_destination
-      @destination.sub(::Dir.pwd + '/', '')
+      @destination.sub(::Dir.pwd + ::File::SEPARATOR, '')
     end
   
     # Renders the template using ERB and returns the result as a String.
@@ -64,4 +64,4 @@ module Templater
     end
       
   end
-end
+end

data/spec/empty_directory_spec.rb

@@ -0,0 +1,97 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe Templater::EmptyDirectory, '.new' do
+  it "sets name and destination" do
+    Templater::EmptyDirectory.new(:monkey, '/path/to/destination').
+      name.should == :monkey
+  end
+
+  it 'sets destination' do
+    Templater::EmptyDirectory.new(:monkey, '/path/to/destination').
+      destination.should == '/path/to/destination'    
+  end
+end
+
+
+
+
+describe Templater::EmptyDirectory, '#relative_destination' do
+  it "returns destination relative to the pwd" do
+    Dir.stub!(:pwd).and_return('/path/to')
+    file = Templater::EmptyDirectory.new(:monkey, '/path/to/destination/with/some/more/subdirs')
+    file.relative_destination.should == 'destination/with/some/more/subdirs'
+  end
+end
+
+
+
+
+describe Templater::EmptyDirectory, '#render' do
+  it 'does nothing for empty directories?'
+end
+
+
+
+
+describe Templater::EmptyDirectory, '#exists?' do
+  
+  it "should exist if the destination file exists" do  
+    file = Templater::EmptyDirectory.new(:monkey, result_path('erb.rbs'))
+    file.should be_exists
+  end
+  
+  it "should not exist if the destination file does not exist" do  
+    file = Templater::EmptyDirectory.new(:monkey, result_path('some_weird_file.rbs'))
+    file.should_not be_exists
+  end
+end
+
+
+
+describe Templater::EmptyDirectory, '#identical' do
+  it "should not be identical if the destination file doesn't exist" do  
+    file = Templater::EmptyDirectory.new(:monkey, result_path('some_weird/path/that_does/not_exist'))
+    file.should_not be_identical
+  end
+  
+  it "should not be identical if the destination file is not identical to the source file" do
+    file = Templater::EmptyDirectory.new(:monkey, result_path('simple_erb.rbs'))
+    file.should be_exists
+    file.should be_identical
+  end
+  
+  it "should be identical if the destination file is identical to the source file" do
+    file= Templater::EmptyDirectory.new(:monkey, result_path('file.rbs'))
+    file.should be_exists
+    file.should be_identical
+  end
+end
+
+
+
+describe Templater::EmptyDirectory, '#invoke!' do
+  it "should copy the source file to the destination" do
+    file = Templater::EmptyDirectory.new(:monkey, result_path('path/to/subdir/test2.rbs'))
+    
+    file.invoke!
+    
+    File.exists?(result_path('path/to/subdir/test2.rbs')).should be_true
+    
+    # cleanup
+    FileUtils.rm_rf(result_path('path'))
+  end
+end
+
+
+
+describe Templater::EmptyDirectory, '#revoke!' do
+  it "removes the destination directory" do
+    file = Templater::EmptyDirectory.new(:monkey, result_path('path/to/empty/subdir/'))
+    
+    file.invoke!
+    File.exists?(result_path('path/to/empty/subdir/')).should be_true
+    
+    file.revoke!
+    File.exists?(result_path('path/to/empty/subdir/')).should be_false
+  end
+end