1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
<?xml version="1.0" ?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>lib/numru/misc/keywordopt.rb</title>
</head>
<body>
<h2><a name="label:0" id="label:0">Index</a></h2><!-- RDLabel: "Index" -->
<ul>
<li><a href="#label:1">class NumRu::Misc::KeywordOpt</a></li>
<li><a href="#label:13">class NumRu::Misc::KeywordOptAutoHelp < NumRu::Misc::KeywordOpt</a></li>
</ul>
<h1><a name="label:1" id="label:1">class NumRu::Misc::KeywordOpt</a></h1><!-- RDLabel: "class NumRu::Misc::KeywordOpt" -->
<h2><a name="label:2" id="label:2">Overview</a></h2><!-- RDLabel: "Overview" -->
<p>A class to facilitate optional keyword arguments. More specifically,
it helps the use of a Hash to mimic the keyword argument system.
With this, you can set default values and description to each
keyword argument.</p>
<h2><a name="label:3" id="label:3">Classes defined supplementarilly</a></h2><!-- RDLabel: "Classes defined supplementarilly" -->
<h3><a name="label:4" id="label:4">class NumRu::Misc::HelpMessagingException < StandardError</a></h3><!-- RDLabel: "class NumRu::Misc::HelpMessagingException < StandardError" -->
<p>This is for your convenience. See the usage example below.</p>
<h2><a name="label:5" id="label:5">Usage example</a></h2><!-- RDLabel: "Usage example" -->
<p>Suppose that you introduce keyword arguments "flag" and "number"
to the method "hoge" in a class/module Foo. It can be done as
follows:</p>
<pre>require 'numru/misc' # or, specifically, require 'numru/misc/keywordopt'
include NumRu
class Foo
@@opt_hoge = Misc::KeywordOpt.new(
['flag', false, 'whether or not ...'],
['number', 1, 'number of ...'],
['help', false, 'show help message']
)
def hoge(regular_arg1, regular_arg2, options=nil)
opt = @@opt_hoge.interpret(options)
if opt['help']
puts @@opt_hoge.help
puts ' Current values='+opt.inspect
raise Misc::HelpMessagingException, '** show help message and raise **'
end
# do what you want below
# (options are set in the Hash opt: opt['flag'] and opt['number'])
end
end</pre>
<p>Here, the options are defined in the class variable @@opt_hoge
with option names, default values, and descriptions (for help
messaging). One can use the method hoge as follows:</p>
<pre>foo = Foo.new
...
x = ...
y = ...
...
foo.hoge( x, y, {'flag'=>true, 'number'=>10} )</pre>
<p>Or equivalently,</p>
<pre>foo.hoge( x, y, 'flag'=>true, 'number'=>10 )</pre>
<p>because '{}' can be omitted here. </p>
<p>Tails of options names can be shortened as long as unambiguous:</p>
<pre>foo.hoge( x, y, 'fla'=>true, 'num'=>10 )</pre>
<p>To show the help message, call</p>
<pre>foo.hoge( x, y, 'help'=>true )</pre>
<p>This will cause the following help message printed with the
exception HelpMessagingException raised.</p>
<pre><< Description of options >>
option name => default value description:
"flag" => false whether or not ...
"number" => 1 number of ...
"help" => false show help message
Current values={"help"=>true, "number"=>1, "flag"=>false}
NumRu::Misc::HelpMessagingException: ** help messaging done **
from (irb):78:in "hoge"
from (irb):83</pre>
<p>Do not affraid to write long descriptions. The help method
breaks lines nicely if they are long.</p>
<h2><a name="label:6" id="label:6">Class methods</a></h2><!-- RDLabel: "Class methods" -->
<dl>
<dt><a name="label:7" id="label:7"><code>KeywordOpt.new( *<var>args</var> )</code></a></dt><!-- RDLabel: "KeywordOpt.new" -->
<dd>
<p>Constructor.</p>
<p>ARGUMENTS</p>
<ul>
<li><p>args : (case 1) arrays of two or three elements: [option name,
default value, description ], or [option name, default value]
if you do not want to write descriptions. Option names and
descriptions must be String. (case 2) another KeywordOpt.
Cases 1 and 2 can be mixed. </p>
<p>When case 2, a link to the other KeywordOpt is kept. Thus, change
of values in it is reflected to the current one. However,
the link is deleted if values are changed by <a href="#label:10">set</a>.</p></li>
</ul>
<p>RETURN VALUE</p>
<ul>
<li>a KeywordOpt object</li>
</ul>
<p>EXAMPLE</p>
<ul>
<li>case 1</li>
</ul></dd>
</dl>
<pre>opt = Misc::KeywordOpt.new(
['flag', false, 'whether or not ...'],
['help', false, 'show help message']
)</pre>
<ul>
<li><p>case 2</p>
<pre>opt = Misc::KeywordOpt.new( optA, optB )</pre></li>
<li>case 1 & 2</li>
</ul>
<pre>opt = Misc::KeywordOpt.new(
['flag', false, 'whether or not ...'],
optA
)</pre>
<h2><a name="label:8" id="label:8">Methods</a></h2><!-- RDLabel: "Methods" -->
<dl>
<dt><a name="label:9" id="label:9"><code>interpret(<var>hash</var>)</code></a></dt><!-- RDLabel: "interpret" -->
<dd>
<p>Interprets a hash that specifies option values.</p>
<p>ARGUMENTS</p>
<ul>
<li>hash (Hash or nil) : a hash with string keys matching option names
(initializedwhen constructed). The matching is case sensitive and done
such that the tail of a option name can be omitted as long as
unambiguous (for example, 'num' for 'number').
If the argument is nil, the current values are returned.
If there are two options like 'max' and 'maxval', to use
a key 'max' (identical to the former paramer) is allowed, although
it matches 'maxval' as well. (Again 'ma' is regarded ambiguous.)</li>
</ul>
<p>RETURN VALUE</p>
<ul>
<li>a Hash containing the option values (default values overwritten
with hash).</li>
</ul>
<p>POSSIBLE EXCEPTION</p>
<ul>
<li>hash has a key that does not match any of the option names.</li>
<li>hash has a key that is ambiguous</li>
</ul></dd>
<dt><a name="label:10" id="label:10"><code>set(<var>hash</var>)</code></a></dt><!-- RDLabel: "set" -->
<dd>
<p>Similar to <a href="#label:9">interpret</a> but changes internal values.</p>
<p>ARGUMENTS</p>
<ul>
<li>hash (Hash) : see <a href="#label:9">interpret</a>. (Here, nil is not permitted though)</li>
</ul>
<p>RETURN VALUE</p>
<ul>
<li>a Hash containing the values replaced (the ones before calling this
method)</li>
</ul>
<p>POSSIBLE EXCEPTION</p>
<ul>
<li>the argument is not a Hash</li>
<li>others are same as in <a href="#label:9">interpret</a></li>
</ul></dd>
<dt><a name="label:11" id="label:11"><code>help</code></a></dt><!-- RDLabel: "help" -->
<dd>
<p>Returns a help message</p>
<p>RETURN VALUE</p>
<ul>
<li>a String describing the option names, default values, and descriptions</li>
</ul></dd>
<dt><a name="label:12" id="label:12"><code>[<var>key</var>]</code></a></dt><!-- RDLabel: "[]" -->
<dd>
<p>Returns a value associated with the key (exact matching unlike interpret)</p></dd>
</dl>
<h1><a name="label:13" id="label:13">class NumRu::Misc::KeywordOptAutoHelp < NumRu::Misc::KeywordOpt</a></h1><!-- RDLabel: "class NumRu::Misc::KeywordOptAutoHelp < NumRu::Misc::KeywordOpt" -->
<p>Same as <a href="#label:1">class NumRu::Misc::KeywordOpt</a>, but the method <a href="#label:9">interpret</a>
shows a help message and raise an exception if option 'help' is provided
as an argument and is not nil or false
(<code>NumRu::Misc::HelpMessagingException < StandardError</code>)
or if the arguments cannot be interpreted correctly (<code>ArgumentError</code>).
Option 'help' is automatically defined, so you do not have to define it
yourself.</p>
</body>
</html>
|
