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
180
181
182
183
184
185
186
187
188
189
|
<?xml version="1.0" encoding="iso-8859-1" ?>
<!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" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="generator" content="Docutils 0.3.0: http://docutils.sourceforge.net/" />
<title>optcomplete: Sample Example Output</title>
<meta name="author" content="Martin Blais <blais@furius.ca>" />
<meta name="date" content="2004-01-26" />
<link rel="stylesheet" href="/docutils-style.css" type="text/css" />
</head>
<body>
<div class="document" id="optcomplete-sample-example-output">
<h1 class="title">optcomplete: Sample Example Output</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Martin Blais <<a class="reference" href="mailto:blais@furius.ca">blais@furius.ca</a>></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2004-01-26</td></tr>
</tbody>
</table>
<div class="abstract topic">
<p class="topic-title">Abstract</p>
<p>Some sample output and examples of what optcomplete provides.</p>
</div>
<div class="section" id="basic-features">
<h1><a name="basic-features">Basic Features</a></h1>
<p>For some input script with the following <tt class="literal"><span class="pre">optparse</span></tt> declarations:</p>
<pre class="literal-block">
parser = optparse.OptionParser()
parser.add_option('-s', '--simple', action='store_true',
help="Simple really simple option without argument.")
parser.add_option('-o', '--output', action='store',
help="Option that requires an argument.")
parser.add_option('-p', '--script', action='store',
help="Option that takes python scripts args only.")
</pre>
<p>We modify the last option simply to add one option-specific completer (this is
option, for this demo):</p>
<pre class="literal-block">
opt = parser.add_option('-p', '--script', action='store',
help="Option that takes python scripts args only.")
opt.completer = optcomplete.RegexCompleter('.*\.py')
</pre>
<p>And then, to add support for completions, we need only add a call to the
autocomplete function, with optional regexps for filename completion:</p>
<pre class="literal-block">
# Support completion for the command-line of this script.
optcomplete.autocomplete(parser, ['.*\.tar.*'])
</pre>
<p>Here is sample output from the script.</p>
<div class="note">
<p class="admonition-title">Note</p>
At the end of each input line I pressed <TAB> and not <ENTER>.</div>
<p>Files present in the test directory:</p>
<pre class="literal-block">
elbow:~/p/optcomplete/test$ ls -l
total 24
drwxr-xr-x 2 blais users 4096 Jan 26 00:59 CVS
-rw-r--r-- 1 blais users 0 Jan 26 00:38 a.tar
-rw-r--r-- 1 blais users 0 Jan 26 00:38 a.tar.bz2
-rw-r--r-- 1 blais users 0 Jan 26 00:38 b.tar.gz
drwxr-xr-x 3 blais users 4096 Jan 26 00:38 dir1
-rw-r--r-- 1 blais users 5803 Jan 26 01:03 sample-output.html
-rw-r--r-- 1 blais users 4160 Jan 26 01:04 sample-output.txt
-rw-r--r-- 1 blais users 0 Jan 26 00:38 script.sh
-rw-r--r-- 1 blais users 0 Jan 26 00:38 script1.py
-rw-r--r-- 1 blais users 0 Jan 26 00:38 script2.py
</pre>
<p>Completing without prefix outputs long and short options, and filename
completion:</p>
<pre class="literal-block">
elbow:~/p/optcomplete/test$ optcomplete-test
--help --script -h -p a.tar b.tar.gz
--output --simple -o -s a.tar.bz2
</pre>
<p>Completing existing short options completes simply:</p>
<pre class="literal-block">
elbow:~/p/optcomplete/test$ optcomplete-test -
--help --output --script --simple -h -o -p -s
elbow:~/p/optcomplete/test$ optcomplete-test -s
</pre>
<p>Completing existing long options works the same:</p>
<pre class="literal-block">
elbow:~/p/optcomplete/test$ optcomplete-test --
--help --output --script --simple
elbow:~/p/optcomplete/test$ optcomplete-test --s
elbow:~/p/optcomplete/test$ optcomplete-test --simple
</pre>
<p>Note that if an option requires an argument, other options following it are not
listed as possible completions:</p>
<pre class="literal-block">
elbow:~/p/optcomplete/test$ optcomplete-test --output
a.tar a.tar.bz2 b.tar.gz
elbow:~/p/optcomplete/test$ optcomplete-test --simple
--help --script -h -p a.tar b.tar.gz
--output --simple -o -s a.tar.bz2
</pre>
<p>Option-specific completion can be easily implemented as seen above, in this
example, the option <tt class="literal"><span class="pre">--script</span></tt> takes files that end with <tt class="literal"><span class="pre">.py</span></tt> only:</p>
<pre class="literal-block">
elbow:~/p/optcomplete/test$ optcomplete-test --script
script1.py script2.py
</pre>
<p>This works anywhere on the command-line, and so on:</p>
<pre class="literal-block">
elbow:~/p/optcomplete/test$ optcomplete-test --simple --script script1.py
--help --script -h -p a.tar b.tar.gz
--output --simple -o -s a.tar.bz2
</pre>
<p>Note that a partial filename will restrict the choices, as expected:</p>
<pre class="literal-block">
elbow:~/p/optcomplete/test$ optcomplete-test --simple --script script1.py a.
a.tar a.tar.bz2
elbow:~/p/optcomplete/test$ optcomplete-test --simple --script script1.py a.tar
</pre>
<p>And running the program has the usual behaviour of <tt class="literal"><span class="pre">optparse</span></tt>, nothing changes:</p>
<pre class="literal-block">
----------------------------------------------------------
opts <Values at 0x404181ac: {'simple': None, 'output': None, 'script': 'script1.py'}>
args ['a.tar']
----------------------------------------------------------
</pre>
<div class="note">
<p class="admonition-title">Note</p>
<p>It is important to note that a shell completion hook is required in order for
the shell to invoke the Python script with the appropriate input to request
<tt class="literal"><span class="pre">optcomplete</span></tt> completion in the first place. This can be done in a
bash/shell initialization file for each supported program once the shell
<tt class="literal"><span class="pre">_optcomplete</span></tt> function has been sourced, it could easily be setup
globally:</p>
<pre class="literal-block">
complete -F _optcomplete optcomplete-test
</pre>
</div>
</div>
<div class="section" id="using-subcommands">
<h1><a name="using-subcommands">Using Subcommands</a></h1>
<p>You can also implement completion for subcommands, given very few
restrictions. Basically, you build a map from command name to command object and
give that to the <tt class="literal"><span class="pre">autocomplete()</span></tt> function and it works it out for you:</p>
<pre class="literal-block">
elbow:~/p/optcomplete$ optcomplete-commands
--global --version -v foo help
--help -g bar goo man
--verbose -h completing gore simplest
elbow:~/p/optcomplete$ optcomplete-commands
</pre>
<p>Subcommands can have their own custom completion for their own arguments:</p>
<pre class="literal-block">
elbow:~/p/optcomplete$ optcomplete-commands bar
--help -L commands some
--local -h completion
--local-other -l default
elbow:~/p/optcomplete$ optcomplete-commands bar
</pre>
<p>For the following interface:</p>
<pre class="literal-block">
elbow:~/p/optcomplete$ optcomplete-commands bar --help
usage: Bar command description, derived from foo.
options:
-h, --help show this help message and exit
-l, --local Some local option.
-L, --local-other Some other local option.
elbow:~/p/optcomplete$
</pre>
<p>Note above that the completions have been set to a default for all the commands,
so that the words 'commands', 'some', 'completion', 'default' are produced.</p>
<p>You can setup command-specific completion as well:</p>
<pre class="literal-block">
elbow:~/p/optcomplete$ optcomplete-commands foo
--help -h foo_topic1
--local -l foo_topic2
elbow:~/p/optcomplete$ optcomplete-commands foo
</pre>
</div>
</div>
</body>
</html>
|
