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
|
<?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: Shell Completion Self-Generator for Python</title>
<link rel="stylesheet" href="/docutils-style.css" type="text/css" />
</head>
<body>
<div class="document" id="optcomplete-shell-completion-self-generator-for-python">
<h1 class="title">optcomplete: Shell Completion Self-Generator for Python</h1>
<div class="contents topic" id="table-of-contents">
<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#description" id="id2" name="id2">Description</a><ul>
<li><a class="reference" href="#motivation" id="id3" name="id3">Motivation</a></li>
</ul>
</li>
<li><a class="reference" href="#documentation" id="id4" name="id4">Documentation</a></li>
<li><a class="reference" href="#download" id="id5" name="id5">Download</a></li>
<li><a class="reference" href="#copyright-and-license" id="id6" name="id6">Copyright and License</a></li>
<li><a class="reference" href="#author" id="id7" name="id7">Author</a></li>
</ul>
</div>
<div class="section" id="description">
<h1><a class="toc-backref" href="#id2" name="description">Description</a></h1>
<p>This Python module aims at providing almost automatically shell completion for
any Python program that already uses the <tt class="literal"><span class="pre">optparse</span></tt> module.</p>
<div class="section" id="motivation">
<h2><a class="toc-backref" href="#id3" name="motivation">Motivation</a></h2>
<p>This module aims at placing the shell completion routine and the option parsing
code in a single location: in the program itself.</p>
<p>The logic is that since a program already knows about its options, and in Python
we have a standard module to specify them programmatically since Python-2.3
(<tt class="literal"><span class="pre">optparse</span></tt>), the program itself is in the best position to suggest
completions for an incomplete command-line to a shell that invokes it.</p>
<p>Traditionally, this has been done by writing shell-specific descriptions
<em>separate</em> from the programs themselves, such as the <a class="reference" href="http://freshmeat.net/projects/bashcompletion/">Bash Programmable
Completion</a> project. This
approach requires maintaining the shell completion functions up-to-date with the
programs.</p>
<p>During development of this proof-of-concept, we were interested in finding if
the programs could not describe their completion routines themselves, using the
well-specified completion protocol in bash. Similar completion routines could
be easily written for other shells and we could extend this module to them.</p>
</div>
</div>
<div class="section" id="documentation">
<h1><a class="toc-backref" href="#id4" name="documentation">Documentation</a></h1>
<p><tt class="literal"><span class="pre">optcomplete</span></tt> consists of a simple module <a class="reference" href="lib/python/optcomplete.py">optcomplete.py</a> which you should install somewhere in your
PYTHONPATH.</p>
<p>To add simple support to a program which already uses <tt class="literal"><span class="pre">optparse</span></tt>, simply add
the following code after the optparse declarations, <em>before</em> calling the
<tt class="literal"><span class="pre">parse_args()</span></tt> function on your options parser:</p>
<pre class="literal-block">
import optcomplete
optcomplete.autocomplete(parser)
</pre>
<p>Optionally, you can pass a completer as a second argument (see module code).</p>
<p>You also need to <a class="reference" href="etc/optcomplete.bash">source a Bash function</a> and then to
tell Bash to trigger optcomplete completion for the specific programs that use
it:</p>
<pre class="literal-block">
complete -F _optcomplete <program>
</pre>
<p>More examples:</p>
<ul class="simple">
<li><a class="reference" href="doc/sample-output.html">Examples --- sample example output</a>;</li>
<li><a class="reference" href="doc/conditional.html">A note about conditionals</a>;</li>
<li><a class="reference" href="bin/optcomplete-simple">Simple test program speaks for itself</a>;</li>
<li><a class="reference" href="bin/optcomplete-commands">Test program with subcommands</a>;</li>
<li><a class="reference" href="CHANGES">CHANGES</a></li>
<li><a class="reference" href="TODO">TODO</a></li>
</ul>
</div>
<div class="section" id="download">
<h1><a class="toc-backref" href="#id5" name="download">Download</a></h1>
<ul>
<li><p><a class="reference" href="/downloads/optcomplete/">Download</a></p>
</li>
</ul>
</div>
<div class="section" id="copyright-and-license">
<h1><a class="toc-backref" href="#id6" name="copyright-and-license">Copyright and License</a></h1>
<p>Copyright (C) 2001-2004 Martin Blais. All Rights Reserved.</p>
<p>This code is distributed under the <a class="reference" href="COPYING">BSD License</a>.</p>
</div>
<div class="section" id="author">
<h1><a class="toc-backref" href="#id7" name="author">Author</a></h1>
<p>Martin Blais <<a class="reference" href="mailto:blais@furius.ca">blais@furius.ca</a>></p>
</div>
</div>
</body>
</html>
|
