Here, at Plataforma, we use a set of tools on our projects, which includes Inherited Resources, Remarkable and Formtastic. At some point, we were planning on creating generators for each of those tools but still they couldn’t play along. If I wanted a generator that uses all three projects, I needed to create a inherited_remarkable_formtastic generator which is not DRY at all.

For example, for those who wants to use Datamapper with Rspec, they need to call “ruby script/generate dm_rspec_model” instead of “ruby script/generate model”. Since Rails 3.0 is moving towards agnosticism, my GSoC proposal was exactly bring it to rails generators.

1. So, what about Thor?!

One day before the official coding period start, I was staring at this Thor post by Yehuda Katz. Thor is a rake replacement with support to options parsing:

At that point, I realized that a generator is nothing more than a scripting task (like rake or thor) with some extra methods which makes the creation and copy of files easy. Thor had several features which convinced me that it was the best solution to build generators on top of:

It has a powerful options parser;

Thor classes can be inherited and all tasks from the class are copied to the child;

Thor classes are self contained. The example above can be invoked straight from your ruby code as Speak.new.hello(“jose”).

Then I was able to create a ROADMAP to Thor:

Add actions like copy_file, template, empty_directory to Thor;

Move all user input and output logic to its own class, so anyone can customize it;

Extend even more Thor options parser to add support to hashes (as in Rails name:string age:integer on generators) and arrays;

Add an invocation mechanism, so I can invoke one task from another Thor task.

2. An example

Let’s see an example on how you can create your own generators with Thor. For example, a generators that stubs out a new gem structure:

You can see from the example above that we are inheriting from Thor::Group and not Thor. In Thor, each method corresponds to a task, which can be invoked on its own. In Thor::Group, you invoke all tasks at once, in the order they are declared. This is interesting because you split your script/generator into several methods. It improves readability and allows anyone to inherit from your generator and change just one step in the process.

The next step, on lines 4 and 5, is to define arguments and options for the class. Arguments are required to be given right after the executable while options are given with switches. The newgem above can be invoked as:

newgem remarkable

And it will create two files: “remarkable/lib/remarkable.rb”, “remarkable/test/remarkable_test.rb” and prompt the user (with the use of the method yes?) if we wants to copy the MITLICENSE. If you want to change the test framework, you can give it as an option:

newgem remarkable --test-framework=rspec

Now it generates “remarkable/lib/remarkable.rb” and “remarkable/spec/remarkable_spec.rb”.

The generation methods are kept into the Thor::Actions module, which is included on top of our class. It holds all the scripting methods, which are: copy_file, create_file, directory, empty_directory, get, inject_into_file and template. All those actions can be revoked, so Thor knows how to do and undo the process (like in script/generate and script/destroy).

Even more, some of Rails templates methods was moved to Thor, like: inside, run, run_ruby_script, gsub_file, append_file and prepend_file. So whenever creating scripts with Thor, those methods will be available to make your life easier.

Finally, all user iteration methods are handled by Thor::Shell classes by say, ask, yes? and no? methods. Thor ships with two Shell implementations: Basic and Color. If you mantain an IDE for Rails, you can build your own shell and make the user interaction through it.

3. What is more?

Thor is used as base in Rails::Generators, where Rails extend it to provide Rails specific functionalities, as hooks for ORM, Test framework and so on. This will be my talk subject on Rails Summit Latin America, 13th October, in São Paulo, Brazil.

If you can join us or not, be sure to grab our RSS feed and keep on checking, we will discuss about it here too.

If generators are created with thor, do you get the conflict resolution options that you currently get with rails generators when a file/folder already exists? (force, skip, show diff, etc)

José Valim

@drnic, yes! In thor, we have the Thor::Actions (with create_file, copy_file,template and so on) and the Thor::Shell. The thor actions only delegates to a file_collision method in the thor shell.

So besides providing a file collision menu by default, you can easily reimplement the file collision menu as you wish. 🙂 For example, Thor ships with two shell implementations, one basic and another with color. The former is only used on Windows (where terminal colors does not work by default).

José Valim

@drnic, yes! In thor, we have the Thor::Actions (with create_file, copy_file,template and so on) and the Thor::Shell. The thor actions only delegates to a file_collision method in the thor shell.

So besides providing a file collision menu by default, you can easily reimplement the file collision menu as you wish. 🙂 For example, Thor ships with two shell implementations, one basic and another with color. The former is only used on Windows (where terminal colors does not work by default).