templater 0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Jonas Nicklas
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,199 @@
+= Templater
+
+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
+
+Each manifold has many generator, and each generator has many actions.
+
+== Example
+
+This is how to create a very simple system for generating things:
+
+    module MyGenerators
+
+      extend Templater::Manifold
+
+      class BlogGenerator < Templater::Generator
+
+        def self.source_root
+          File.join(File.dirname(__FILE__), 'templates')
+        end
+
+        template :blog, 'blog.rb'
+        file :me, 'me.jpg'
+
+      end
+
+      class WikiGenerator < Templater::Generator
+
+        def self.source_root
+          File.join(File.dirname(__FILE__), 'templates')
+        end
+
+        template :wiki, 'wiki.rb'
+        file :img, 'wiki.jpg'
+
+      end
+      
+      add :blog, BlogGenerator
+      add :wiki, WikiGenerator
+
+    end
+
+    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'.
+
+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.
+
+== Invoking other generators
+
+Generators can invoke other generators, a WikiBlog generator that creates both a Wiki and a Blog could look like this:
+
+    module MyGenerators
+
+      extend Templater::Manifold
+
+      class WikiBlogGenerator < Templater::Generator
+
+        invoke :wiki
+        invoke :blog
+
+      end
+      
+      add :wiki_blog, WikiBlogGenerator
+
+    end
+    
+It needs to source_root, since it has no actions. Not here that the generators are invoked by their name in the manifold, *not* by their class name. This gives the system a great deal of flexibility.
+
+== Automatically adding actions
+
+It can get tedious to declare each action, instead you can search in a given directory and automatically add all files to your generator, this is done with the glob! function.
+
+    class MyGenerator < Templater::Generator
+     
+      def self.source_root
+        File.join(File.dirname(__FILE__), 'templates')
+      end
+      
+      glob!
+    
+    end
+    
+This will search the source root and add all files as actions.
+
+== Templates
+
+There are a lot of ways of adding templates:
+
+    template :one_argument, 'source_and_destination.rb'
+  
+    template :two_arguments, 'source.rb', 'destination.rb'
+  
+    template :block do
+      source('source.rb')
+      destination(some_instance_method)
+    end
+  
+    template :expression, 'source.rb' '%some_instance_method%.rb'
+
+In the last example, the characters enclosed in percentage signs will be replaced with the results of the instance method +some_instance_method+
+
+Inside the templates normal ERB can be used. The templates are rendered in the same context as the generator instance, so generator instance methods can be called from inside the template.
+
+    <% if name %>
+    puts "My name is <%= name %>"
+    <% else %>
+    puts "I have no name"
+    <% end %>
+    
+IF you need to render templates where the result should contain actual erb, simply use a double percentage sign, this will prevent the statement from being executed.
+
+    <%= 2 + 2 %>
+    <%%= 2 + 2 %>
+
+will result in
+
+    4
+    <%= 2 + 2 %>
+
+== An advanced example
+
+A generator for creating a model class, such as it used by Merb or Rails, could look like this:
+
+    module Merb::Generators
+  
+      class ModelGenerator < ComponentGenerator
+
+        def self.source_root
+          File.join(super, 'model')
+        end
+    
+        desc <<-DESC
+          This is a model generator
+        DESC
+    
+        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)'
+    
+        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
+    
+        template :model, :orm => :none do
+          source('model.rbt')
+          destination('app/models/' + file_name + '.rb')
+        end
+    
+        template :model_activerecord, :orm => :activerecord do
+          source('model_activerecord.rbt')
+          destination('app/models/' + file_name + '.rb')
+        end
+    
+        template :model_datamapper, :orm => :datamapper do
+          source('model_datamapper.rbt')
+          destination('app/models/' + file_name + '.rb')
+        end
+    
+        template :model_sequel, :orm => :sequel do
+          source('model_sequel.rbt')
+          destination('app/models/' + file_name + '.rb')
+        end
+    
+        template :spec, :testing_framework => :rspec do
+          source('spec.rbt')
+          destination('spec/models/' + file_name + '_spec.rb')
+        end
+    
+        template :test_unit, :testing_framework => :test_unit do
+          source('test_unit.rbt')
+          destination('test/models/' + file_name + '_test.rb')
+        end
+    
+        def class_name
+          self.name.camel_case
+        end
+    
+        def test_class_name
+          self.class_name + "Test"
+        end
+    
+        def file_name
+          self.name.snake_case
+        end
+    
+      end
+  
+      add :model, ModelGenerator
+  
+    end

data/Rakefile

