Method Options

NOTE: a good part of the documentation here is outdated, see the website instead: http://whatisthor.com/

Thor allows you to specify options for its tasks, using method_options (options as an alias) to supply a hash of options, or method_option (option as an alias) to provide more detail about an individual option. You can access these options via the options hash.

Available Options

• :aliases — A list of aliases for this option. Typically, you would use aliases to provide short versions of the option.
• :banner — The short description of the option, printed out in the usage description. By default, this is the upcase version of the flag (from=FROM).
• :default — The default value of this option if it is not provided.
• :lazy_default — A default that is only passed if the cli option is passed without a value.
• :desc — A description for the option. When printing out full usage for a command using cli help hello, this description will appear next to the option.
• :required — Indicates that an option is required
• :type — :string, :hash, :array, :numeric, or :boolean (see below for more details)
• :enum — A list of allowed values for this option.
• :repeatable - Allows the same option to be used multiple times.

Types for method_options

• :boolean is parsed as --option or --option=true
• :string is parsed as --option=VALUE
• :numeric is parsed as --option=N
• :array is parsed as --option=one two three
• :hash is parsed as --option=name:string age:integer

Default Values

method_option allows a default value to be given. Example:

method_option :value, :default => "some value"
#=> Creates a string option with a default value of "some value"

You can also specify the default as a value to the option name. Examples:

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

method_option :aliases => "bar"
#=> Creates an alias 'bar'

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

You can also supply :option => :required 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 method_option 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 supplying 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: Thor follows a convention of one-dash-one-letter options. Thus aliases like "-something" wont be parsed; use either "\--something" or "-s" instead.

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

Repeatable Options

Options with repeatable: true allow the user to use the same option multiple times, the given values are put together into an array, for example:

method_options :format, type: :string, repeatable: true

When called with:

thor app name --format html --format xml --format text

Would produce the following options hash:

{ format: ["html", "xml", "text"] }

Please note that when repeatable is true the value will still be an array, even is the option was used only once:

thor app name --format html
# => Will produce: { format: ["html"] }