projects / OpenSPARC-T2-DV / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / optparse-adding-new-actions.html
CommitLineData
86530b38
AT		 1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<link rel="STYLESHEET" href="lib.css" type='text/css' />
5<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
6<link rel='start' href='../index.html' title='Python Documentation Index' />
7<link rel="first" href="lib.html" title='Python Library Reference' />
8<link rel='contents' href='contents.html' title="Contents" />
9<link rel='index' href='genindex.html' title='Index' />
10<link rel='last' href='about.html' title='About this document...' />
11<link rel='help' href='about.html' title='About this document...' />
12<link rel="next" href="optparse-other-reasons-to-extend-optparse.html" />
13<link rel="prev" href="optparse-adding-new-types.html" />
14<link rel="parent" href="optparse-extending-optparse.html" />
15<link rel="next" href="optparse-other-reasons-to-extend-optparse.html" />
16<meta name='aesop' content='information' />
17<title>6.21.5.2 Adding new actions</title>
18</head>
19<body>
20<DIV CLASS="navigation">
21<div id='top-navigation-panel' xml:id='top-navigation-panel'>
22<table align="center" width="100%" cellpadding="0" cellspacing="2">
23<tr>
24<td class='online-navigation'><a rel="prev" title="6.21.5.1 Adding new types"
25 href="optparse-adding-new-types.html"><img src='../icons/previous.png'
26 border='0' height='32' alt='Previous Page' width='32' /></A></td>
27<td class='online-navigation'><a rel="parent" title="6.21.5 Extending optparse"
28 href="optparse-extending-optparse.html"><img src='../icons/up.png'
29 border='0' height='32' alt='Up One Level' width='32' /></A></td>
30<td class='online-navigation'><a rel="next" title="6.21.5.3 Other reasons to"
31 href="optparse-other-reasons-to-extend-optparse.html"><img src='../icons/next.png'
32 border='0' height='32' alt='Next Page' width='32' /></A></td>
33<td align="center" width="100%">Python Library Reference</td>
34<td class='online-navigation'><a rel="contents" title="Table of Contents"
35 href="contents.html"><img src='../icons/contents.png'
36 border='0' height='32' alt='Contents' width='32' /></A></td>
37<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
38 border='0' height='32' alt='Module Index' width='32' /></a></td>
39<td class='online-navigation'><a rel="index" title="Index"
40 href="genindex.html"><img src='../icons/index.png'
41 border='0' height='32' alt='Index' width='32' /></A></td>
42</tr></table>
43<div class='online-navigation'>
44<b class="navlabel">Previous:</b>
45<a class="sectref" rel="prev" href="optparse-adding-new-types.html">6.21.5.1 Adding new types</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="optparse-extending-optparse.html">6.21.5 Extending optparse</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="optparse-other-reasons-to-extend-optparse.html">6.21.5.3 Other reasons to</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H3><A NAME="SECTION0082152000000000000000"></A><A NAME="optparse-adding-new-actions"></A>
56<BR>
576.21.5.2 Adding new actions
58</H3>
59
60<P>
61Adding new actions is a bit trickier, because you have to understand
62that <tt class="module">optparse</tt> has a couple of classifications for actions:
63<DL>
64<DT><STRONG>``store'' actions</STRONG></DT>
65<DD>actions that result in <tt class="module">optparse</tt> storing a value to an attribute of the
66current OptionValues instance; these options require a <tt class="member">dest</tt>
67attribute to be supplied to the Option constructor
68</DD>
69<DT><STRONG>``typed'' actions</STRONG></DT>
70<DD>actions that take a value from the command line and expect it to be
71of a certain type; or rather, a string that can be converted to a
72certain type. These options require a <tt class="member">type</tt> attribute to the
73Option constructor.
74</DD>
75</DL>
76
77<P>
78These are overlapping sets: some default ``store'' actions are <code>store</code>,
79<code>store_const</code>, <code>append</code>, and <code>count</code>, while the default ``typed''
80actions are <code>store</code>, <code>append</code>, and <code>callback</code>.
81
82<P>
83When you add an action, you need to decide if it's a ``store'' action, a
84``typed'' action, neither, or both. Three class attributes of
85Option (or your Option subclass) control this:
86<DL>
87<DT><STRONG><tt class="member">ACTIONS</tt></STRONG></DT>
88<DD>all actions must be listed in ACTIONS
89</DD>
90<DT><STRONG><tt class="member">STORE_ACTIONS</tt></STRONG></DT>
91<DD>``store'' actions are additionally listed here
92</DD>
93<DT><STRONG><tt class="member">TYPED_ACTIONS</tt></STRONG></DT>
94<DD>``typed'' actions are additionally listed here
95</DD>
96</DL>
97
98<P>
99In order to actually implement your new action, you must override
100Option's <tt class="method">take_action()</tt> method and add a case that recognizes your
101action.
102
103<P>
104For example, let's add an <code>extend</code> action. This is similar to the
105standard <code>append</code> action, but instead of taking a single value from
106the command-line and appending it to an existing list, <code>extend</code> will
107take multiple values in a single comma-delimited string, and extend an
108existing list with them. That is, if <code>"-names"</code> is an <code>extend</code>
109option of type <code>string</code>, the command line
110<div class="verbatim"><pre>
111--names=foo,bar --names blah --names ding,dong
112</pre></div>
113
114<P>
115would result in a list
116<div class="verbatim"><pre>
117["foo", "bar", "blah", "ding", "dong"]
118</pre></div>
119
120<P>
121Again we define a subclass of Option:
122<div class="verbatim"><pre>
123class MyOption (Option):
124
125 ACTIONS = Option.ACTIONS + ("extend",)
126 STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
127 TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
128
129 def take_action(self, action, dest, opt, value, values, parser):
130 if action == "extend":
131 lvalue = value.split(",")
132 values.ensure_value(dest, []).extend(lvalue)
133 else:
134 Option.take_action(
135 self, action, dest, opt, value, values, parser)
136</pre></div>
137
138<P>
139Features of note:
140
141<UL>
142<LI>
143<code>extend</code> both expects a value on the command-line and stores that
144value somewhere, so it goes in both <tt class="member">STORE_ACTIONS</tt> and
145<tt class="member">TYPED_ACTIONS</tt>
146
147<P>
148</LI>
149<LI>
150<tt class="method">MyOption.take_action()</tt> implements just this one new action, and
151passes control back to <tt class="method">Option.take_action()</tt> for the standard
152<tt class="module">optparse</tt> actions
153
154<P>
155</LI>
156<LI>
157<code>values</code> is an instance of the optparse_parser.Values class,
158which provides the very useful <tt class="method">ensure_value()</tt> method.
159<tt class="method">ensure_value()</tt> is essentially <tt class="function">getattr()</tt> with a safety valve;
160it is called as
161<div class="verbatim"><pre>
162values.ensure_value(attr, value)
163</pre></div>
164
165<P>
166If the <code>attr</code> attribute of <code>values</code> doesn't exist or is None, then
167ensure_value() first sets it to <code>value</code>, and then returns 'value.
168This is very handy for actions like <code>extend</code>, <code>append</code>, and
169<code>count</code>, all of which accumulate data in a variable and expect that
170variable to be of a certain type (a list for the first two, an integer
171for the latter). Using <tt class="method">ensure_value()</tt> means that scripts using
172your action don't have to worry about setting a default value for the
173option destinations in question; they can just leave the default as
174None and <tt class="method">ensure_value()</tt> will take care of getting it right when
175it's needed.
176
177<P>
178</LI>
179</UL>
180
181<P>
182
183<DIV CLASS="navigation">
184<div class='online-navigation'>
185<p></p><hr />
186<table align="center" width="100%" cellpadding="0" cellspacing="2">
187<tr>
188<td class='online-navigation'><a rel="prev" title="6.21.5.1 Adding new types"
189 href="optparse-adding-new-types.html"><img src='../icons/previous.png'
190 border='0' height='32' alt='Previous Page' width='32' /></A></td>
191<td class='online-navigation'><a rel="parent" title="6.21.5 Extending optparse"
192 href="optparse-extending-optparse.html"><img src='../icons/up.png'
193 border='0' height='32' alt='Up One Level' width='32' /></A></td>
194<td class='online-navigation'><a rel="next" title="6.21.5.3 Other reasons to"
195 href="optparse-other-reasons-to-extend-optparse.html"><img src='../icons/next.png'
196 border='0' height='32' alt='Next Page' width='32' /></A></td>
197<td align="center" width="100%">Python Library Reference</td>
198<td class='online-navigation'><a rel="contents" title="Table of Contents"
199 href="contents.html"><img src='../icons/contents.png'
200 border='0' height='32' alt='Contents' width='32' /></A></td>
201<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
202 border='0' height='32' alt='Module Index' width='32' /></a></td>
203<td class='online-navigation'><a rel="index" title="Index"
204 href="genindex.html"><img src='../icons/index.png'
205 border='0' height='32' alt='Index' width='32' /></A></td>
206</tr></table>
207<div class='online-navigation'>
208<b class="navlabel">Previous:</b>
209<a class="sectref" rel="prev" href="optparse-adding-new-types.html">6.21.5.1 Adding new types</A>
210<b class="navlabel">Up:</b>
211<a class="sectref" rel="parent" href="optparse-extending-optparse.html">6.21.5 Extending optparse</A>
212<b class="navlabel">Next:</b>
213<a class="sectref" rel="next" href="optparse-other-reasons-to-extend-optparse.html">6.21.5.3 Other reasons to</A>
214</div>
215</div>
216<hr />
217<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
218</DIV>
219<!--End of Navigation Panel-->
220<ADDRESS>
221See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
222</ADDRESS>
223</BODY>
224</HTML>
Full OpenSPARC design & verification tarball including full HDL.