@@ -0,0 +1,69 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rubygems/specification'
+require 'rake/rdoctask'
+require 'date'
+
+PLUGIN = "templater"
+NAME = "templater"
+GEM_VERSION = "0.1"
+AUTHOR = "Jonas Nicklas"
+EMAIL = "jonas.nicklas@gmail.com"
+HOMEPAGE = "http://templater.rubyforge.org/"
+SUMMARY = "File generation system"
+
+spec = Gem::Specification.new do |s|
+  s.name = NAME
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README", "LICENSE", 'TODO']
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  s.require_path = 'lib'
+  s.autorequire = PLUGIN
+  s.files = %w(LICENSE README Rakefile TODO) + Dir.glob("{lib,spec}/**/*")
+  
+  s.add_dependency "highline", ">= 1.4.0"
+  s.add_dependency "diff-lcs", ">= 1.1.2"
+  # Templater uses facets only for a single instance_exec. This dependency might be a bit stupid.
+  s.add_dependency "facets"
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "install the plugin locally"
+task :install => [:package] do
+  sh %{sudo gem install pkg/#{NAME}-#{VERSION} --no-update-sources}
+end
+
+desc "create a gemspec file"
+task :make_spec do
+  File.open("#{GEM}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end
+
+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}
+  end
+  
+end
+
+desc 'Generate documentation for Templater.'
+Rake::RDocTask.new(:doc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = 'Templater'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('LICENSE')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODO

@@ -0,0 +1,5 @@
+TODO:
+Fix LICENSE with your name
+Fix Rakefile with your name and contact info
+Add your code to lib/templater.rb
+Add your Merb rake tasks to lib/templater/merbtasks.rb

data/lib/templater.rb

@@ -0,0 +1,44 @@
+path = File.dirname(__FILE__) + '/templater/'
+
+require 'rubygems'
+require 'highline'
+require "highline/import"
+require 'diff/lcs'
+require 'facets'
+
+
+require path + 'capture_helpers'
+require path + 'template'
+require path + 'file'
+require path + 'generator'
+require path + 'proxy'
+require path + 'manifold'
+require path + 'cli/parser'
+require path + 'cli/manifold'
+require path + 'cli/generator'
+require path + 'core_ext/string'
+
+require 'erb'
+
+module Templater
+  
+  class TemplaterError < StandardError #:nodoc:
+  end
+  class GeneratorError < TemplaterError #:nodoc:
+  end
+  class SourceNotSpecifiedError < TemplaterError #:nodoc:
+  end
+  class ArgumentError < GeneratorError #:nodoc:
+  end
+  class TooManyArgumentsError < ArgumentError #:nodoc:
+  end
+  class TooFewArgumentsError < ArgumentError #:nodoc:
+  end
+  class JustTheRightAmountOfArgumentsError < ArgumentError #:nodoc:
+  end
+  class MalformattedArgumentError < ArgumentError #:nodoc:
+  end
+  
+  VERSION = '0.1'
+  
+end

data/lib/templater/capture_helpers.rb

@@ -0,0 +1,62 @@
+module Templater
+  
+  # Stolen from merb-core. Merb-core is licensed under the MIT license as follows:
+
+  # Copyright (c) 2008 Ezra Zygmuntowicz
+  # 
+  # Permission is hereby granted, free of charge, to any person obtaining
+  # a copy of this software and associated documentation files (the
+  # "Software"), to deal in the Software without restriction, including
+  # without limitation the rights to use, copy, modify, merge, publish,
+  # distribute, sublicense, and/or sell copies of the Software, and to
+  # permit persons to whom the Software is furnished to do so, subject to
+  # the following conditions:
+  # 
+  # The above copyright notice and this permission notice shall be
+  # included in all copies or substantial portions of the Software.
+  # 
+  # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+  # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+  
+  # TODO: this should be specced in some way.
+  module CaptureHelpers #:nodoc:
+    
+    def _erb_buffer( the_binding )
+      @_buffer = eval( "_erbout", the_binding, __FILE__, __LINE__)
+    end
+    
+    def capture(*args, &block)
+      # get the buffer from the block's binding
+      buffer = _erb_buffer( block.binding ) rescue nil
+
+      # If there is no buffer, just call the block and get the contents
+      if buffer.nil?
+        block.call(*args)
+      # If there is a buffer, execute the block, then extract its contents
+      else
+        pos = buffer.length
+        block.call(*args)
+
+        # extract the block
+        data = buffer[pos..-1]
+
+        # replace it in the original with empty string
+        buffer[pos..-1] = ''
+
+        data
+      end
+    end
+
+    # DOC
+    def concat(string, binding)
+      _erb_buffer(binding) << string
+    end
+    
+  end
+  
+end

data/lib/templater/cli/generator.rb

@@ -0,0 +1,162 @@
+module Templater
+  
+  module CLI
+    
+    class Generator
+
+      def initialize(generator_name, destination_root, manifold, name, version)
+        @destination_root, @manifold, @name, @version = destination_root, manifold, name, version
+        @generator_name = generator_name
+        @generator_class = @manifold.generator(@generator_name)
+      end
+
+      def version
+        puts @version
+        exit
+      end
+
+      # outputs a helpful message and quits
+      def help
+        puts "Usage: #{@name} #{@generator_name} [options] [args]"
+        puts ''
+        puts @generator_class.desc
+        puts ''
+        puts @options[:opts]
+        puts ''
+        exit
+      end
+
+      def run(arguments)
+        generator_class = @generator_class # FIXME: closure wizardry, there has got to be a better way than this?
+        @options = Templater::CLI::Parser.parse(arguments) do |opts, options|
+          opts.separator "Options specific for this generator:"
+          # the reason this is reversed is so that the 'main' generator will always have the last word
+          # on the description of the option
+          generator_class.generators.reverse.each do |generator|
+            # Loop through this generator's options and add them as valid command line options
+            # so that they show up in help messages and such
+            generator.options.each do |option|
+              name = option[:name].to_s.gsub('_', '-')
+              if option[:options][:as] == :boolean
+                opts.on("--#{name}", option[:options][:desc]) do |s|
+                  options[option[:name]] = s
+                end                
+              else
+                opts.on("--#{name} OPTION", option[:options][:desc]) do |s|
+                  options[option[:name]] = s.to_sym
+                end
+              end
+            end
+          end
+        end
+
+        self.help if @options[:help]
+        self.help if arguments.first == 'help'
+        self.version if @options[:version]
+
+        # 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
+        end
+
+        if @options[:pretend] 
+          puts "Generating with #{@generator_name} generator (just pretending):"
+        else
+          puts "Generating with #{@generator_name} generator:" 
+        end
+        step_through_templates
+      end
+
+      def step_through_templates
+        @generator.actions.each do |action|
+          if action.identical?
+            say_status('identical', action, :blue)
+          elsif action.exists?
+            if @options[:force]
+              say_status('forced', action, :yellow)
+              action.invoke! unless @options[:pretend]
+            elsif @options[:skip]
+              say_status('skipped', action, :yellow)
+            else
+              say_status('conflict', action, :red)
+              conflict_menu(action)
+            end
+          else
+            say_status('added', action, :green)
+            action.invoke! unless @options[:pretend]
+          end
+        end
+      end
+
+      protected
+
+      def conflict_menu(template)
+        choose do |menu|
+          menu.prompt = "How do you wish to proceed with this file?"
+
+          menu.choice(:skip) do
+            say("Skipped file")
+          end
+          menu.choice(:overwrite) do
+            say("Overwritten")
+            template.invoke! unless @options[:pretend]
+          end
+          menu.choice(:render) do
+            puts "Rendering " + template.relative_destination
+            puts ""
+            # outputs each line of the file with the row number prepended
+            template.render.to_a.each_with_index do |line, i|
+              puts((i+1).to_s.rjust(4) + ':  ' + line)
+            end
+            puts ""
+            puts ""
+            conflict_menu(template)
+          end
+          menu.choice(:diff) do
+            puts "Showing differences for " + template.relative_destination
+            puts ""
+
+            diffs = Diff::LCS.diff(File.read(template.destination).to_s.to_a, template.render.to_a).first
+
+            diffs.each do |diff|
+              output_diff_line(diff)
+            end
+
+            puts ""
+            puts ""
+            conflict_menu(template)
+          end
+          menu.choice(:abort) do
+            say("Aborted!")
+            exit
+          end
+        end
+      end
+
+      def say_status(status, template, color = nil)
+        status_flag = "[#{status.to_s.upcase}]".rjust(12)
+        if color and not @options[:no_color]
+          say "<%= color('#{status_flag}', :#{color}) %>  " + template.relative_destination
+        else
+          say "#{status_flag}  " + template.relative_destination
+        end
+      end
+
+      def output_diff_line(diff)
+        case diff.action
+        when '-'
+          say "<%= color('-  #{diff.element.chomp}', :red) %>"
+        when '+'
+          say "<%= color('+  #{diff.element.chomp}', :green) %>"
+        else
+          say "#{diff.action}  #{diff.element.chomp}"
+        end
+      end
+
+    end
+    
+  end
+  
+end