path: root/railties/lib/rails/vendor/thor-0.11.6/README.rdoc

= thor

Map options to a class. Simply create a class with the appropriate annotations
and have options automatically map to functions and parameters.

Example:

    class App < Thor                                                 # [1]
      map "-L" => :list                                              # [2]
      
      desc "install APP_NAME", "install one of the available apps"   # [3]
      method_options :force => :boolean, :alias => :string           # [4]
      def install(name)
        user_alias = options[:alias]
        if options.force?
          # do something
        end
        # other code
      end
      
      desc "list [SEARCH]", "list all of the available apps, limited by SEARCH"
      def list(search="")
        # list everything
      end
    end

Thor automatically maps commands as such:

    thor app:install myname --force

That gets converted to:

    App.new.install("myname")
    # with {'force' => true} as options hash

1. Inherit from Thor to turn a class into an option mapper
2. Map additional non-valid identifiers to specific methods. In this case, convert -L to :list
3. Describe the method immediately below. The first parameter is the usage information, and the second parameter is the description
4. Provide any additional options that will be available the instance method options.

== Types for <tt>method_options</tt>

* :boolean - is parsed as <tt>--option</tt> or <tt>--option=true</tt>
* :string  - is parsed as <tt>--option=VALUE</tt>
* :numeric - is parsed as <tt>--option=N</tt>
* :array   - is parsed as <tt>--option=one two three</tt>
* :hash    - is parsed as <tt>--option=name:string age:integer</tt>

Besides, method_option allows a default value to be given, examples:

    method_options :force => false
    #=> Creates a boolean option with default value false

    method_options :alias => "bar"
    #=> Creates a string option with default value "bar"

    method_options :threshold => 3.0
    #=> Creates a numeric option with default value 3.0

You can also supply <tt>:option => :required</tt> to mark an option as required. The
type is assumed to be string. If you want a required hash with default values
as option, you can use <tt>method_option</tt> which uses a more declarative style:

    method_option :attributes, :type => :hash, :default => {}, :required => true

All arguments can be set to nil (except required arguments), by suppling a no or
skip variant. For example:

    thor app name --no-attributes

In previous versions, aliases for options were created automatically, but now
they should be explicit. You can supply aliases in both short and declarative
styles:

    method_options %w( force -f ) => :boolean

Or:

    method_option :force, :type => :boolean, :aliases => "-f"

You can supply as many aliases as you want.

NOTE: Type :optional available in Thor 0.9.0 was deprecated. Use :string or :boolean instead.

== Namespaces

By default, your Thor tasks are invoked using Ruby namespace. In the example
above, tasks are invoked as:

    thor app:install name --force

However, you could namespace your class as:

    module Sinatra
      class App < Thor
        # tasks
      end
    end

And then you should invoke your tasks as:

    thor sinatra:app:install name --force

If desired, you can change the namespace:

    module Sinatra
      class App < Thor
        namespace :myapp
        # tasks
      end
    end

And then your tasks hould be invoked as:

    thor myapp:install name --force

== Invocations

Thor comes with a invocation-dependency system as well which allows a task to be
invoked only once. For example:

    class Counter < Thor
      desc "one", "Prints 1, 2, 3"
      def one
        puts 1
        invoke :two
        invoke :three
      end
      
      desc "two", "Prints 2, 3"
      def two
        puts 2
        invoke :three
      end
      
      desc "three", "Prints 3"
      def three
        puts 3
      end
    end

When invoking the task one:

    thor counter:one

The output is "1 2 3", which means that the three task was invoked only once.
You can even invoke tasks from another class, so be sure to check the
documentation.

== Thor::Group

Thor has a special class called Thor::Group. The main difference to Thor class
is that it invokes all tasks at once. The example above could be rewritten in
Thor::Group as this:

    class Counter < Thor::Group
      desc "Prints 1, 2, 3"
      
      def one
        puts 1
      end
     
      def two
        puts 2
      end
      
      def three
        puts 3
      end
    end

When invoked:

    thor counter

It prints "1 2 3" as well. Notice you should describe (using the method <tt>desc</tt>)
only the class and not each task anymore. Thor::Group is a great tool to create
generators, since you can define several steps which are invoked in the order they
are defined (Thor::Group is the tool use in generators in Rails 3.0).

Besides, Thor::Group can parse arguments and options as Thor tasks:

    class Counter < Thor::Group
      # number will be available as attr_accessor
      argument :number, :type => :numeric, :desc => "The number to start counting"
      desc "Prints the 'number' given upto 'number+2'"
      
      def one
        puts number + 0
      end
      
      def two
        puts number + 1
      end
      
      def three
        puts number + 2
      end
    end

The counter above expects one parameter and has the folling outputs:

    thor counter 5
    # Prints "5 6 7"

    thor counter 11
    # Prints "11 12 13"

You can also give options to Thor::Group, but instead of using <tt>method_option</tt>
and <tt>method_options</tt>, you should use <tt>class_option</tt> and <tt>class_options</tt>.
Both argument and class_options methods are available to Thor class as well.

== Actions

Thor comes with several actions which helps with script and generator tasks. You
might be familiar with them since some came from Rails Templates. They are:
<tt>say</tt>, <tt>ask</tt>, <tt>yes?</tt>, <tt>no?</tt>, <tt>add_file</tt>,
<tt>remove_file</tt>, <tt>copy_file</tt>, <tt>template</tt>, <tt>directory</tt>,
<tt>inside</tt>, <tt>run</tt>, <tt>inject_into_file</tt> and a couple more.

To use them, you just need to include Thor::Actions in your Thor classes:

    class App < Thor
      include Thor::Actions
      # tasks
    end

Some actions like copy file requires that a class method called source_root is
defined in your class. This is the directory where your templates should be
placed. Be sure to check the documentation.

== License

See MIT LICENSE.