Getting Started

There are a few things that you need to know about thor to get started. For example, it uses a file name convention to load tasks, and you typically call your scripts via the thor command line, though this is not the only option.

File Names

To create a thor task, the first thing you need is a file ending with the .thor extension (a file named Thorfile works as well). This file can contain any standard ruby code, including the functionality provided by thor. When the thor command line tool is run, it will look for .thor files and load them up, making your tasks available.

A Simple Example

Create a file named test.thor and place the following code in it

class Test < Thor
  desc "example", "an example task"
  def example
    puts "I'm a thor task!"
  end
end

Once you have this created, you can run thor list from the command line and you should see the following output:

test
----
thor test:example  # an example task

Now run thor test:example from the command line. You should see I'm a thor task! output to the command line.

Breaking Down The Sample

There are several parts of this task that can be examined to understand what is happening.

First, the class name is used as the namespace for the task. Thor uses some standard ruby conventions to turn the class name into a namespace. If you change the class name to FooBar, for example, your task would now be listed as foo_bar:example.

Next, the desc method call is used to describe the task that we are creating. There are two parameters to the desc method. The first parameter should state the name of the task (the method) and any parameters that are provided to the method. The second option should be a plain text description of what this task does.

Last, the example method itself. Thor uses this method name as the actual task name. Therefore, when you rename the example method to widget, you end up with a task listing of test:widget.

Task Parameters

The following thor task defines one parameter on the task by adding a parameter to the method:

class Test < Thor
  desc "example FILE", "an example task that does something with a file"
  def example(file)
    puts "You supplied the file: #{file}"
  end
end

Note that the description has been updated to include the word 'FILE' in the first parameter. As stated previously, you should include the name of any required task parameters in the task description. This is used to produce help text that is useful to the end user.

Run thor help test:example to see the help text for the test:example task and you will see the following output:

Usage:
  thor test:example FILE

an example task that does something with a file

This indicated the requirement of a FILE parameter for the task.

Now when you run the task itself, with thor test:example my_file.rb you should see You supplied the file: my_file.rb.

If you run the script without a file supplied, you'll see a message saying you need to supply one: "example" was called incorrectly. Call as "thor test:example FILE".

Options For A Task

Thor also lets you provide named options for a task. There are several methods of doing this, and more detail can be found on the method options wiki page.

Put the following into your test.thor file:

class Test < Thor
  desc "example FILE", "an example task"
  method_option :delete, :aliases => "-d", :desc => "Delete the file after parsing it"
  def example(file)
    puts "You supplied the file: #{file}"
    delete_file = options[:delete]
    if delete_file
      puts "You specified that you would like to delete #{file}"
    else
      puts "You do not want to delete #{file}"
    end
  end
end

In this example, a method_option has been supplied with several parameters. The first parameter is the full name of the option. this is translated into a -- option on the command line. In this case, --delete. The :aliases option allows you to provide one or more short-hand aliases for the option. In this case, -d has been provided as a short-hand alias. And last, a description of the option has been provided.

Run thor help test:example and you will see the following output:

Usage:
  thor test:example FILE

Options:
  -d, [--delete=DELETE]  # Delete the file after parsing it

an example task

Now you can run the task with or without the delete option.

Run thor test:example my_file.rb, you will see this output:

You supplied the file: my_file.rb
You do not want to delete my_file.rb

Run thor test:example my_file.rb --delete or thor test:example my_file.rb -d and you will see:

You supplied the file: my_file.rb
You specified that you would like to delete my_file.rb

You can specify as many method options as you need, for a given task method. Just keep piling them on to the method name and they will show up in the task.

Running With Scissors

Though the examples here are simple and contrived, you should be able to get started with some real functionality for your thor tasks, now. Be sure to check the other wiki pages for documentation on the various options and capabilities of thor.