-
Notifications
You must be signed in to change notification settings - Fork 554
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
`
-
: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.
-
: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
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.
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"] }