@@ -10,49 +10,67 @@ Example: map "-L" => :list # [2] desc "install APP_NAME", "install one of the available apps" # [3] - method_options :force => :boolean # [4] - def install(name, opts) - ... code ... - if opts[:force] + method_options :force => :boolean, :alias => :optional # [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 - MyApp.start - -Thor automatically maps commands as follows: +Thor automatically maps commands as such: - app install name --force + app install myname --force That gets converted to: - MyApp.new.install("name", :force => true) + MyApp.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. These will be marshaled from -- and - params. - In this case, a --force and a -f option is added. +4. Provide any additional options. These will be marshaled from `--` and `-` params. + In this case, a `--force` and a `-f` option is added. Types for `method_options` -------------------------- <dl> <dt><code>:boolean</code></dt> - <dd>true if the option is passed</dd> + <dd>true if the option is passed</dd> + <dt><code>true</code></dt> + <dd>same as <code>:boolean</code></dd> <dt><code>:required</code></dt> - <dd>the value for this option MUST be provided</dd> + <dd>the value for this option MUST be provided</dd> <dt><code>:optional</code></dt> - <dd>the value for this option MAY be provided</dd> - <dt>a String</dt> - <dd>same as <code>:optional</code>; fall back to the given string as default value</dd> -</dl> \ No newline at end of file + <dd>the value for this option MAY be provided</dd> + <dt><code>:numeric</code></dt> + <dd>the value MAY be provided, but MUST be in numeric form</dd> + <dt>a String or Numeric</dt> + <dd>same as <code>:optional</code>, but fall back to the given object as default value</dd> +</dl> + +In case of unsatisfied requirements, `Thor::Options::Error` is raised. + +Examples of option parsing: + + # let's say this is how we defined options for a method: + method_options(:force => :boolean, :retries => :numeric) + + # here is how the following command-line invocations would be parsed: + + command -f --retries 5 # => {'force' => true, 'retries' => 5} + command --force -r=5 # => {'force' => true, 'retries' => 5} + command -fr 5 # => {'force' => true, 'retries' => 5} + command --retries=5 # => {'retries' => 5} + command -r5 # => {'retries' => 5} \ No newline at end of file README.markdown @@ -165,7 +165,7 @@ class Thor when :required opt + "=" + opt.gsub(/\-/, "").upcase else - sample = @defaults[undasherize opt] + sample = @defaults[undasherize(opt)] sample ||= case type when :optional then opt.gsub(/\-/, "").upcase when :numeric then "N" @@ -228,7 +228,7 @@ class Thor def check_required!(hash) for name, type in @switches - if type == :required and !hash[undasherize name] + if type == :required and !hash[undasherize(name)] raise Error, "no value provided for required argument '#{name}'" end end lib/thor/options.rb @@ -3,9 +3,9 @@ class Amazing < Thor desc "describe NAME", "say that someone is amazing" method_options :forcefully => :boolean - def describe(name, opts = {}) + def describe(name) ret = "#{name} is amazing" - puts opts["forcefully"] ? ret.upcase : ret + puts options.forcefully?? ret.upcase : ret end desc "hello", "say hello" task.thor 4e4be8c2d31f62076b3ad1a6a769400f94215998 Mislav Marohnić mislav.marohnic@gmail.com http://github.com/wycats/thor/commit/a699ed71fd858b248d23f7341f3f292609063463 a699ed71fd858b248d23f7341f3f292609063463 2008-08-27T07:28:58-07:00 2008-08-26T17:10:57-07:00 update (incorrect) README and task.thor sample file fa65dc54d2137fa2ea5b19cd6157045f642587eb Mislav Marohnić mislav.marohnic@gmail.com