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
|
==================================
optcomplete: Sample Example Output
==================================
:Author: Martin Blais <blais@furius.ca>
:Date: 2004-01-26
:Abstract:
Some sample output and examples of what optcomplete provides.
Basic Features
==============
For some input script with the following ``optparse`` declarations::
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.")
We modify the last option simply to add one option-specific completer (this is
option, for this demo)::
opt = parser.add_option('-p', '--script', action='store',
help="Option that takes python scripts args only.")
opt.completer = optcomplete.RegexCompleter('.*\.py')
And then, to add support for completions, we need only add a call to the
autocomplete function, with optional regexps for filename completion::
# Support completion for the command-line of this script.
optcomplete.autocomplete(parser, ['.*\.tar.*'])
Here is sample output from the script.
.. note:: At the end of each input line I pressed <TAB> and not <ENTER>.
Files present in the test directory::
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
Completing without prefix outputs long and short options, and filename
completion::
elbow:~/p/optcomplete/test$ optcomplete-test
--help --script -h -p a.tar b.tar.gz
--output --simple -o -s a.tar.bz2
Completing existing short options completes simply::
elbow:~/p/optcomplete/test$ optcomplete-test -
--help --output --script --simple -h -o -p -s
elbow:~/p/optcomplete/test$ optcomplete-test -s
Completing existing long options works the same::
elbow:~/p/optcomplete/test$ optcomplete-test --
--help --output --script --simple
elbow:~/p/optcomplete/test$ optcomplete-test --s
elbow:~/p/optcomplete/test$ optcomplete-test --simple
Note that if an option requires an argument, other options following it are not
listed as possible completions::
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
Option-specific completion can be easily implemented as seen above, in this
example, the option ``--script`` takes files that end with ``.py`` only::
elbow:~/p/optcomplete/test$ optcomplete-test --script
script1.py script2.py
This works anywhere on the command-line, and so on::
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
Note that a partial filename will restrict the choices, as expected::
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
And running the program has the usual behaviour of ``optparse``, nothing changes::
----------------------------------------------------------
opts <Values at 0x404181ac: {'simple': None, 'output': None, 'script': 'script1.py'}>
args ['a.tar']
----------------------------------------------------------
.. note::
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
``optcomplete`` completion in the first place. This can be done in a
bash/shell initialization file for each supported program once the shell
``_optcomplete`` function has been sourced, it could easily be setup
globally::
complete -F _optcomplete optcomplete-test
Using Subcommands
=================
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 ``autocomplete()`` function and it works it out for you::
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
Subcommands can have their own custom completion for their own arguments::
elbow:~/p/optcomplete$ optcomplete-commands bar
--help -L commands some
--local -h completion
--local-other -l default
elbow:~/p/optcomplete$ optcomplete-commands bar
For the following interface::
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$
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.
You can setup command-specific completion as well::
elbow:~/p/optcomplete$ optcomplete-commands foo
--help -h foo_topic1
--local -l foo_topic2
elbow:~/p/optcomplete$ optcomplete-commands foo
|
