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! The caveat to that is that it’s a modified version of ERB for the file names. The syntax is just %= … % and not <%= … %>. It’s just a little easier on the file system.

Let’s look at a more complex example:

dir:
  complex_generator.rb
  templates:
    app:
      views:
        %=param(:name).plural%.template: # or %=name.plural%.rb.template 
          hello_world.html.erb
      models:
        %=param(:name)%.rb.template # or %=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.

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.

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.

Contact

Please mail bugs, suggestions and patches to <[email protected]>.

On the web at: www.mackframework.com

License and Copyright

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.