Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/liboptparse.tex @ 39042:c02fa187e0f4 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.
author Neal Norwitz <nnorwitz@gmail.com>
date Mon, 10 Jul 2006 00:23:17 +0000
parents ab253cd497d2
children a3fda843234e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
38718
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1 % THIS FILE IS AUTO-GENERATED! DO NOT EDIT!
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
2 % (Your changes will be lost the next time it is generated.)
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
3 \section{\module{optparse} --- More powerful command line option parser}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
4 \declaremodule{standard}{optparse}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
5 \moduleauthor{Greg Ward}{gward@python.net}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
6 \modulesynopsis{More convenient, flexible, and powerful command-line parsing library.}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
7 \versionadded{2.3}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
8 \sectionauthor{Greg Ward}{gward@python.net}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
9 % An intro blurb used only when generating LaTeX docs for the Python
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
10 % manual (based on README.txt).
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
11
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
12 \code{optparse} is a more convenient, flexible, and powerful library for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
13 parsing command-line options than \code{getopt}. \code{optparse} uses a more
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
14 declarative style of command-line parsing: you create an instance of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
15 \class{OptionParser}, populate it with options, and parse the command line.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
16 \code{optparse} allows users to specify options in the conventional GNU/POSIX
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
17 syntax, and additionally generates usage and help messages for you.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
18
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
19 Here's an example of using \code{optparse} in a simple script:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
20 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
21 from optparse import OptionParser
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
22 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
23 parser = OptionParser()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
24 parser.add_option("-f", "--file", dest="filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
25 help="write report to FILE", metavar="FILE")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
26 parser.add_option("-q", "--quiet",
28964
2e9956d01de3 Use True/False instead of 1/0 when talking about store_true/store_false.
Greg Ward <gward@python.net>
parents: 28962
diff changeset
27 action="store_false", dest="verbose", default=True,
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
28 help="don't print status messages to stdout")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
29
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
30 (options, args) = parser.parse_args()
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
31 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
32
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
33 With these few lines of code, users of your script can now do the
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
34 ``usual thing'' on the command-line, for example:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
35 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
36 <yourscript> --file=outfile -q
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
37 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
38
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
39 As it parses the command line, \code{optparse} sets attributes of the
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
40 \code{options} object returned by \method{parse{\_}args()} based on user-supplied
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
41 command-line values. When \method{parse{\_}args()} returns from parsing this
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
42 command line, \code{options.filename} will be \code{"outfile"} and
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
43 \code{options.verbose} will be \code{False}. \code{optparse} supports both long
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
44 and short options, allows short options to be merged together, and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
45 allows options to be associated with their arguments in a variety of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
46 ways. Thus, the following command lines are all equivalent to the above
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
47 example:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
48 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
49 <yourscript> -f outfile --quiet
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
50 <yourscript> --quiet --file outfile
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
51 <yourscript> -q -foutfile
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
52 <yourscript> -qfoutfile
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
53 \end{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
54
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
55 Additionally, users can run one of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
56 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
57 <yourscript> -h
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
58 <yourscript> --help
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
59 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
60
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
61 and \code{optparse} will print out a brief summary of your script's
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
62 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
63 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
64 usage: <yourscript> [options]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
65
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
66 options:
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
67 -h, --help show this help message and exit
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
68 -f FILE, --file=FILE write report to FILE
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
69 -q, --quiet don't print status messages to stdout
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
70 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
71
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
72 where the value of \emph{yourscript} is determined at runtime (normally
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
73 from \code{sys.argv{[}0]}).
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
74 % $Id: intro.txt 413 2004-09-28 00:59:13Z greg $
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
75
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
76
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
77 \subsection{Background\label{optparse-background}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
78
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
79 \module{optparse} was explicitly designed to encourage the creation of programs with
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
80 straightforward, conventional command-line interfaces. To that end, it
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
81 supports only the most common command-line syntax and semantics
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
82 conventionally used under \UNIX{}. If you are unfamiliar with these
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
83 conventions, read this section to acquaint yourself with them.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
84
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
85
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
86 \subsubsection{Terminology\label{optparse-terminology}}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
87 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
88 \item[argument]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
89 a string entered on the command-line, and passed by the shell to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
90 \code{execl()} or \code{execv()}. In Python, arguments are elements of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
91 \code{sys.argv{[}1:]} (\code{sys.argv{[}0]} is the name of the program being
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
92 executed). \UNIX{} shells also use the term ``word''.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
93
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
94 It is occasionally desirable to substitute an argument list other
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
95 than \code{sys.argv{[}1:]}, so you should read ``argument'' as ``an element of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
96 \code{sys.argv{[}1:]}, or of some other list provided as a substitute for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
97 \code{sys.argv{[}1:]}''.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
98 \item[option ]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
99 an argument used to supply extra information to guide or customize the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
100 execution of a program. There are many different syntaxes for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
101 options; the traditional \UNIX{} syntax is a hyphen (``-'') followed by a
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
102 single letter, e.g. \code{"-x"} or \code{"-F"}. Also, traditional \UNIX{}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
103 syntax allows multiple options to be merged into a single argument,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
104 e.g. \code{"-x -F"} is equivalent to \code{"-xF"}. The GNU project
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
105 introduced \code{"-{}-"} followed by a series of hyphen-separated words,
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
106 e.g. \code{"-{}-file"} or \code{"-{}-dry-run"}. These are the only two option
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
107 syntaxes provided by \module{optparse}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
108
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
109 Some other option syntaxes that the world has seen include:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
110 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
111 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
112 a hyphen followed by a few letters, e.g. \code{"-pf"} (this is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
113 \emph{not} the same as multiple options merged into a single argument)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
114
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
115 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
116 a hyphen followed by a whole word, e.g. \code{"-file"} (this is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
117 technically equivalent to the previous syntax, but they aren't
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
118 usually seen in the same program)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
119
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
120 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
121 a plus sign followed by a single letter, or a few letters,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
122 or a word, e.g. \code{"+f"}, \code{"+rgb"}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
123
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
124 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
125 a slash followed by a letter, or a few letters, or a word, e.g.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
126 \code{"/f"}, \code{"/file"}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
127
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
128 \end{itemize}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
129
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
130 These option syntaxes are not supported by \module{optparse}, and they never will
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
131 be. This is deliberate: the first three are non-standard on any
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
132 environment, and the last only makes sense if you're exclusively
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
133 targeting VMS, MS-DOS, and/or Windows.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
134 \item[option argument]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
135 an argument that follows an option, is closely associated with that
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
136 option, and is consumed from the argument list when that option is.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
137 With \module{optparse}, option arguments may either be in a separate argument
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
138 from their option:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
139 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
140 -f foo
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
141 --file foo
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
142 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
143
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
144 or included in the same argument:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
145 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
146 -ffoo
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
147 --file=foo
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
148 \end{verbatim}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
149
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
150 Typically, a given option either takes an argument or it doesn't.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
151 Lots of people want an ``optional option arguments'' feature, meaning
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
152 that some options will take an argument if they see it, and won't if
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
153 they don't. This is somewhat controversial, because it makes parsing
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
154 ambiguous: if \code{"-a"} takes an optional argument and \code{"-b"} is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
155 another option entirely, how do we interpret \code{"-ab"}? Because of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
156 this ambiguity, \module{optparse} does not support this feature.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
157 \item[positional argument]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
158 something leftover in the argument list after options have been
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
159 parsed, i.e. after options and their arguments have been parsed and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
160 removed from the argument list.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
161 \item[required option]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
162 an option that must be supplied on the command-line; note that the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
163 phrase ``required option'' is self-contradictory in English. \module{optparse}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
164 doesn't prevent you from implementing required options, but doesn't
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
165 give you much help at it either. See \code{examples/required{\_}1.py} and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
166 \code{examples/required{\_}2.py} in the \module{optparse} source distribution for two
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
167 ways to implement required options with \module{optparse}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
168 \end{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
169
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
170 For example, consider this hypothetical command-line:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
171 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
172 prog -v --report /tmp/report.txt foo bar
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
173 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
174
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
175 \code{"-v"} and \code{"-{}-report"} are both options. Assuming that
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
176 \longprogramopt{report} takes one argument, \code{"/tmp/report.txt"} is an option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
177 argument. \code{"foo"} and \code{"bar"} are positional arguments.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
178
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
179
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
180 \subsubsection{What are options for?\label{optparse-what-options-for}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
181
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
182 Options are used to provide extra information to tune or customize the
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
183 execution of a program. In case it wasn't clear, options are usually
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
184 \emph{optional}. A program should be able to run just fine with no options
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
185 whatsoever. (Pick a random program from the \UNIX{} or GNU toolsets. Can
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
186 it run without any options at all and still make sense? The main
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
187 exceptions are \code{find}, \code{tar}, and \code{dd}{---}all of which are mutant
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
188 oddballs that have been rightly criticized for their non-standard syntax
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
189 and confusing interfaces.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
190
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
191 Lots of people want their programs to have ``required options''. Think
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
192 about it. If it's required, then it's \emph{not optional}! If there is a
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
193 piece of information that your program absolutely requires in order to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
194 run successfully, that's what positional arguments are for.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
195
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
196 As an example of good command-line interface design, consider the humble
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
197 \code{cp} utility, for copying files. It doesn't make much sense to try to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
198 copy files without supplying a destination and at least one source.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
199 Hence, \code{cp} fails if you run it with no arguments. However, it has a
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
200 flexible, useful syntax that does not require any options at all:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
201 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
202 cp SOURCE DEST
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
203 cp SOURCE ... DEST-DIR
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
204 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
205
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
206 You can get pretty far with just that. Most \code{cp} implementations
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
207 provide a bunch of options to tweak exactly how the files are copied:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
208 you can preserve mode and modification time, avoid following symlinks,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
209 ask before clobbering existing files, etc. But none of this distracts
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
210 from the core mission of \code{cp}, which is to copy either one file to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
211 another, or several files to another directory.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
212
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
213
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
214 \subsubsection{What are positional arguments for?\label{optparse-what-positional-arguments-for}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
215
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
216 Positional arguments are for those pieces of information that your
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
217 program absolutely, positively requires to run.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
218
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
219 A good user interface should have as few absolute requirements as
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
220 possible. If your program requires 17 distinct pieces of information in
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
221 order to run successfully, it doesn't much matter \emph{how} you get that
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
222 information from the user{---}most people will give up and walk away
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
223 before they successfully run the program. This applies whether the user
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
224 interface is a command-line, a configuration file, or a GUI: if you make
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
225 that many demands on your users, most of them will simply give up.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
226
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
227 In short, try to minimize the amount of information that users are
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
228 absolutely required to supply{---}use sensible defaults whenever
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
229 possible. Of course, you also want to make your programs reasonably
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
230 flexible. That's what options are for. Again, it doesn't matter if
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
231 they are entries in a config file, widgets in the ``Preferences'' dialog
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
232 of a GUI, or command-line options{---}the more options you implement, the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
233 more flexible your program is, and the more complicated its
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
234 implementation becomes. Too much flexibility has drawbacks as well, of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
235 course; too many options can overwhelm users and make your code much
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
236 harder to maintain.
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
237 % $Id: tao.txt 413 2004-09-28 00:59:13Z greg $
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
238
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
239
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
240 \subsection{Tutorial\label{optparse-tutorial}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
241
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
242 While \module{optparse} is quite flexible and powerful, it's also straightforward to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
243 use in most cases. This section covers the code patterns that are
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
244 common to any \module{optparse}-based program.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
245
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
246 First, you need to import the OptionParser class; then, early in the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
247 main program, create an OptionParser instance:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
248 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
249 from optparse import OptionParser
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
250 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
251 parser = OptionParser()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
252 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
253
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
254 Then you can start defining options. The basic syntax is:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
255 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
256 parser.add_option(opt_str, ...,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
257 attr=value, ...)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
258 \end{verbatim}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
259
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
260 Each option has one or more option strings, such as \code{"-f"} or
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
261 \code{"-{}-file"}, and several option attributes that tell \module{optparse} what to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
262 expect and what to do when it encounters that option on the command
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
263 line.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
264
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
265 Typically, each option will have one short option string and one long
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
266 option string, e.g.:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
267 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
268 parser.add_option("-f", "--file", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
269 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
270
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
271 You're free to define as many short option strings and as many long
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
272 option strings as you like (including zero), as long as there is at
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
273 least one option string overall.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
274
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
275 The option strings passed to \method{add{\_}option()} are effectively labels for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
276 the option defined by that call. For brevity, we will frequently refer
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
277 to \emph{encountering an option} on the command line; in reality, \module{optparse}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
278 encounters \emph{option strings} and looks up options from them.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
279
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
280 Once all of your options are defined, instruct \module{optparse} to parse your
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
281 program's command line:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
282 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
283 (options, args) = parser.parse_args()
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
284 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
285
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
286 (If you like, you can pass a custom argument list to \method{parse{\_}args()},
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
287 but that's rarely necessary: by default it uses \code{sys.argv{[}1:]}.)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
288
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
289 \method{parse{\_}args()} returns two values:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
290 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
291 \item {}
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
292 \code{options}, an object containing values for all of your options{---}e.g. if \code{"-{}-file"} takes a single string argument, then
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
293 \code{options.file} will be the filename supplied by the user, or
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
294 \code{None} if the user did not supply that option
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
295
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
296 \item {}
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
297 \code{args}, the list of positional arguments leftover after parsing
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
298 options
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
299
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
300 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
301
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
302 This tutorial section only covers the four most important option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
303 attributes: \member{action}, \member{type}, \member{dest} (destination), and \member{help}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
304 Of these, \member{action} is the most fundamental.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
305
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
306
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
307 \subsubsection{Understanding option actions\label{optparse-understanding-option-actions}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
308
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
309 Actions tell \module{optparse} what to do when it encounters an option on the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
310 command line. There is a fixed set of actions hard-coded into \module{optparse};
38718
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
311 adding new actions is an advanced topic covered in section~\ref{optparse-extending-optparse}, Extending \module{optparse}.
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
312 Most actions tell \module{optparse} to store a value in some variable{---}for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
313 example, take a string from the command line and store it in an
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
314 attribute of \code{options}.
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
315
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
316 If you don't specify an option action, \module{optparse} defaults to \code{store}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
317
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
318
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
319 \subsubsection{The store action\label{optparse-store-action}}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
320
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
321 The most common option action is \code{store}, which tells \module{optparse} to take
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
322 the next argument (or the remainder of the current argument), ensure
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
323 that it is of the correct type, and store it to your chosen destination.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
324
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
325 For example:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
326 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
327 parser.add_option("-f", "--file",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
328 action="store", type="string", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
329 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
330
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
331 Now let's make up a fake command line and ask \module{optparse} to parse it:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
332 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
333 args = ["-f", "foo.txt"]
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
334 (options, args) = parser.parse_args(args)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
335 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
336
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
337 When \module{optparse} sees the option string \code{"-f"}, it consumes the next
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
338 argument, \code{"foo.txt"}, and stores it in \code{options.filename}. So,
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
339 after this call to \method{parse{\_}args()}, \code{options.filename} is
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
340 \code{"foo.txt"}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
341
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
342 Some other option types supported by \module{optparse} are \code{int} and \code{float}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
343 Here's an option that expects an integer argument:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
344 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
345 parser.add_option("-n", type="int", dest="num")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
346 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
347
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
348 Note that this option has no long option string, which is perfectly
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
349 acceptable. Also, there's no explicit action, since the default is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
350 \code{store}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
351
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
352 Let's parse another fake command-line. This time, we'll jam the option
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
353 argument right up against the option: since \code{"-n42"} (one argument) is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
354 equivalent to \code{"-n 42"} (two arguments), the code
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
355 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
356 (options, args) = parser.parse_args(["-n42"])
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
357 print options.num
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
358 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
359
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
360 will print \code{"42"}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
361
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
362 If you don't specify a type, \module{optparse} assumes \code{string}. Combined with the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
363 fact that the default action is \code{store}, that means our first example
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
364 can be a lot shorter:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
365 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
366 parser.add_option("-f", "--file", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
367 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
368
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
369 If you don't supply a destination, \module{optparse} figures out a sensible default
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
370 from the option strings: if the first long option string is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
371 \code{"-{}-foo-bar"}, then the default destination is \code{foo{\_}bar}. If there
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
372 are no long option strings, \module{optparse} looks at the first short option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
373 string: the default destination for \code{"-f"} is \code{f}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
374
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
375 \module{optparse} also includes built-in \code{long} and \code{complex} types. Adding
38718
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
376 types is covered in section~\ref{optparse-extending-optparse}, Extending \module{optparse}.
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
377
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
378
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
379 \subsubsection{Handling boolean (flag) options\label{optparse-handling-boolean-options}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
380
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
381 Flag options{---}set a variable to true or false when a particular option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
382 is seen{---}are quite common. \module{optparse} supports them with two separate
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
383 actions, \code{store{\_}true} and \code{store{\_}false}. For example, you might have a
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
384 \code{verbose} flag that is turned on with \code{"-v"} and off with \code{"-q"}:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
385 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
386 parser.add_option("-v", action="store_true", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
387 parser.add_option("-q", action="store_false", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
388 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
389
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
390 Here we have two different options with the same destination, which is
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
391 perfectly OK. (It just means you have to be a bit careful when setting
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
392 default values{---}see below.)
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
393
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
394 When \module{optparse} encounters \code{"-v"} on the command line, it sets
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
395 \code{options.verbose} to \code{True}; when it encounters \code{"-q"},
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
396 \code{options.verbose} is set to \code{False}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
397
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
398
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
399 \subsubsection{Other actions\label{optparse-other-actions}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
400
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
401 Some other actions supported by \module{optparse} are:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
402 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
403 \item[\code{store{\_}const}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
404 store a constant value
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
405 \item[\code{append}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
406 append this option's argument to a list
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
407 \item[\code{count}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
408 increment a counter by one
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
409 \item[\code{callback}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
410 call a specified function
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
411 \end{description}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
412
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
413 These are covered in section~\ref{optparse-reference-guide}, Reference Guide and section~\ref{optparse-option-callbacks}, Option Callbacks.
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
414
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
415
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
416 \subsubsection{Default values\label{optparse-default-values}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
417
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
418 All of the above examples involve setting some variable (the
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
419 ``destination'') when certain command-line options are seen. What happens
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
420 if those options are never seen? Since we didn't supply any defaults,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
421 they are all set to \code{None}. This is usually fine, but sometimes you
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
422 want more control. \module{optparse} lets you supply a default value for each
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
423 destination, which is assigned before the command line is parsed.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
424
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
425 First, consider the verbose/quiet example. If we want \module{optparse} to set
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
426 \code{verbose} to \code{True} unless \code{"-q"} is seen, then we can do this:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
427 \begin{verbatim}
28964
2e9956d01de3 Use True/False instead of 1/0 when talking about store_true/store_false.
Greg Ward <gward@python.net>
parents: 28962
diff changeset
428 parser.add_option("-v", action="store_true", dest="verbose", default=True)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
429 parser.add_option("-q", action="store_false", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
430 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
431
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
432 Since default values apply to the \emph{destination} rather than to any
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
433 particular option, and these two options happen to have the same
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
434 destination, this is exactly equivalent:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
435 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
436 parser.add_option("-v", action="store_true", dest="verbose")
28964
2e9956d01de3 Use True/False instead of 1/0 when talking about store_true/store_false.
Greg Ward <gward@python.net>
parents: 28962
diff changeset
437 parser.add_option("-q", action="store_false", dest="verbose", default=True)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
438 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
439
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
440 Consider this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
441 \begin{verbatim}
28964
2e9956d01de3 Use True/False instead of 1/0 when talking about store_true/store_false.
Greg Ward <gward@python.net>
parents: 28962
diff changeset
442 parser.add_option("-v", action="store_true", dest="verbose", default=False)
2e9956d01de3 Use True/False instead of 1/0 when talking about store_true/store_false.
Greg Ward <gward@python.net>
parents: 28962
diff changeset
443 parser.add_option("-q", action="store_false", dest="verbose", default=True)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
444 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
445
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
446 Again, the default value for \code{verbose} will be \code{True}: the last
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
447 default value supplied for any particular destination is the one that
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
448 counts.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
449
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
450 A clearer way to specify default values is the \method{set{\_}defaults()}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
451 method of OptionParser, which you can call at any time before calling
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
452 \method{parse{\_}args()}:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
453 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
454 parser.set_defaults(verbose=True)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
455 parser.add_option(...)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
456 (options, args) = parser.parse_args()
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
457 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
458
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
459 As before, the last value specified for a given option destination is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
460 the one that counts. For clarity, try to use one method or the other of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
461 setting default values, not both.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
462
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
463
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
464 \subsubsection{Generating help\label{optparse-generating-help}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
465
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
466 \module{optparse}'s ability to generate help and usage text automatically is useful
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
467 for creating user-friendly command-line interfaces. All you have to do
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
468 is supply a \member{help} value for each option, and optionally a short usage
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
469 message for your whole program. Here's an OptionParser populated with
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
470 user-friendly (documented) options:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
471 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
472 usage = "usage: %prog [options] arg1 arg2"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
473 parser = OptionParser(usage=usage)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
474 parser.add_option("-v", "--verbose",
28964
2e9956d01de3 Use True/False instead of 1/0 when talking about store_true/store_false.
Greg Ward <gward@python.net>
parents: 28962
diff changeset
475 action="store_true", dest="verbose", default=True,
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
476 help="make lots of noise [default]")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
477 parser.add_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
478 action="store_false", dest="verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
479 help="be vewwy quiet (I'm hunting wabbits)")
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
480 parser.add_option("-f", "--filename",
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
481 metavar="FILE", help="write output to FILE"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
482 parser.add_option("-m", "--mode",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
483 default="intermediate",
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
484 help="interaction mode: novice, intermediate, "
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
485 "or expert [default: %default]")
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
486 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
487
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
488 If \module{optparse} encounters either \code{"-h"} or \code{"-{}-help"} on the command-line,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
489 or if you just call \method{parser.print{\_}help()}, it prints the following to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
490 standard output:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
491 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
492 usage: <yourscript> [options] arg1 arg2
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
493
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
494 options:
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
495 -h, --help show this help message and exit
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
496 -v, --verbose make lots of noise [default]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
497 -q, --quiet be vewwy quiet (I'm hunting wabbits)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
498 -f FILE, --filename=FILE
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
499 write output to FILE
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
500 -m MODE, --mode=MODE interaction mode: novice, intermediate, or
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
501 expert [default: intermediate]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
502 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
503
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
504 (If the help output is triggered by a help option, \module{optparse} exits after
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
505 printing the help text.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
506
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
507 There's a lot going on here to help \module{optparse} generate the best possible
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
508 help message:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
509 \begin{itemize}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
510 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
511 the script defines its own usage message:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
512 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
513 usage = "usage: %prog [options] arg1 arg2"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
514 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
515
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
516 \module{optparse} expands \code{"{\%}prog"} in the usage string to the name of the current
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
517 program, i.e. \code{os.path.basename(sys.argv{[}0])}. The expanded string
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
518 is then printed before the detailed option help.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
519
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
520 If you don't supply a usage string, \module{optparse} uses a bland but sensible
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
521 default: ``\code{usage: {\%}prog {[}options]"}, which is fine if your script
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
522 doesn't take any positional arguments.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
523
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
524 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
525 every option defines a help string, and doesn't worry about line-
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
526 wrapping{---}\module{optparse} takes care of wrapping lines and making the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
527 help output look good.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
528
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
529 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
530 options that take a value indicate this fact in their
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
531 automatically-generated help message, e.g. for the ``mode'' option:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
532 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
533 -m MODE, --mode=MODE
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
534 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
535
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
536 Here, ``MODE'' is called the meta-variable: it stands for the argument
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
537 that the user is expected to supply to \programopt{-m}/\longprogramopt{mode}. By default,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
538 \module{optparse} converts the destination variable name to uppercase and uses
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
539 that for the meta-variable. Sometimes, that's not what you want{---}for example, the \longprogramopt{filename} option explicitly sets
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
540 \code{metavar="FILE"}, resulting in this automatically-generated option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
541 description:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
542 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
543 -f FILE, --filename=FILE
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
544 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
545
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
546 This is important for more than just saving space, though: the
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
547 manually written help text uses the meta-variable ``FILE'' to clue the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
548 user in that there's a connection between the semi-formal syntax ``-f
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
549 FILE'' and the informal semantic description ``write output to FILE''.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
550 This is a simple but effective way to make your help text a lot
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
551 clearer and more useful for end users.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
552
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
553 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
554 options that have a default value can include \code{{\%}default} in
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
555 the help string{---}\module{optparse} will replace it with \function{str()} of the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
556 option's default value. If an option has no default value (or the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
557 default value is \code{None}), \code{{\%}default} expands to \code{none}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
558
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
559 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
560
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
561
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
562 \subsubsection{Printing a version string\label{optparse-printing-version-string}}
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
563
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
564 Similar to the brief usage string, \module{optparse} can also print a version string
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
565 for your program. You have to supply the string as the \code{version}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
566 argument to OptionParser:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
567 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
568 parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
569 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
570
38718
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
571 \code{"{\%}prog"} is expanded just like it is in \code{usage}. Apart
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
572 from that, \code{version} can contain anything you like. When you supply
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
573 it, \module{optparse} automatically adds a \code{"-{}-version"} option to your parser.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
574 If it encounters this option on the command line, it expands your
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
575 \code{version} string (by replacing \code{"{\%}prog"}), prints it to stdout, and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
576 exits.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
577
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
578 For example, if your script is called \code{/usr/bin/foo}:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
579 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
580 $ /usr/bin/foo --version
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
581 foo 1.0
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
582 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
583
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
584
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
585 \subsubsection{How \module{optparse} handles errors\label{optparse-how-optparse-handles-errors}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
586
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
587 There are two broad classes of errors that \module{optparse} has to worry about:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
588 programmer errors and user errors. Programmer errors are usually
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
589 erroneous calls to \code{parser.add{\_}option()}, e.g. invalid option strings,
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
590 unknown option attributes, missing option attributes, etc. These are
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
591 dealt with in the usual way: raise an exception (either
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
592 \code{optparse.OptionError} or \code{TypeError}) and let the program crash.
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
593
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
594 Handling user errors is much more important, since they are guaranteed
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
595 to happen no matter how stable your code is. \module{optparse} can automatically
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
596 detect some user errors, such as bad option arguments (passing \code{"-n
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
597 4x"} where \programopt{-n} takes an integer argument), missing arguments
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
598 (\code{"-n"} at the end of the command line, where \programopt{-n} takes an argument
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
599 of any type). Also, you can call \code{parser.error()} to signal an
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
600 application-defined error condition:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
601 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
602 (options, args) = parser.parse_args()
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
603 [...]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
604 if options.a and options.b:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
605 parser.error("options -a and -b are mutually exclusive")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
606 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
607
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
608 In either case, \module{optparse} handles the error the same way: it prints the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
609 program's usage message and an error message to standard error and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
610 exits with error status 2.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
611
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
612 Consider the first example above, where the user passes \code{"4x"} to an
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
613 option that takes an integer:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
614 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
615 $ /usr/bin/foo -n 4x
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
616 usage: foo [options]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
617
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
618 foo: error: option -n: invalid integer value: '4x'
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
619 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
620
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
621 Or, where the user fails to pass a value at all:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
622 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
623 $ /usr/bin/foo -n
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
624 usage: foo [options]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
625
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
626 foo: error: -n option requires an argument
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
627 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
628
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
629 \module{optparse}-generated error messages take care always to mention the option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
630 involved in the error; be sure to do the same when calling
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
631 \code{parser.error()} from your application code.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
632
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
633 If \module{optparse}'s default error-handling behaviour does not suite your needs,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
634 you'll need to subclass OptionParser and override \code{exit()} and/or
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
635 \method{error()}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
636
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
637
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
638 \subsubsection{Putting it all together\label{optparse-putting-it-all-together}}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
639
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
640 Here's what \module{optparse}-based scripts usually look like:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
641 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
642 from optparse import OptionParser
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
643 [...]
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
644 def main():
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
645 usage = "usage: %prog [options] arg"
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
646 parser = OptionParser(usage)
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
647 parser.add_option("-f", "--file", dest="filename",
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
648 help="read data from FILENAME")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
649 parser.add_option("-v", "--verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
650 action="store_true", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
651 parser.add_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
652 action="store_false", dest="verbose")
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
653 [...]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
654 (options, args) = parser.parse_args()
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
655 if len(args) != 1:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
656 parser.error("incorrect number of arguments")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
657 if options.verbose:
33454
3daa6633f017 Patch #1025800: remove TeX quoting from verbatim section. Thanks Dima Dorfman!
Johannes Gijsbers <jlg@dds.nl>
parents: 32609
diff changeset
658 print "reading %s..." % options.filename
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
659 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
660
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
661 if __name__ == "__main__":
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
662 main()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
663 \end{verbatim}
38718
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
664 % $Id: tutorial.txt 515 2006-06-10 15:37:45Z gward $
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
665
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
666
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
667 \subsection{Reference Guide\label{optparse-reference-guide}}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
668
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
669
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
670 \subsubsection{Creating the parser\label{optparse-creating-parser}}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
671
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
672 The first step in using \module{optparse} is to create an OptionParser instance:
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
673 \begin{verbatim}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
674 parser = OptionParser(...)
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
675 \end{verbatim}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
676
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
677 The OptionParser constructor has no required arguments, but a number of
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
678 optional keyword arguments. You should always pass them as keyword
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
679 arguments, i.e. do not rely on the order in which the arguments are
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
680 declared.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
681 \begin{quote}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
682 \begin{description}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
683 \item[\code{usage} (default: \code{"{\%}prog {[}options]"})]
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
684 The usage summary to print when your program is run incorrectly or
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
685 with a help option. When \module{optparse} prints the usage string, it expands
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
686 \code{{\%}prog} to \code{os.path.basename(sys.argv{[}0])} (or to \code{prog} if
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
687 you passed that keyword argument). To suppress a usage message,
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
688 pass the special value \code{optparse.SUPPRESS{\_}USAGE}.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
689 \item[\code{option{\_}list} (default: \code{{[}]})]
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
690 A list of Option objects to populate the parser with. The options
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
691 in \code{option{\_}list} are added after any options in
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
692 \code{standard{\_}option{\_}list} (a class attribute that may be set by
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
693 OptionParser subclasses), but before any version or help options.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
694 Deprecated; use \method{add{\_}option()} after creating the parser instead.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
695 \item[\code{option{\_}class} (default: optparse.Option)]
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
696 Class to use when adding options to the parser in \method{add{\_}option()}.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
697 \item[\code{version} (default: \code{None})]
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
698 A version string to print when the user supplies a version option.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
699 If you supply a true value for \code{version}, \module{optparse} automatically adds
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
700 a version option with the single option string \code{"-{}-version"}. The
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
701 substring \code{"{\%}prog"} is expanded the same as for \code{usage}.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
702 \item[\code{conflict{\_}handler} (default: \code{"error"})]
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
703 Specifies what to do when options with conflicting option strings
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
704 are added to the parser; see section~\ref{optparse-conflicts-between-options}, Conflicts between options.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
705 \item[\code{description} (default: \code{None})]
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
706 A paragraph of text giving a brief overview of your program. \module{optparse}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
707 reformats this paragraph to fit the current terminal width and
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
708 prints it when the user requests help (after \code{usage}, but before
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
709 the list of options).
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
710 \item[\code{formatter} (default: a new IndentedHelpFormatter)]
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
711 An instance of optparse.HelpFormatter that will be used for
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
712 printing help text. \module{optparse} provides two concrete classes for this
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
713 purpose: IndentedHelpFormatter and TitledHelpFormatter.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
714 \item[\code{add{\_}help{\_}option} (default: \code{True})]
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
715 If true, \module{optparse} will add a help option (with option strings \code{"-h"}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
716 and \code{"-{}-help"}) to the parser.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
717 \item[\code{prog}]
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
718 The string to use when expanding \code{"{\%}prog"} in \code{usage} and
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
719 \code{version} instead of \code{os.path.basename(sys.argv{[}0])}.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
720 \end{description}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
721 \end{quote}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
722
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
723
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
724 \subsubsection{Populating the parser\label{optparse-populating-parser}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
725
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
726 There are several ways to populate the parser with options. The
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
727 preferred way is by using \code{OptionParser.add{\_}option()}, as shown in
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
728 section~\ref{optparse-tutorial}, the tutorial. \method{add{\_}option()} can be called in one of two
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
729 ways:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
730 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
731 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
732 pass it an Option instance (as returned by \function{make{\_}option()})
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
733
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
734 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
735 pass it any combination of positional and keyword arguments that are
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
736 acceptable to \function{make{\_}option()} (i.e., to the Option constructor),
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
737 and it will create the Option instance for you
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
738
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
739 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
740
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
741 The other alternative is to pass a list of pre-constructed Option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
742 instances to the OptionParser constructor, as in:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
743 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
744 option_list = [
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
745 make_option("-f", "--filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
746 action="store", type="string", dest="filename"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
747 make_option("-q", "--quiet",
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
748 action="store_false", dest="verbose"),
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
749 ]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
750 parser = OptionParser(option_list=option_list)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
751 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
752
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
753 (\function{make{\_}option()} is a factory function for creating Option instances;
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
754 currently it is an alias for the Option constructor. A future version
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
755 of \module{optparse} may split Option into several classes, and \function{make{\_}option()}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
756 will pick the right class to instantiate. Do not instantiate Option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
757 directly.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
758
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
759
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
760 \subsubsection{Defining options\label{optparse-defining-options}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
761
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
762 Each Option instance represents a set of synonymous command-line option
33974
d25615ef5d8f SF #1063757: fix markup error (had LaTeX markup in the reST source,
Greg Ward <gward@python.net>
parents: 33636
diff changeset
763 strings, e.g. \programopt{-f} and \longprogramopt{file}. You can
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
764 specify any number of short or long option strings, but you must specify
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
765 at least one overall option string.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
766
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
767 The canonical way to create an Option instance is with the
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
768 \method{add{\_}option()} method of \class{OptionParser}:
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
769 \begin{verbatim}
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
770 parser.add_option(opt_str[, ...], attr=value, ...)
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
771 \end{verbatim}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
772
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
773 To define an option with only a short option string:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
774 \begin{verbatim}
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
775 parser.add_option("-f", attr=value, ...)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
776 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
777
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
778 And to define an option with only a long option string:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
779 \begin{verbatim}
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
780 parser.add_option("--foo", attr=value, ...)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
781 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
782
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
783 The keyword arguments define attributes of the new Option object. The
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
784 most important option attribute is \member{action}, and it largely determines
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
785 which other attributes are relevant or required. If you pass irrelevant
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
786 option attributes, or fail to pass required ones, \module{optparse} raises an
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
787 OptionError exception explaining your mistake.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
788
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
789 An options's \emph{action} determines what \module{optparse} does when it encounters this
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
790 option on the command-line. The standard option actions hard-coded into
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
791 \module{optparse} are:
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
792 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
793 \item[\code{store}]
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
794 store this option's argument (default)
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
795 \item[\code{store{\_}const}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
796 store a constant value
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
797 \item[\code{store{\_}true}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
798 store a true value
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
799 \item[\code{store{\_}false}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
800 store a false value
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
801 \item[\code{append}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
802 append this option's argument to a list
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
803 \item[\code{append{\_}const}]
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
804 append a constant value to a list
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
805 \item[\code{count}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
806 increment a counter by one
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
807 \item[\code{callback}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
808 call a specified function
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
809 \item[\member{help}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
810 print a usage message including all options and the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
811 documentation for them
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
812 \end{description}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
813
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
814 (If you don't supply an action, the default is \code{store}. For this
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
815 action, you may also supply \member{type} and \member{dest} option attributes; see
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
816 below.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
817
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
818 As you can see, most actions involve storing or updating a value
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
819 somewhere. \module{optparse} always creates a special object for this,
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
820 conventionally called \code{options} (it happens to be an instance of
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
821 \code{optparse.Values}). Option arguments (and various other values) are
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
822 stored as attributes of this object, according to the \member{dest}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
823 (destination) option attribute.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
824
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
825 For example, when you call
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
826 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
827 parser.parse_args()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
828 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
829
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
830 one of the first things \module{optparse} does is create the \code{options} object:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
831 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
832 options = Values()
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
833 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
834
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
835 If one of the options in this parser is defined with
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
836 \begin{verbatim}
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
837 parser.add_option("-f", "--file", action="store", type="string", dest="filename")
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
838 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
839
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
840 and the command-line being parsed includes any of the following:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
841 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
842 -ffoo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
843 -f foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
844 --file=foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
845 --file foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
846 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
847
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
848 then \module{optparse}, on seeing this option, will do the equivalent of
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
849 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
850 options.filename = "foo"
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
851 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
852
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
853 The \member{type} and \member{dest} option attributes are almost as important as
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
854 \member{action}, but \member{action} is the only one that makes sense for \emph{all}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
855 options.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
856
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
857
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
858 \subsubsection{Standard option actions\label{optparse-standard-option-actions}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
859
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
860 The various option actions all have slightly different requirements and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
861 effects. Most actions have several relevant option attributes which you
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
862 may specify to guide \module{optparse}'s behaviour; a few have required attributes,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
863 which you must specify for any option using that action.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
864 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
865 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
866 \code{store} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
867
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
868 The option must be followed by an argument, which is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
869 converted to a value according to \member{type} and stored in
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
870 \member{dest}. If \code{nargs} {\textgreater} 1, multiple arguments will be consumed
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
871 from the command line; all will be converted according to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
872 \member{type} and stored to \member{dest} as a tuple. See the ``Option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
873 types'' section below.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
874
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
875 If \code{choices} is supplied (a list or tuple of strings), the type
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
876 defaults to \code{choice}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
877
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
878 If \member{type} is not supplied, it defaults to \code{string}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
879
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
880 If \member{dest} is not supplied, \module{optparse} derives a destination from the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
881 first long option string (e.g., \code{"-{}-foo-bar"} implies \code{foo{\_}bar}).
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
882 If there are no long option strings, \module{optparse} derives a destination from
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
883 the first short option string (e.g., \code{"-f"} implies \code{f}).
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
884
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
885 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
886 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
887 parser.add_option("-f")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
888 parser.add_option("-p", type="float", nargs=3, dest="point")
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
889 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
890
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
891 As it parses the command line
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
892 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
893 -f foo.txt -p 1 -3.5 4 -fbar.txt
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
894 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
895
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
896 \module{optparse} will set
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
897 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
898 options.f = "foo.txt"
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
899 options.point = (1.0, -3.5, 4.0)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
900 options.f = "bar.txt"
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
901 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
902
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
903 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
904 \code{store{\_}const} {[}required: \code{const}; relevant: \member{dest}]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
905
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
906 The value \code{const} is stored in \member{dest}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
907
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
908 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
909 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
910 parser.add_option("-q", "--quiet",
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
911 action="store_const", const=0, dest="verbose")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
912 parser.add_option("-v", "--verbose",
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
913 action="store_const", const=1, dest="verbose")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
914 parser.add_option("--noisy",
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
915 action="store_const", const=2, dest="verbose")
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
916 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
917
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
918 If \code{"-{}-noisy"} is seen, \module{optparse} will set
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
919 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
920 options.verbose = 2
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
921 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
922
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
923 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
924 \code{store{\_}true} {[}relevant: \member{dest}]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
925
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
926 A special case of \code{store{\_}const} that stores a true value
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
927 to \member{dest}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
928
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
929 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
930 \code{store{\_}false} {[}relevant: \member{dest}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
931
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
932 Like \code{store{\_}true}, but stores a false value.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
933
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
934 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
935 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
936 parser.add_option("--clobber", action="store_true", dest="clobber")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
937 parser.add_option("--no-clobber", action="store_false", dest="clobber")
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
938 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
939
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
940 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
941 \code{append} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
942
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
943 The option must be followed by an argument, which is appended to the
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
944 list in \member{dest}. If no default value for \member{dest} is supplied, an
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
945 empty list is automatically created when \module{optparse} first encounters this
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
946 option on the command-line. If \code{nargs} {\textgreater} 1, multiple arguments are
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
947 consumed, and a tuple of length \code{nargs} is appended to \member{dest}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
948
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
949 The defaults for \member{type} and \member{dest} are the same as for the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
950 \code{store} action.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
951
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
952 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
953 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
954 parser.add_option("-t", "--tracks", action="append", type="int")
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
955 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
956
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
957 If \code{"-t3"} is seen on the command-line, \module{optparse} does the equivalent of:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
958 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
959 options.tracks = []
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
960 options.tracks.append(int("3"))
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
961 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
962
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
963 If, a little later on, \code{"-{}-tracks=4"} is seen, it does:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
964 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
965 options.tracks.append(int("4"))
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
966 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
967
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
968 \item {}
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
969 \code{append{\_}const} {[}required: \code{const}; relevant: \member{dest}]
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
970
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
971 Like \code{store{\_}const}, but the value \code{const} is appended to \member{dest};
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
972 as with \code{append}, \member{dest} defaults to \code{None}, and an an empty list is
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
973 automatically created the first time the option is encountered.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
974
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
975 \item {}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
976 \code{count} {[}relevant: \member{dest}]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
977
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
978 Increment the integer stored at \member{dest}. If no default value is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
979 supplied, \member{dest} is set to zero before being incremented the first
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
980 time.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
981
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
982 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
983 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
984 parser.add_option("-v", action="count", dest="verbosity")
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
985 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
986
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
987 The first time \code{"-v"} is seen on the command line, \module{optparse} does the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
988 equivalent of:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
989 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
990 options.verbosity = 0
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
991 options.verbosity += 1
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
992 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
993
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
994 Every subsequent occurrence of \code{"-v"} results in
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
995 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
996 options.verbosity += 1
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
997 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
998
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
999 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1000 \code{callback} {[}required: \code{callback};
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1001 relevant: \member{type}, \code{nargs}, \code{callback{\_}args}, \code{callback{\_}kwargs}]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1002
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1003 Call the function specified by \code{callback}, which is called as
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1004 \begin{verbatim}
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1005 func(option, opt_str, value, parser, *args, **kwargs)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1006 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1007
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1008 See section~\ref{optparse-option-callbacks}, Option Callbacks for more detail.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1009
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1010 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1011 \member{help}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1012
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1013 Prints a complete help message for all the options in the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1014 current option parser. The help message is constructed from
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1015 the \code{usage} string passed to OptionParser's constructor and
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1016 the \member{help} string passed to every option.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1017
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1018 If no \member{help} string is supplied for an option, it will still be
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1019 listed in the help message. To omit an option entirely, use
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1020 the special value \code{optparse.SUPPRESS{\_}HELP}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1021
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1022 \module{optparse} automatically adds a \member{help} option to all OptionParsers, so
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1023 you do not normally need to create one.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1024
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1025 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1026 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1027 from optparse import OptionParser, SUPPRESS_HELP
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1028
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1029 parser = OptionParser()
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1030 parser.add_option("-h", "--help", action="help"),
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1031 parser.add_option("-v", action="store_true", dest="verbose",
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1032 help="Be moderately verbose")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1033 parser.add_option("--file", dest="filename",
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1034 help="Input file to read data from"),
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1035 parser.add_option("--secret", help=SUPPRESS_HELP)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1036 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1037
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1038 If \module{optparse} sees either \code{"-h"} or \code{"-{}-help"} on the command line, it
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1039 will print something like the following help message to stdout
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1040 (assuming \code{sys.argv{[}0]} is \code{"foo.py"}):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1041 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1042 usage: foo.py [options]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1043
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1044 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1045 -h, --help Show this help message and exit
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1046 -v Be moderately verbose
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1047 --file=FILENAME Input file to read data from
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1048 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1049
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1050 After printing the help message, \module{optparse} terminates your process
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1051 with \code{sys.exit(0)}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1052
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1053 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1054 \code{version}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1055
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1056 Prints the version number supplied to the OptionParser to stdout and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1057 exits. The version number is actually formatted and printed by the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1058 \code{print{\_}version()} method of OptionParser. Generally only relevant
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1059 if the \code{version} argument is supplied to the OptionParser
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1060 constructor. As with \member{help} options, you will rarely create
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1061 \code{version} options, since \module{optparse} automatically adds them when needed.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1062
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1063 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1064
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1065
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1066 \subsubsection{Option attributes\label{optparse-option-attributes}}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1067
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1068 The following option attributes may be passed as keyword arguments
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1069 to \code{parser.add{\_}option()}. If you pass an option attribute
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1070 that is not relevant to a particular option, or fail to pass a required
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1071 option attribute, \module{optparse} raises OptionError.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1072 \begin{itemize}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1073 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1074 \member{action} (default: \code{"store"})
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1075
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1076 Determines \module{optparse}'s behaviour when this option is seen on the command
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1077 line; the available options are documented above.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1078
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1079 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1080 \member{type} (default: \code{"string"})
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1081
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1082 The argument type expected by this option (e.g., \code{"string"} or
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1083 \code{"int"}); the available option types are documented below.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1084
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1085 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1086 \member{dest} (default: derived from option strings)
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1087
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1088 If the option's action implies writing or modifying a value somewhere,
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1089 this tells \module{optparse} where to write it: \member{dest} names an attribute of the
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1090 \code{options} object that \module{optparse} builds as it parses the command line.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1091
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1092 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1093 \code{default} (deprecated)
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1094
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1095 The value to use for this option's destination if the option is not
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1096 seen on the command line. Deprecated; use \code{parser.set{\_}defaults()}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1097 instead.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1098
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1099 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1100 \code{nargs} (default: 1)
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1101
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1102 How many arguments of type \member{type} should be consumed when this
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1103 option is seen. If {\textgreater} 1, \module{optparse} will store a tuple of values to
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1104 \member{dest}.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1105
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1106 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1107 \code{const}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1108
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1109 For actions that store a constant value, the constant value to store.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1110
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1111 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1112 \code{choices}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1113
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1114 For options of type \code{"choice"}, the list of strings the user
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1115 may choose from.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1116
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1117 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1118 \code{callback}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1119
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1120 For options with action \code{"callback"}, the callable to call when this
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1121 option is seen. See section~\ref{optparse-option-callbacks}, Option Callbacks for detail on the arguments
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1122 passed to \code{callable}.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1123
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1124 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1125 \code{callback{\_}args}, \code{callback{\_}kwargs}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1126
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1127 Additional positional and keyword arguments to pass to \code{callback}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1128 after the four standard callback arguments.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1129
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1130 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1131 \member{help}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1132
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1133 Help text to print for this option when listing all available options
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1134 after the user supplies a \member{help} option (such as \code{"-{}-help"}).
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1135 If no help text is supplied, the option will be listed without help
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1136 text. To hide this option, use the special value \code{SUPPRESS{\_}HELP}.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1137
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1138 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1139 \code{metavar} (default: derived from option strings)
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1140
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1141 Stand-in for the option argument(s) to use when printing help text.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1142 See section~\ref{optparse-tutorial}, the tutorial for an example.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1143
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1144 \end{itemize}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1145
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1146
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1147 \subsubsection{Standard option types\label{optparse-standard-option-types}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1148
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1149 \module{optparse} has six built-in option types: \code{string}, \code{int}, \code{long},
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1150 \code{choice}, \code{float} and \code{complex}. If you need to add new option
38718
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1151 types, see section~\ref{optparse-extending-optparse}, Extending \module{optparse}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1152
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1153 Arguments to string options are not checked or converted in any way: the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1154 text on the command line is stored in the destination (or passed to the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1155 callback) as-is.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1156
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1157 Integer arguments (type \code{int} or \code{long}) are parsed as follows:
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1158 \begin{quote}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1159 \begin{itemize}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1160 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1161 if the number starts with \code{0x}, it is parsed as a hexadecimal number
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1162
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1163 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1164 if the number starts with \code{0}, it is parsed as an octal number
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1165
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1166 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1167 if the number starts with \code{0b}, is is parsed as a binary number
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1168
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1169 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1170 otherwise, the number is parsed as a decimal number
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1171
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1172 \end{itemize}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1173 \end{quote}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1174
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1175 The conversion is done by calling either \code{int()} or \code{long()} with
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1176 the appropriate base (2, 8, 10, or 16). If this fails, so will \module{optparse},
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1177 although with a more useful error message.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1178
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1179 \code{float} and \code{complex} option arguments are converted directly with
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1180 \code{float()} and \code{complex()}, with similar error-handling.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1181
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1182 \code{choice} options are a subtype of \code{string} options. The \code{choices}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1183 option attribute (a sequence of strings) defines the set of allowed
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1184 option arguments. \code{optparse.check{\_}choice()} compares
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1185 user-supplied option arguments against this master list and raises
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1186 OptionValueError if an invalid string is given.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1187
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1188
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1189 \subsubsection{Parsing arguments\label{optparse-parsing-arguments}}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1190
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1191 The whole point of creating and populating an OptionParser is to call
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1192 its \method{parse{\_}args()} method:
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1193 \begin{verbatim}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1194 (options, args) = parser.parse_args(args=None, options=None)
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1195 \end{verbatim}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1196
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1197 where the input parameters are
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1198 \begin{description}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1199 \item[\code{args}]
38745
ab253cd497d2 SF #1366250: optparse docs: fix inconsistency in variable name; minor tweaks.
Greg Ward <gward@python.net>
parents: 38718
diff changeset
1200 the list of arguments to process (default: \code{sys.argv{[}1:]})
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1201 \item[\code{options}]
38745
ab253cd497d2 SF #1366250: optparse docs: fix inconsistency in variable name; minor tweaks.
Greg Ward <gward@python.net>
parents: 38718
diff changeset
1202 object to store option arguments in (default: a new instance of
ab253cd497d2 SF #1366250: optparse docs: fix inconsistency in variable name; minor tweaks.
Greg Ward <gward@python.net>
parents: 38718
diff changeset
1203 optparse.Values)
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1204 \end{description}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1205
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1206 and the return values are
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1207 \begin{description}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1208 \item[\code{options}]
38745
ab253cd497d2 SF #1366250: optparse docs: fix inconsistency in variable name; minor tweaks.
Greg Ward <gward@python.net>
parents: 38718
diff changeset
1209 the same object that was passed in as \code{options}, or the
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1210 optparse.Values instance created by \module{optparse}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1211 \item[\code{args}]
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1212 the leftover positional arguments after all options have been
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1213 processed
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1214 \end{description}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1215
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1216 The most common usage is to supply neither keyword argument. If you
38745
ab253cd497d2 SF #1366250: optparse docs: fix inconsistency in variable name; minor tweaks.
Greg Ward <gward@python.net>
parents: 38718
diff changeset
1217 supply \code{options}, it will be modified with repeated \code{setattr()}
ab253cd497d2 SF #1366250: optparse docs: fix inconsistency in variable name; minor tweaks.
Greg Ward <gward@python.net>
parents: 38718
diff changeset
1218 calls (roughly one for every option argument stored to an option
ab253cd497d2 SF #1366250: optparse docs: fix inconsistency in variable name; minor tweaks.
Greg Ward <gward@python.net>
parents: 38718
diff changeset
1219 destination) and returned by \method{parse{\_}args()}.
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1220
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1221 If \method{parse{\_}args()} encounters any errors in the argument list, it calls
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1222 the OptionParser's \method{error()} method with an appropriate end-user error
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1223 message. This ultimately terminates your process with an exit status of
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1224 2 (the traditional \UNIX{} exit status for command-line errors).
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1225
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1226
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1227 \subsubsection{Querying and manipulating your option parser\label{optparse-querying-manipulating-option-parser}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1228
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1229 Sometimes, it's useful to poke around your option parser and see what's
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1230 there. OptionParser provides a couple of methods to help you out:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1231 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1232 \item[\code{has{\_}option(opt{\_}str)}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1233 Return true if the OptionParser has an option with
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1234 option string \code{opt{\_}str} (e.g., \code{"-q"} or \code{"-{}-verbose"}).
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1235 \item[\code{get{\_}option(opt{\_}str)}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1236 Returns the Option instance with the option string \code{opt{\_}str}, or
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1237 \code{None} if no options have that option string.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1238 \item[\code{remove{\_}option(opt{\_}str)}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1239 If the OptionParser has an option corresponding to \code{opt{\_}str},
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1240 that option is removed. If that option provided any other
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1241 option strings, all of those option strings become invalid.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1242 If \code{opt{\_}str} does not occur in any option belonging to this
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1243 OptionParser, raises ValueError.
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1244 \end{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1245
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1246
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1247 \subsubsection{Conflicts between options\label{optparse-conflicts-between-options}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1248
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1249 If you're not careful, it's easy to define options with conflicting
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1250 option strings:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1251 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1252 parser.add_option("-n", "--dry-run", ...)
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1253 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1254 parser.add_option("-n", "--noisy", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1255 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1256
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1257 (This is particularly true if you've defined your own OptionParser
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1258 subclass with some standard options.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1259
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1260 Every time you add an option, \module{optparse} checks for conflicts with existing
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1261 options. If it finds any, it invokes the current conflict-handling
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1262 mechanism. You can set the conflict-handling mechanism either in the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1263 constructor:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1264 \begin{verbatim}
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1265 parser = OptionParser(..., conflict_handler=handler)
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1266 \end{verbatim}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1267
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1268 or with a separate call:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1269 \begin{verbatim}
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1270 parser.set_conflict_handler(handler)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1271 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1272
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1273 The available conflict handlers are:
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1274 \begin{quote}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1275 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1276 \item[\code{error} (default)]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1277 assume option conflicts are a programming error and raise
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1278 OptionConflictError
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1279 \item[\code{resolve}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1280 resolve option conflicts intelligently (see below)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1281 \end{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1282 \end{quote}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1283
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1284 As an example, let's define an OptionParser that resolves conflicts
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1285 intelligently and add conflicting options to it:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1286 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1287 parser = OptionParser(conflict_handler="resolve")
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1288 parser.add_option("-n", "--dry-run", ..., help="do no harm")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1289 parser.add_option("-n", "--noisy", ..., help="be noisy")
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1290 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1291
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1292 At this point, \module{optparse} detects that a previously-added option is already
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1293 using the \code{"-n"} option string. Since \code{conflict{\_}handler} is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1294 \code{"resolve"}, it resolves the situation by removing \code{"-n"} from the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1295 earlier option's list of option strings. Now \code{"-{}-dry-run"} is the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1296 only way for the user to activate that option. If the user asks for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1297 help, the help message will reflect that:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1298 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1299 options:
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1300 --dry-run do no harm
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1301 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1302 -n, --noisy be noisy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1303 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1304
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1305 It's possible to whittle away the option strings for a previously-added
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1306 option until there are none left, and the user has no way of invoking
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1307 that option from the command-line. In that case, \module{optparse} removes that
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1308 option completely, so it doesn't show up in help text or anywhere else.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1309 Carrying on with our existing OptionParser:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1310 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1311 parser.add_option("--dry-run", ..., help="new dry-run option")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1312 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1313
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1314 At this point, the original \programopt{-n/-{}-dry-run} option is no longer
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1315 accessible, so \module{optparse} removes it, leaving this help text:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1316 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1317 options:
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1318 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1319 -n, --noisy be noisy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1320 --dry-run new dry-run option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1321 \end{verbatim}
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1322
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1323
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1324 \subsubsection{Cleanup\label{optparse-cleanup}}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1325
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1326 OptionParser instances have several cyclic references. This should not
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1327 be a problem for Python's garbage collector, but you may wish to break
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1328 the cyclic references explicitly by calling \code{destroy()} on your
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1329 OptionParser once you are done with it. This is particularly useful in
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1330 long-running applications where large object graphs are reachable from
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1331 your OptionParser.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1332
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1333
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1334 \subsubsection{Other methods\label{optparse-other-methods}}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1335
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1336 OptionParser supports several other public methods:
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1337 \begin{itemize}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1338 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1339 \code{set{\_}usage(usage)}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1340
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1341 Set the usage string according to the rules described above for the
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1342 \code{usage} constructor keyword argument. Passing \code{None} sets the
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1343 default usage string; use \code{SUPPRESS{\_}USAGE} to suppress a usage
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1344 message.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1345
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1346 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1347 \code{enable{\_}interspersed{\_}args()}, \code{disable{\_}interspersed{\_}args()}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1348
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1349 Enable/disable positional arguments interspersed with options, similar
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1350 to GNU getopt (enabled by default). For example, if \code{"-a"} and
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1351 \code{"-b"} are both simple options that take no arguments, \module{optparse}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1352 normally accepts this syntax:
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1353 \begin{verbatim}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1354 prog -a arg1 -b arg2
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1355 \end{verbatim}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1356
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1357 and treats it as equivalent to
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1358 \begin{verbatim}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1359 prog -a -b arg1 arg2
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1360 \end{verbatim}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1361
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1362 To disable this feature, call \code{disable{\_}interspersed{\_}args()}. This
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1363 restores traditional \UNIX{} syntax, where option parsing stops with the
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1364 first non-option argument.
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1365
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1366 \item {}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1367 \code{set{\_}defaults(dest=value, ...)}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1368
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1369 Set default values for several option destinations at once. Using
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1370 \method{set{\_}defaults()} is the preferred way to set default values for
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1371 options, since multiple options can share the same destination. For
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1372 example, if several ``mode'' options all set the same destination, any
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1373 one of them can set the default, and the last one wins:
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1374 \begin{verbatim}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1375 parser.add_option("--advanced", action="store_const",
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1376 dest="mode", const="advanced",
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1377 default="novice") # overridden below
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1378 parser.add_option("--novice", action="store_const",
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1379 dest="mode", const="novice",
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1380 default="advanced") # overrides above setting
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1381 \end{verbatim}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1382
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1383 To avoid this confusion, use \method{set{\_}defaults()}:
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1384 \begin{verbatim}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1385 parser.set_defaults(mode="advanced")
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1386 parser.add_option("--advanced", action="store_const",
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1387 dest="mode", const="advanced")
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1388 parser.add_option("--novice", action="store_const",
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1389 dest="mode", const="novice")
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1390 \end{verbatim}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1391
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1392 \end{itemize}
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1393 % $Id: reference.txt 505 2005-07-22 01:52:40Z gward $
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1394
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1395
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1396 \subsection{Option Callbacks\label{optparse-option-callbacks}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1397
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1398 When \module{optparse}'s built-in actions and types aren't quite enough for your
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1399 needs, you have two choices: extend \module{optparse} or define a callback option.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1400 Extending \module{optparse} is more general, but overkill for a lot of simple
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1401 cases. Quite often a simple callback is all you need.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1402
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1403 There are two steps to defining a callback option:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1404 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1405 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1406 define the option itself using the \code{callback} action
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1407
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1408 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1409 write the callback; this is a function (or method) that
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1410 takes at least four arguments, as described below
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1411
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1412 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1413
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1414
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1415 \subsubsection{Defining a callback option\label{optparse-defining-callback-option}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1416
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1417 As always, the easiest way to define a callback option is by using the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1418 \code{parser.add{\_}option()} method. Apart from \member{action}, the only option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1419 attribute you must specify is \code{callback}, the function to call:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1420 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1421 parser.add_option("-c", action="callback", callback=my_callback)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1422 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1423
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1424 \code{callback} is a function (or other callable object), so you must have
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1425 already defined \code{my{\_}callback()} when you create this callback option.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1426 In this simple case, \module{optparse} doesn't even know if \programopt{-c} takes any
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1427 arguments, which usually means that the option takes no arguments{---}the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1428 mere presence of \programopt{-c} on the command-line is all it needs to know. In
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1429 some circumstances, though, you might want your callback to consume an
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1430 arbitrary number of command-line arguments. This is where writing
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1431 callbacks gets tricky; it's covered later in this section.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1432
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1433 \module{optparse} always passes four particular arguments to your callback, and it
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1434 will only pass additional arguments if you specify them via
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1435 \code{callback{\_}args} and \code{callback{\_}kwargs}. Thus, the minimal callback
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1436 function signature is:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1437 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1438 def my_callback(option, opt, value, parser):
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1439 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1440
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1441 The four arguments to a callback are described below.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1442
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1443 There are several other option attributes that you can supply when you
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1444 define a callback option:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1445 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1446 \item[\member{type}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1447 has its usual meaning: as with the \code{store} or \code{append} actions,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1448 it instructs \module{optparse} to consume one argument and convert it to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1449 \member{type}. Rather than storing the converted value(s) anywhere,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1450 though, \module{optparse} passes it to your callback function.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1451 \item[\code{nargs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1452 also has its usual meaning: if it is supplied and {\textgreater} 1, \module{optparse} will
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1453 consume \code{nargs} arguments, each of which must be convertible to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1454 \member{type}. It then passes a tuple of converted values to your
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1455 callback.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1456 \item[\code{callback{\_}args}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1457 a tuple of extra positional arguments to pass to the callback
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1458 \item[\code{callback{\_}kwargs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1459 a dictionary of extra keyword arguments to pass to the callback
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1460 \end{description}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1461
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1462
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1463 \subsubsection{How callbacks are called\label{optparse-how-callbacks-called}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1464
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1465 All callbacks are called as follows:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1466 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1467 func(option, opt_str, value, parser, *args, **kwargs)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1468 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1469
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1470 where
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1471 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1472 \item[\code{option}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1473 is the Option instance that's calling the callback
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1474 \item[\code{opt{\_}str}]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1475 is the option string seen on the command-line that's triggering the
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1476 callback. (If an abbreviated long option was used, \code{opt{\_}str} will
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1477 be the full, canonical option string{---}e.g. if the user puts
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1478 \code{"-{}-foo"} on the command-line as an abbreviation for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1479 \code{"-{}-foobar"}, then \code{opt{\_}str} will be \code{"-{}-foobar"}.)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1480 \item[\code{value}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1481 is the argument to this option seen on the command-line. \module{optparse} will
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1482 only expect an argument if \member{type} is set; the type of \code{value}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1483 will be the type implied by the option's type. If \member{type} for this
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1484 option is \code{None} (no argument expected), then \code{value} will be
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1485 \code{None}. If \code{nargs} {\textgreater} 1, \code{value} will be a tuple of values of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1486 the appropriate type.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1487 \item[\code{parser}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1488 is the OptionParser instance driving the whole thing, mainly
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1489 useful because you can access some other interesting data through
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1490 its instance attributes:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1491 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1492 \item[\code{parser.largs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1493 the current list of leftover arguments, ie. arguments that have
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1494 been consumed but are neither options nor option arguments.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1495 Feel free to modify \code{parser.largs}, e.g. by adding more
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1496 arguments to it. (This list will become \code{args}, the second
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1497 return value of \method{parse{\_}args()}.)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1498 \item[\code{parser.rargs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1499 the current list of remaining arguments, ie. with \code{opt{\_}str} and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1500 \code{value} (if applicable) removed, and only the arguments
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1501 following them still there. Feel free to modify
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1502 \code{parser.rargs}, e.g. by consuming more arguments.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1503 \item[\code{parser.values}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1504 the object where option values are by default stored (an
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1505 instance of optparse.OptionValues). This lets callbacks use the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1506 same mechanism as the rest of \module{optparse} for storing option values;
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1507 you don't need to mess around with globals or closures. You can
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1508 also access or modify the value(s) of any options already
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1509 encountered on the command-line.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1510 \end{description}
34287
3ec54c5f7081 SF bug #1090139: presentation typo in lib: 6.21.4.2 How callbacks are called
Raymond Hettinger <python@rcn.com>
parents: 33974
diff changeset
1511 \item[\code{args}]
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1512 is a tuple of arbitrary positional arguments supplied via the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1513 \code{callback{\_}args} option attribute.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1514 \item[\code{kwargs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1515 is a dictionary of arbitrary keyword arguments supplied via
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1516 \code{callback{\_}kwargs}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1517 \end{description}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1518
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1519
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1520 \subsubsection{Raising errors in a callback\label{optparse-raising-errors-in-callback}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1521
37929
88da84776119 Update optparse to Optik 1.5.1.
Greg Ward <gward@python.net>
parents: 37064
diff changeset
1522 The callback function should raise OptionValueError if there are any
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1523 problems with the option or its argument(s). \module{optparse} catches this and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1524 terminates the program, printing the error message you supply to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1525 stderr. Your message should be clear, concise, accurate, and mention
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1526 the option at fault. Otherwise, the user will have a hard time
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1527 figuring out what he did wrong.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1528
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1529
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1530 \subsubsection{Callback example 1: trivial callback\label{optparse-callback-example-1}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1531
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1532 Here's an example of a callback option that takes no arguments, and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1533 simply records that the option was seen:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1534 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1535 def record_foo_seen(option, opt_str, value, parser):
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1536 parser.saw_foo = True
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1537
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1538 parser.add_option("--foo", action="callback", callback=record_foo_seen)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1539 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1540
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1541 Of course, you could do that with the \code{store{\_}true} action.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1542
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1543
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1544 \subsubsection{Callback example 2: check option order\label{optparse-callback-example-2}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1545
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1546 Here's a slightly more interesting example: record the fact that
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1547 \code{"-a"} is seen, but blow up if it comes after \code{"-b"} in the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1548 command-line.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1549 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1550 def check_order(option, opt_str, value, parser):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1551 if parser.values.b:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1552 raise OptionValueError("can't use -a after -b")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1553 parser.values.a = 1
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1554 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1555 parser.add_option("-a", action="callback", callback=check_order)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1556 parser.add_option("-b", action="store_true", dest="b")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1557 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1558
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1559
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1560 \subsubsection{Callback example 3: check option order (generalized)\label{optparse-callback-example-3}}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1561
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1562 If you want to re-use this callback for several similar options (set a
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1563 flag, but blow up if \code{"-b"} has already been seen), it needs a bit of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1564 work: the error message and the flag that it sets must be
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1565 generalized.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1566 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1567 def check_order(option, opt_str, value, parser):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1568 if parser.values.b:
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1569 raise OptionValueError("can't use %s after -b" % opt_str)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1570 setattr(parser.values, option.dest, 1)
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1571 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1572 parser.add_option("-a", action="callback", callback=check_order, dest='a')
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1573 parser.add_option("-b", action="store_true", dest="b")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1574 parser.add_option("-c", action="callback", callback=check_order, dest='c')
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1575 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1576
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1577
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1578 \subsubsection{Callback example 4: check arbitrary condition\label{optparse-callback-example-4}}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1579
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1580 Of course, you could put any condition in there{---}you're not limited
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1581 to checking the values of already-defined options. For example, if
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1582 you have options that should not be called when the moon is full, all
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1583 you have to do is this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1584 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1585 def check_moon(option, opt_str, value, parser):
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1586 if is_moon_full():
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1587 raise OptionValueError("%s option invalid when moon is full"
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1588 % opt_str)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1589 setattr(parser.values, option.dest, 1)
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1590 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1591 parser.add_option("--foo",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1592 action="callback", callback=check_moon, dest="foo")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1593 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1594
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1595 (The definition of \code{is{\_}moon{\_}full()} is left as an exercise for the
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1596 reader.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1597
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1598
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1599 \subsubsection{Callback example 5: fixed arguments\label{optparse-callback-example-5}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1600
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1601 Things get slightly more interesting when you define callback options
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1602 that take a fixed number of arguments. Specifying that a callback
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1603 option takes arguments is similar to defining a \code{store} or \code{append}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1604 option: if you define \member{type}, then the option takes one argument that
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1605 must be convertible to that type; if you further define \code{nargs}, then
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1606 the option takes \code{nargs} arguments.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1607
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1608 Here's an example that just emulates the standard \code{store} action:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1609 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1610 def store_value(option, opt_str, value, parser):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1611 setattr(parser.values, option.dest, value)
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1612 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1613 parser.add_option("--foo",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1614 action="callback", callback=store_value,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1615 type="int", nargs=3, dest="foo")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1616 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1617
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1618 Note that \module{optparse} takes care of consuming 3 arguments and converting them
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1619 to integers for you; all you have to do is store them. (Or whatever;
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1620 obviously you don't need a callback for this example.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1621
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1622
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1623 \subsubsection{Callback example 6: variable arguments\label{optparse-callback-example-6}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1624
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1625 Things get hairy when you want an option to take a variable number of
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1626 arguments. For this case, you must write a callback, as \module{optparse} doesn't
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1627 provide any built-in capabilities for it. And you have to deal with
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1628 certain intricacies of conventional \UNIX{} command-line parsing that \module{optparse}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1629 normally handles for you. In particular, callbacks should implement
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1630 the conventional rules for bare \code{"-{}-"} and \code{"-"} arguments:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1631 \begin{itemize}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1632 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1633 either \code{"-{}-"} or \code{"-"} can be option arguments
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1634
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1635 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1636 bare \code{"-{}-"} (if not the argument to some option): halt command-line
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1637 processing and discard the \code{"-{}-"}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1638
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1639 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1640 bare \code{"-"} (if not the argument to some option): halt command-line
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1641 processing but keep the \code{"-"} (append it to \code{parser.largs})
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1642
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1643 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1644
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1645 If you want an option that takes a variable number of arguments, there
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1646 are several subtle, tricky issues to worry about. The exact
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1647 implementation you choose will be based on which trade-offs you're
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1648 willing to make for your application (which is why \module{optparse} doesn't support
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1649 this sort of thing directly).
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1650
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1651 Nevertheless, here's a stab at a callback for an option with variable
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1652 arguments:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1653 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1654 def vararg_callback(option, opt_str, value, parser):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1655 assert value is None
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1656 done = 0
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1657 value = []
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1658 rargs = parser.rargs
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1659 while rargs:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1660 arg = rargs[0]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1661
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1662 # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1663 # etc. Note that this also stops on "-3" or "-3.0", so if
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1664 # your option takes numeric values, you will need to handle
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1665 # this.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1666 if ((arg[:2] == "--" and len(arg) > 2) or
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1667 (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")):
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1668 break
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1669 else:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1670 value.append(arg)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1671 del rargs[0]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1672
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1673 setattr(parser.values, option.dest, value)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1674
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1675 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1676 parser.add_option("-c", "--callback",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1677 action="callback", callback=varargs)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1678 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1679
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1680 The main weakness with this particular implementation is that negative
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1681 numbers in the arguments following \code{"-c"} will be interpreted as
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1682 further options (probably causing an error), rather than as arguments to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1683 \code{"-c"}. Fixing this is left as an exercise for the reader.
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1684 % $Id: callbacks.txt 415 2004-09-30 02:26:17Z greg $
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1685
38718
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1686
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1687 \subsection{Extending \module{optparse}\label{optparse-extending-optparse}}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1688
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1689 Since the two major controlling factors in how \module{optparse} interprets
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1690 command-line options are the action and type of each option, the most
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1691 likely direction of extension is to add new actions and new types.
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1692
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1693
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1694 \subsubsection{Adding new types\label{optparse-adding-new-types}}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1695
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1696 To add new types, you need to define your own subclass of \module{optparse}'s Option
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1697 class. This class has a couple of attributes that define \module{optparse}'s types:
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1698 \member{TYPES} and \member{TYPE{\_}CHECKER}.
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1699
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1700 \member{TYPES} is a tuple of type names; in your subclass, simply define a new
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1701 tuple \member{TYPES} that builds on the standard one.
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1702
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1703 \member{TYPE{\_}CHECKER} is a dictionary mapping type names to type-checking
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1704 functions. A type-checking function has the following signature:
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1705 \begin{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1706 def check_mytype(option, opt, value)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1707 \end{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1708
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1709 where \code{option} is an \class{Option} instance, \code{opt} is an option string
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1710 (e.g., \code{"-f"}), and \code{value} is the string from the command line that
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1711 must be checked and converted to your desired type. \code{check{\_}mytype()}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1712 should return an object of the hypothetical type \code{mytype}. The value
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1713 returned by a type-checking function will wind up in the OptionValues
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1714 instance returned by \method{OptionParser.parse{\_}args()}, or be passed to a
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1715 callback as the \code{value} parameter.
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1716
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1717 Your type-checking function should raise OptionValueError if it
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1718 encounters any problems. OptionValueError takes a single string
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1719 argument, which is passed as-is to OptionParser's \method{error()} method,
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1720 which in turn prepends the program name and the string \code{"error:"} and
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1721 prints everything to stderr before terminating the process.
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1722
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1723 Here's a silly example that demonstrates adding a \code{complex} option
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1724 type to parse Python-style complex numbers on the command line. (This
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1725 is even sillier than it used to be, because \module{optparse} 1.3 added built-in
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1726 support for complex numbers, but never mind.)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1727
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1728 First, the necessary imports:
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1729 \begin{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1730 from copy import copy
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1731 from optparse import Option, OptionValueError
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1732 \end{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1733
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1734 You need to define your type-checker first, since it's referred to later
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1735 (in the \member{TYPE{\_}CHECKER} class attribute of your Option subclass):
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1736 \begin{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1737 def check_complex(option, opt, value):
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1738 try:
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1739 return complex(value)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1740 except ValueError:
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1741 raise OptionValueError(
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1742 "option %s: invalid complex value: %r" % (opt, value))
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1743 \end{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1744
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1745 Finally, the Option subclass:
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1746 \begin{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1747 class MyOption (Option):
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1748 TYPES = Option.TYPES + ("complex",)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1749 TYPE_CHECKER = copy(Option.TYPE_CHECKER)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1750 TYPE_CHECKER["complex"] = check_complex
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1751 \end{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1752
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1753 (If we didn't make a \function{copy()} of \member{Option.TYPE{\_}CHECKER}, we would end
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1754 up modifying the \member{TYPE{\_}CHECKER} attribute of \module{optparse}'s Option class.
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1755 This being Python, nothing stops you from doing that except good manners
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1756 and common sense.)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1757
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1758 That's it! Now you can write a script that uses the new option type
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1759 just like any other \module{optparse}-based script, except you have to instruct your
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1760 OptionParser to use MyOption instead of Option:
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1761 \begin{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1762 parser = OptionParser(option_class=MyOption)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1763 parser.add_option("-c", type="complex")
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1764 \end{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1765
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1766 Alternately, you can build your own option list and pass it to
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1767 OptionParser; if you don't use \method{add{\_}option()} in the above way, you
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1768 don't need to tell OptionParser which option class to use:
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1769 \begin{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1770 option_list = [MyOption("-c", action="store", type="complex", dest="c")]
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1771 parser = OptionParser(option_list=option_list)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1772 \end{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1773
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1774
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1775 \subsubsection{Adding new actions\label{optparse-adding-new-actions}}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1776
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1777 Adding new actions is a bit trickier, because you have to understand
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1778 that \module{optparse} has a couple of classifications for actions:
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1779 \begin{description}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1780 \item[``store'' actions]
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1781 actions that result in \module{optparse} storing a value to an attribute of the
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1782 current OptionValues instance; these options require a \member{dest}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1783 attribute to be supplied to the Option constructor
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1784 \item[``typed'' actions]
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1785 actions that take a value from the command line and expect it to be
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1786 of a certain type; or rather, a string that can be converted to a
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1787 certain type. These options require a \member{type} attribute to the
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1788 Option constructor.
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1789 \end{description}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1790
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1791 These are overlapping sets: some default ``store'' actions are \code{store},
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1792 \code{store{\_}const}, \code{append}, and \code{count}, while the default ``typed''
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1793 actions are \code{store}, \code{append}, and \code{callback}.
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1794
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1795 When you add an action, you need to categorize it by listing it in at
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1796 least one of the following class attributes of Option (all are lists of
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1797 strings):
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1798 \begin{description}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1799 \item[\member{ACTIONS}]
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1800 all actions must be listed in ACTIONS
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1801 \item[\member{STORE{\_}ACTIONS}]
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1802 ``store'' actions are additionally listed here
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1803 \item[\member{TYPED{\_}ACTIONS}]
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1804 ``typed'' actions are additionally listed here
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1805 \item[\code{ALWAYS{\_}TYPED{\_}ACTIONS}]
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1806 actions that always take a type (i.e. whose options always take a
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1807 value) are additionally listed here. The only effect of this is
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1808 that \module{optparse} assigns the default type, \code{string}, to options with no
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1809 explicit type whose action is listed in \code{ALWAYS{\_}TYPED{\_}ACTIONS}.
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1810 \end{description}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1811
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1812 In order to actually implement your new action, you must override
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1813 Option's \method{take{\_}action()} method and add a case that recognizes your
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1814 action.
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1815
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1816 For example, let's add an \code{extend} action. This is similar to the
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1817 standard \code{append} action, but instead of taking a single value from
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1818 the command-line and appending it to an existing list, \code{extend} will
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1819 take multiple values in a single comma-delimited string, and extend an
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1820 existing list with them. That is, if \code{"-{}-names"} is an \code{extend}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1821 option of type \code{string}, the command line
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1822 \begin{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1823 --names=foo,bar --names blah --names ding,dong
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1824 \end{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1825
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1826 would result in a list
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1827 \begin{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1828 ["foo", "bar", "blah", "ding", "dong"]
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1829 \end{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1830
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1831 Again we define a subclass of Option:
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1832 \begin{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1833 class MyOption (Option):
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1834
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1835 ACTIONS = Option.ACTIONS + ("extend",)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1836 STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1837 TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1838 ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1839
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1840 def take_action(self, action, dest, opt, value, values, parser):
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1841 if action == "extend":
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1842 lvalue = value.split(",")
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1843 values.ensure_value(dest, []).extend(lvalue)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1844 else:
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1845 Option.take_action(
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1846 self, action, dest, opt, value, values, parser)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1847 \end{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1848
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1849 Features of note:
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1850 \begin{itemize}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1851 \item {}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1852 \code{extend} both expects a value on the command-line and stores that
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1853 value somewhere, so it goes in both \member{STORE{\_}ACTIONS} and
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1854 \member{TYPED{\_}ACTIONS}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1855
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1856 \item {}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1857 to ensure that \module{optparse} assigns the default type of \code{string} to
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1858 \code{extend} actions, we put the \code{extend} action in
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1859 \code{ALWAYS{\_}TYPED{\_}ACTIONS} as well
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1860
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1861 \item {}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1862 \method{MyOption.take{\_}action()} implements just this one new action, and
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1863 passes control back to \method{Option.take{\_}action()} for the standard
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1864 \module{optparse} actions
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1865
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1866 \item {}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1867 \code{values} is an instance of the optparse{\_}parser.Values class,
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1868 which provides the very useful \method{ensure{\_}value()} method.
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1869 \method{ensure{\_}value()} is essentially \function{getattr()} with a safety valve;
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1870 it is called as
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1871 \begin{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1872 values.ensure_value(attr, value)
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1873 \end{verbatim}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1874
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1875 If the \code{attr} attribute of \code{values} doesn't exist or is None, then
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1876 ensure{\_}value() first sets it to \code{value}, and then returns 'value.
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1877 This is very handy for actions like \code{extend}, \code{append}, and
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1878 \code{count}, all of which accumulate data in a variable and expect that
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1879 variable to be of a certain type (a list for the first two, an integer
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1880 for the latter). Using \method{ensure{\_}value()} means that scripts using
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1881 your action don't have to worry about setting a default value for the
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1882 option destinations in question; they can just leave the default as
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1883 None and \method{ensure{\_}value()} will take care of getting it right when
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1884 it's needed.
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1885
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1886 \end{itemize}
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1887 % $Id: extending.txt 517 2006-06-10 16:18:11Z gward $
3125099b3497 Sync with Optik docs (rev 518):
Greg Ward <gward@python.net>
parents: 37929
diff changeset
1888