genosaurus: A Ruby repository from dsutedja

=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.
dsutedja/genosaurus
