@@ -3,4 +3,5 @@ tmp *.log *.tmp pkg -*.gem \ No newline at end of file +*.gem +doc \ No newline at end of file .gitignore @@ -1,3 +1,117 @@ -README -======================================================================== -genosaurus was developed by: markbates +=Hello, and welcome to Genosaurus! + +Genosaurus is meant to be a very, very easy to use generation system for Ruby. It's simple and straightforward, yet offers plenty of flexibility in it's use. People use 'generators' all the time, and you either have to roll your own, or use some really cumbersome generator that some one else wrote, that is just way too difficult to use. Enter Genosaurus! + +==Installation + $ sudo gem install genosaurus + +==Getting Started + +===Implied Manifests +The easiest way to use Genosaurus is to let it do the work for you. Let's looked at what's called an 'implied' manifest: + + dir: + simple_generator.rb + templates: + hello_world.txt.template + +That's our folder structure. Now let's look at simple_generator.rb: + + require 'rubygems' + require 'genosaurus' + + class SimpleGenerator < Genosaurus + end + +Now if we run that generator: + + $irb: SimpleGenerator.run + +We should get a file called hello_world.txt generated in the current directory. Yes, it truly is that simple! + +With implied manifests our directory structure under 'templates' tells the whole story, and Genosaurus is smart enough to figure it out. All the file names, and the same goes for folders, need to end in .template, and Genosaurus will do the rest. + +All the files will go through ERB before they generated, so you can put all your lovely little dynamic goodies in there. File, and folder, names also get run through ERB so you can even make the file name dynamic too! + +Let's look at a more complex example: + + dir: + complex_generator.rb + templates: + app: + views: + <%=param(:name).plural%>.template: + hello_world.html.erb + models: + <%=param(:name)%>.rb.template + +Let's run our complex_generator.rb file: + + require 'rubygems' + require 'genosaurus' + + class ComplexGenerator < Genosaurus + require_param: name + end + +Now if we run that generator: + + $irb: ComplexGenerator.run("name" => "user") + +Now you should end up with the following: + + app: + views: + users: + hello_world.html.erb + models: + user.rb.template + +In the ComplexGenerator we told Genosaurus that we are requiring that the parameter, name, be passed into it. We are then using that parameter to generate the names of some files and folders. Pretty cool, eh? See how simple that is. + +Let's look at the manifest.yml file for our simple_generator example: + + template_1: + type: file + template_path: <%= File.join(templates_directory_path, "templates", "hello_world.txt.template") + output_path: hello_world.txt + +Pretty simple. We give the template a name, template_1, it really doesn't matter what it is, but Hash objects need keys. The 'type' parameter is either file or directory. The template_path is the path to the template. Finally, the output_path is the where you want the file to be generated. + +Let's look at our more complex example. We can change the directory structure a bit, since we really don't need ERB in the file names now: + + dir: + complex_generator.rb + templates: + hello_world.html.erb.template + model.rb.template + +Our manifest.yml file would look like this: + + hello_world_template: + type: file + template_path: <%= File.join(templates_directory_path, "templates", "hello_world.html.erb") + output_path: <%= File.join("app", "views", param(:name).plural, "hello_world.html.erb") %> + model_template: + type: file + template_path: <%= File.join(templates_directory_path, "templates", "model.html.erb") + output_path: <%= File.join("app", "models", "#{param(:name)}.rb") %> + +This will generate the exact same thing as our implied manifest. + +===Explicit Manifests +Explicit manifests are used when there is a manifest.yml supplied at the same level as the generator. If there is a manifest.yml file then implied manifests are not used. This means you have to define the entire generation process. This is great if you have a pretty complicated generator, as the manifest.yml is also sent through ERB before being loaded. + +==Contact +Please mail bugs, suggestions and patches to <bugs@mackframework.com>. + +On the web at: http://www.mackframework.com + +==License and Copyright +Copyright (C) 2008 Mark Bates, http://www.mackframework.com + +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 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. \ No newline at end of file README @@ -8,7 +8,7 @@ require 'rubyforge' require 'rubygems' require 'rubygems/gem_runner' -GEM_VERSION = "1.1.0" +GEM_VERSION = "1.1.1" GEM_NAME = "genosaurus" GEM_RUBYFORGE_PROJECT = "genosaurus" Rakefile @@ -4,22 +4,13 @@ require 'fileutils' require 'erb' require 'yaml' - -# All generator classes should extend this class if they're expected to be used by the rake generate:<generator_name> task. -# A generator must by name in the following style: <name>Generator. -# -# Example: -# class MyCoolGenerator < Genosaurus -# require_param :name, :foo -# end -# -# rake generate:my_cool # => calls MyCoolGenerator class Genosaurus include FileUtils class << self + # Instantiates a new Genosaurus, passing the ENV hash as options into it, runs the generate method, and returns the Genosaurus object. def run(options = ENV.to_hash) gen = self.new(options) gen.generate @@ -28,6 +19,8 @@ class Genosaurus end + # Takes any options needed for this generator. If the generator requires any parameters an ArgumentError exception will be + # raised if those parameters are found in the options Hash. The setup method is called at the end of the initialization. def initialize(options = {}) @options = options self.class.required_params.each do |p| @@ -35,47 +28,62 @@ class Genosaurus end @generator_name = self.class.name @generator_name_underscore = @generator_name.underscore - @generator_file_path = nil - @generator_directory_path = nil + @templates_directory_path = nil + @manifest_path = nil $".each do |f| if f.match(/#{@generator_name_underscore}\.rb$/) - @generator_file_path = f - @generator_directory_path = File.dirname(@generator_file_path) + @templates_directory_path = File.join(File.dirname(f), "templates") + @manifest_path = File.join(File.dirname(f), "manifest.yml") end end setup end - def generator_file_path - @generator_file_path + # Returns the path to the templates directory. + # IMPORTANT: The location of the templates_directory_path is VERY important! Genosaurus will attempt to find this location + # automatically, HOWEVER, if there is a problem, or you want to be special, you can override this method in your generator + # and have it return the correct path. + def templates_directory_path + @templates_directory_path end - def generator_directory_path - @generator_directory_path + # Returns the path to the manifest.yml. This is only used if you have a manifest.yml file, if there is no file, or this + # method returns nil, then an implied manifest is used based on the templates_directory_path contents. + # IMPORTANT: Genosaurus will attempt to find this location automatically, HOWEVER, if there is a problem, or you want to + # be special, you can override this method in your generator and have it return the correct path. + def manifest_path + @manifest_path end + # To be overridden in subclasses to do any setup work needed by the generator. def setup # does nothing, unless overridden in subclass. end + # To be overridden in subclasses to do work before the generate method is run. def before_generate end + # To be overridden in subclasses to do work after the generate method is run. + # This is a simple way to call other generators. def after_generate end + # Returns the manifest for this generator, which is used by the generate method to do the dirty work. + # If there is a manifest.yml, defined by the manifest_path method, then the contents of that file are processed + # with ERB and returned. If there is not manifest.yml then an implied manifest is generated from the contents + # of the templates_directory_path. def manifest ivar_cache do - yml = File.join(generator_directory_path, "manifest.yml") - if File.exists?(yml) + if File.exists?(manifest_path) # run using the yml file - template = ERB.new(File.open(yml).read, nil, "->") + template = ERB.new(File.open(manifest_path).read, nil, "->") man = YAML.load(template.result(binding)) else - files = Dir.glob(File.join(generator_directory_path, "**/*.template")) + files = Dir.glob(File.join(templates_directory_path, "**/*.template")) man = {} files.each_with_index do |f, i| - output_path = f.gsub(File.join(generator_directory_path, "templates"), "") + output_path = f.gsub(templates_directory_path, "") output_path.gsub!(".template", "") output_path.gsub!(/^\//, "") man["template_#{i+1}"] = { @@ -141,7 +149,8 @@ class Genosaurus mkdir_p(output_dir) puts "Created: #{output_dir}" end - + + # This does the dirty work of generation. def generate generate_callbacks do manifest.each_value do |info| lib/genosaurus.rb @@ -3,5 +3,5 @@ directory_1: output_path: beatles/albums/magical_mystery_tour template_1: type: file - template_path: <%= File.join(generator_directory_path, "templates", "fields.txt") %> + template_path: <%= File.join(templates_directory_path, "fields.txt") %> output_path: beatles/albums/magical_mystery_tour/lyrics/strawberry_fields_forever.lyrics \ No newline at end of file test/lib/strawberry_fields_generator/manifest.yml cd032a83eea270bf2fda7d6031acb52a375ba66e Mark Bates mark@markbates.com http://github.com/markbates/genosaurus/commit/91789f734b505884f1f5e87ed23781b8781a8d82 91789f734b505884f1f5e87ed23781b8781a8d82 2008-04-21T14:20:26-07:00 2008-04-21T14:20:26-07:00 Release 1.1.1: Better RDoc, README has examples, plus a little clean up. e167946326c529ff5bb2f29995adce8284c8adb1 Mark Bates mark@markbates.com