Skip to content
Newer
Older
100644 76 lines (59 sloc) 2.67 KB
82ff27a @wycats Change name to thor. Last commit to hermes repo.
wycats authored May 7, 2008
1 thor
2 ====
a8de418 @wycats Initial checkin of Hermes
wycats authored May 6, 2008
3
4 Map options to a class. Simply create a class with the appropriate annotations, and have options automatically map
5 to functions and parameters.
6
c0cb7aa @mislav allow specifying optional args with default values: method_options(:u…
mislav authored Aug 25, 2008
7 Example:
a8de418 @wycats Initial checkin of Hermes
wycats authored May 7, 2008
8
c0cb7aa @mislav allow specifying optional args with default values: method_options(:u…
mislav authored Aug 25, 2008
9 class MyApp < Thor # [1]
10 map "-L" => :list # [2]
11
12 desc "install APP_NAME", "install one of the available apps" # [3]
a699ed7 @mislav update (incorrect) README and task.thor sample file
mislav authored Aug 27, 2008
13 method_options :force => :boolean, :alias => :optional # [4]
14 def install(name)
15 user_alias = options[:alias]
16 if options.force?
a8de418 @wycats Initial checkin of Hermes
wycats authored May 7, 2008
17 # do something
18 end
a699ed7 @mislav update (incorrect) README and task.thor sample file
mislav authored Aug 27, 2008
19 # ... other code ...
a8de418 @wycats Initial checkin of Hermes
wycats authored May 7, 2008
20 end
21
22 desc "list [SEARCH]", "list all of the available apps, limited by SEARCH"
23 def list(search = "")
24 # list everything
25 end
26 end
27
a699ed7 @mislav update (incorrect) README and task.thor sample file
mislav authored Aug 27, 2008
28 Thor automatically maps commands as such:
a8de418 @wycats Initial checkin of Hermes
wycats authored May 7, 2008
29
a699ed7 @mislav update (incorrect) README and task.thor sample file
mislav authored Aug 27, 2008
30 app install myname --force
a8de418 @wycats Initial checkin of Hermes
wycats authored May 7, 2008
31
32 That gets converted to:
33
a699ed7 @mislav update (incorrect) README and task.thor sample file
mislav authored Aug 27, 2008
34 MyApp.new.install("myname")
35 # with {'force' => true} as options hash
a8de418 @wycats Initial checkin of Hermes
wycats authored May 7, 2008
36
c0cb7aa @mislav allow specifying optional args with default values: method_options(:u…
mislav authored Aug 25, 2008
37 1. Inherit from Thor to turn a class into an option mapper
38 2. Map additional non-valid identifiers to specific methods. In this case,
a8de418 @wycats Initial checkin of Hermes
wycats authored May 7, 2008
39 convert -L to :list
c0cb7aa @mislav allow specifying optional args with default values: method_options(:u…
mislav authored Aug 25, 2008
40 3. Describe the method immediately below. The first parameter is the usage information,
a8de418 @wycats Initial checkin of Hermes
wycats authored May 7, 2008
41 and the second parameter is the description.
a699ed7 @mislav update (incorrect) README and task.thor sample file
mislav authored Aug 27, 2008
42 4. Provide any additional options. These will be marshaled from `--` and `-` params.
43 In this case, a `--force` and a `-f` option is added.
a8de418 @wycats Initial checkin of Hermes
wycats authored May 7, 2008
44
45 Types for `method_options`
46 --------------------------
47
48 <dl>
c0cb7aa @mislav allow specifying optional args with default values: method_options(:u…
mislav authored Aug 25, 2008
49 <dt><code>:boolean</code></dt>
a699ed7 @mislav update (incorrect) README and task.thor sample file
mislav authored Aug 27, 2008
50 <dd>true if the option is passed</dd>
51 <dt><code>true</code></dt>
52 <dd>same as <code>:boolean</code></dd>
c0cb7aa @mislav allow specifying optional args with default values: method_options(:u…
mislav authored Aug 25, 2008
53 <dt><code>:required</code></dt>
a699ed7 @mislav update (incorrect) README and task.thor sample file
mislav authored Aug 27, 2008
54 <dd>the value for this option MUST be provided</dd>
c0cb7aa @mislav allow specifying optional args with default values: method_options(:u…
mislav authored Aug 25, 2008
55 <dt><code>:optional</code></dt>
a699ed7 @mislav update (incorrect) README and task.thor sample file
mislav authored Aug 27, 2008
56 <dd>the value for this option MAY be provided</dd>
57 <dt><code>:numeric</code></dt>
58 <dd>the value MAY be provided, but MUST be in numeric form</dd>
59 <dt>a String or Numeric</dt>
60 <dd>same as <code>:optional</code>, but fall back to the given object as default value</dd>
61 </dl>
62
63 In case of unsatisfied requirements, `Thor::Options::Error` is raised.
64
65 Examples of option parsing:
66
67 # let's say this is how we defined options for a method:
68 method_options(:force => :boolean, :retries => :numeric)
69
70 # here is how the following command-line invocations would be parsed:
71
72 command -f --retries 5 # => {'force' => true, 'retries' => 5}
73 command --force -r=5 # => {'force' => true, 'retries' => 5}
74 command -fr 5 # => {'force' => true, 'retries' => 5}
75 command --retries=5 # => {'retries' => 5}
76 command -r5 # => {'retries' => 5}
Something went wrong with that request. Please try again.