Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/liboptparse.tex @ 37850:ebe59cd18273

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use explicit relative import for an, ehm, relative import.
author Thomas Wouters <thomas@python.org>
date Tue, 18 Apr 2006 21:41:36 +0000
parents 3ec54c5f7081
children 9d80e63004cd 64c83e0f683e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1 \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
2 \declaremodule{standard}{optparse}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
3 \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
4 \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
5 \versionadded{2.3}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
6 \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
7 % 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
8 % manual (based on README.txt).
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
9
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
10 \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
11 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
12 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
13 \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
14 \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
15 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
16
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
17 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
18 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
19 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
20 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
21 parser = OptionParser()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
22 parser.add_option("-f", "--file", dest="filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
23 help="write report to FILE", metavar="FILE")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
24 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
25 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
26 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
27
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
28 (options, args) = parser.parse_args()
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
29 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
30
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
31 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
32 ``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
33 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
34 <yourscript> --file=outfile -q
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
35 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
36
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
37 As it parses the command line, \code{optparse} sets attributes of the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
38 \var{options} object returned by \method{parse{\_}args()} based on user-supplied
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
39 command-line values. When \method{parse{\_}args()} returns from parsing this
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
40 command line, \var{options.filename} will be \code{"outfile"} and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
41 \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
42 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
43 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
44 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
45 example:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
46 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
47 <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
48 <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
49 <yourscript> -q -foutfile
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
50 <yourscript> -qfoutfile
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
51 \end{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
52
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
53 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
54 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
55 <yourscript> -h
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
56 <yourscript> --help
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
57 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
58
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
59 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
60 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
61 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
62 usage: <yourscript> [options]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
63
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
64 options:
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
65 -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
66 -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
67 -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
68 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
69
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
70 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
71 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
72 % $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
73
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
74
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
75 \subsection{Background\label{optparse-background}}
27116
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 \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
78 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
79 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
80 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
81 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
82
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
83
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
84 \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
85 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
86 \item[argument]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
87 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
88 \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
89 \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
90 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
91
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
92 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
93 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
94 \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
95 \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
96 \item[option ]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
97 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
98 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
99 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
100 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
101 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
102 e.g. \code{"-x -F"} is equivalent to \code{"-xF"}. The GNU project
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
103 introduced \code{"-{}-"} followed by a series of hyphen-separated words,
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{"-{}-file"} or \code{"-{}-dry-run"}. These are the only two option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
105 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
106
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
107 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
108 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
109 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
110 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
111 \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
112
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
113 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
114 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
115 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
116 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
117
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
118 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
119 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
120 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
121
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
122 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
123 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
124 \code{"/f"}, \code{"/file"}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
125
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
126 \end{itemize}
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 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
129 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
130 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
131 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
132 \item[option argument]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
133 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
134 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
135 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
136 from their option:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
137 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
138 -f foo
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
139 --file foo
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
140 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
141
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
142 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
143 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
144 -ffoo
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
145 --file=foo
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
146 \end{verbatim}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
147
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
148 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
149 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
150 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
151 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
152 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
153 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
154 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
155 \item[positional argument]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
156 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
157 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
158 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
159 \item[required option]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
160 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
161 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
162 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
163 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
164 \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
165 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
166 \end{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
167
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
168 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
169 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
170 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
171 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
172
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
173 \code{"-v"} and \code{"-{}-report"} are both options. Assuming that
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
174 \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
175 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
176
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
177
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
178 \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
179
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
180 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
181 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
182 \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
183 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
184 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
185 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
186 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
187 and confusing interfaces.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
188
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
189 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
190 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
191 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
192 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
193
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
194 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
195 \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
196 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
197 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
198 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
199 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
200 cp SOURCE DEST
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
201 cp SOURCE ... DEST-DIR
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
202 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
203
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
204 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
205 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
206 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
207 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
208 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
209 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
210
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
211
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
212 \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
213
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
214 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
215 program absolutely, positively requires to run.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
216
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
217 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
218 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
219 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
220 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
221 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
222 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
223 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
224
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
225 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
226 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
227 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
228 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
229 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
230 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
231 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
232 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
233 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
234 harder to maintain.
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
235 % $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
236
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
237
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
238 \subsection{Tutorial\label{optparse-tutorial}}
27116
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 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
241 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
242 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
243
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
244 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
245 main program, create an OptionParser instance:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
246 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
247 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
248 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
249 parser = OptionParser()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
250 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
251
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
252 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
253 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
254 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
255 attr=value, ...)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
256 \end{verbatim}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
257
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
258 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
259 \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
260 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
261 line.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
262
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
263 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
264 option string, e.g.:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
265 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
266 parser.add_option("-f", "--file", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
267 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
268
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
269 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
270 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
271 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
272
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
273 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
274 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
275 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
276 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
277
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
278 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
279 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
280 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
281 (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
282 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
283
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
284 (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
285 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
286
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
287 \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
288 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
289 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
290 \var{options}, an object containing values for all of your options{---}e.g. if \code{"-{}-file"} takes a single string argument, then
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
291 \var{options.file} will be the filename supplied by the user, or
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
292 \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
293
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
294 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
295 \var{args}, the list of positional arguments leftover after parsing
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
296 options
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
297
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
298 \end{itemize}
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 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
301 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
302 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
303
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
304
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
305 \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
306
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
307 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
308 command line. There is a fixed set of actions hard-coded into \module{optparse};
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
309 adding new actions is an advanced topic covered in section~\ref{optparse-extending}, Extending \module{optparse}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
310 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
311 example, take a string from the command line and store it in an
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
312 attribute of \var{options}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
313
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
314 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
315
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
316
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
317 \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
318
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
319 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
320 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
321 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
322
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
323 For example:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
324 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
325 parser.add_option("-f", "--file",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
326 action="store", type="string", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
327 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
328
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
329 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
330 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
331 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
332 (options, args) = parser.parse_args(args)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
333 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
334
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
335 When \module{optparse} sees the option string \code{"-f"}, it consumes the next
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
336 argument, \code{"foo.txt"}, and stores it in \var{options.filename}. So,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
337 after this call to \method{parse{\_}args()}, \var{options.filename} is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
338 \code{"foo.txt"}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
339
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
340 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
341 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
342 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
343 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
344 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
345
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
346 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
347 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
348 \code{store}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
349
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
350 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
351 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
352 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
353 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
354 (options, args) = parser.parse_args(["-n42"])
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
355 print options.num
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
356 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
357
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
358 will print \code{"42"}.
27116
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 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
361 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
362 can be a lot shorter:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
363 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
364 parser.add_option("-f", "--file", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
365 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
366
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
367 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
368 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
369 \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
370 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
371 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
372
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
373 \module{optparse} also includes built-in \code{long} and \code{complex} types. Adding
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
374 types is covered in section~\ref{optparse-extending}, Extending \module{optparse}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
375
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
376
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
377 \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
378
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
379 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
380 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
381 actions, \code{store{\_}true} and \code{store{\_}false}. For example, you might have a
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
382 \var{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
383 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
384 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
385 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
386 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
387
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
388 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
389 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
390 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
391
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
392 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
393 \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
394 \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
395
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
396
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
397 \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
398
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
399 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
400 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
401 \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
402 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
403 \item[\code{append}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
404 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
405 \item[\code{count}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
406 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
407 \item[\code{callback}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
408 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
409 \end{description}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
410
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
411 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
412
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
413
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
414 \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
415
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
416 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
417 ``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
418 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
419 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
420 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
421 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
422
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
423 First, consider the verbose/quiet example. If we want \module{optparse} to set
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
424 \var{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
425 \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
426 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
427 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
428 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
429
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
430 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
431 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
432 destination, this is exactly equivalent:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
433 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
434 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
435 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
436 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
437
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
438 Consider this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
439 \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
440 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
441 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
442 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
443
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
444 Again, the default value for \var{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
445 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
446 counts.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
447
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
448 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
449 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
450 \method{parse{\_}args()}:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
451 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
452 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
453 parser.add_option(...)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
454 (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
455 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
456
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
457 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
458 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
459 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
460
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
461
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
462 \subsubsection{Generating help\label{optparse-generating-help}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
463
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
464 \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
465 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
466 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
467 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
468 user-friendly (documented) options:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
469 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
470 usage = "usage: %prog [options] arg1 arg2"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
471 parser = OptionParser(usage=usage)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
472 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
473 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
474 help="make lots of noise [default]")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
475 parser.add_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
476 action="store_false", dest="verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
477 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
478 parser.add_option("-f", "--filename",
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
479 metavar="FILE", help="write output to FILE"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
480 parser.add_option("-m", "--mode",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
481 default="intermediate",
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
482 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
483 "or expert [default: %default]")
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
484 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
485
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
486 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
487 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
488 standard output:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
489 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
490 usage: <yourscript> [options] arg1 arg2
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
491
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
492 options:
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
493 -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
494 -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
495 -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
496 -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
497 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
498 -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
499 expert [default: intermediate]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
500 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
501
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
502 (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
503 printing the help text.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
504
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
505 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
506 help message:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
507 \begin{itemize}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
508 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
509 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
510 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
511 usage = "usage: %prog [options] arg1 arg2"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
512 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
513
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
514 \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
515 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
516 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
517
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
518 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
519 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
520 doesn't take any positional arguments.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
521
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
522 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
523 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
524 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
525 help output look good.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
526
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
527 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
528 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
529 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
530 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
531 -m MODE, --mode=MODE
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
532 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
533
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
534 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
535 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
536 \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
537 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
538 \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
539 description:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
540 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
541 -f FILE, --filename=FILE
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
542 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
543
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
544 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
545 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
546 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
547 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
548 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
549 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
550
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
551 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
552 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
553 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
554 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
555 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
556
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
557 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
558
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
559
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
560 \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
561
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
562 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
563 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
564 argument to OptionParser:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
565 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
566 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
567 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
568
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
569 Note that \code{"{\%}prog"} is expanded just like it is in \var{usage}. Apart
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
570 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
571 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
572 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
573 \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
574 exits.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
575
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
576 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
577 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
578 $ /usr/bin/foo --version
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
579 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
580 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
581
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
582
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
583 \subsubsection{How \module{optparse} handles errors\label{optparse-how-optik-handles-errors}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
584
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
585 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
586 programmer errors and user errors. Programmer errors are usually
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
587 erroneous calls to \code{parse.add{\_}option()}, e.g. invalid option strings,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
588 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
589 dealt with in the usual way: raise an exception (either
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
590 \code{optparse.OptionError} or \code{TypeError}) and let the program crash.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
591
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
592 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
593 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
594 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
595 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
596 (\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
597 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
598 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
599 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
600 (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
601 [...]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
602 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
603 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
604 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
605
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
606 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
607 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
608 exits with error status 2.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
609
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
610 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
611 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
612 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
613 $ /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
614 usage: foo [options]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
615
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
616 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
617 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
618
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
619 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
620 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
621 $ /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
622 usage: foo [options]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
623
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
624 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
625 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
626
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
627 \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
628 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
629 \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
630
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
631 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
632 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
633 \method{error()}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
634
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
635
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
636 \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
637
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
638 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
639 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
640 from optparse import OptionParser
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
641 [...]
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
642 def main():
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
643 usage = "usage: %prog [options] arg"
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
644 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
645 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
646 help="read data from FILENAME")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
647 parser.add_option("-v", "--verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
648 action="store_true", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
649 parser.add_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
650 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
651 [...]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
652 (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
653 if len(args) != 1:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
654 parser.error("incorrect number of arguments")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
655 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
656 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
657 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
658
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
659 if __name__ == "__main__":
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
660 main()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
661 \end{verbatim}
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
662 % $Id: tutorial.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
663
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
664
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
665 \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
666
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
667
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
668 \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
669
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
670 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
671 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
672 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
673 ways:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
674 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
675 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
676 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
677
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
678 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
679 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
680 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
681 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
682
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
683 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
684
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
685 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
686 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
687 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
688 option_list = [
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
689 make_option("-f", "--filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
690 action="store", type="string", dest="filename"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
691 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
692 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
693 ]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
694 parser = OptionParser(option_list=option_list)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
695 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
696
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
697 (\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
698 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
699 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
700 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
701 directly.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
702
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
703
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
704 \subsubsection{Defining options\label{optparse-defining-options}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
705
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
706 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
707 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
708 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
709 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
710
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
711 The canonical way to create an Option instance is by calling
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
712 \function{make{\_}option()}, so that is what will be shown here. However, the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
713 most common and convenient way is to use \code{parser.add{\_}option()}. Note
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
714 that \function{make{\_}option()} and \code{parser.add{\_}option()} have identical call
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
715 signatures:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
716 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
717 make_option(opt_str, ..., attr=value, ...)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
718 parser.add_option(opt_str, ..., attr=value, ...)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
719 \end{verbatim}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
720
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
721 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
722 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
723 make_option("-f", attr=value, ...)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
724 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
725
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
726 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
727 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
728 make_option("--foo", attr=value, ...)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
729 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
730
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
731 The \code{attr=value} keyword arguments define option attributes,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
732 i.e. attributes of the Option object. The most important option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
733 attribute is \member{action}, and it largely determines what other attributes
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
734 are relevant or required. If you pass irrelevant option attributes, or
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
735 fail to pass required ones, \module{optparse} raises an OptionError exception
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
736 explaining your mistake.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
737
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
738 An options's \emph{action} determines what \module{optparse} does when it encounters
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
739 this option on the command-line. The actions hard-coded into \module{optparse} are:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
740 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
741 \item[\code{store}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
742 store this option's argument {[}default]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
743 \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
744 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
745 \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
746 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
747 \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
748 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
749 \item[\code{append}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
750 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
751 \item[\code{count}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
752 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
753 \item[\code{callback}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
754 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
755 \item[\member{help}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
756 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
757 documentation for them
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
758 \end{description}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
759
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
760 (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
761 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
762 below.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
763
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
764 As you can see, most actions involve storing or updating a value
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
765 somewhere. \module{optparse} always creates an instance of \code{optparse.Values}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
766 specifically for this purpose; we refer to this instance as \var{options}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
767 Option arguments (and various other values) are stored as attributes of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
768 this object, according to the \member{dest} (destination) option attribute.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
769
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
770 For example, when you call
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
771 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
772 parser.parse_args()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
773 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
774
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
775 one of the first things \module{optparse} does is create the \var{options} object:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
776 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
777 options = Values()
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
778 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
779
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
780 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
781 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
782 make_option("-f", "--file", action="store", type="string", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
783 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
784
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
785 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
786 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
787 -ffoo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
788 -f foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
789 --file=foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
790 --file foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
791 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
792
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
793 then \module{optparse}, on seeing the \programopt{-f} or \longprogramopt{file} option, will do the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
794 equivalent of
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
795 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
796 options.filename = "foo"
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
797 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
798
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
799 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
800 \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
801 options.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
802
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
803
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
804 \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
805
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
806 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
807 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
808 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
809 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
810 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
811 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
812 \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
813
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
814 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
815 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
816 \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
817 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
818 \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
819 types'' section below.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
820
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
821 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
822 defaults to \code{choice}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
823
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
824 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
825
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
826 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
827 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
828 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
829 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
830
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
831 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
832 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
833 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
834 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
835 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
836
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
837 As it parses the command line
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
838 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
839 -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
840 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
841
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
842 \module{optparse} will set
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
843 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
844 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
845 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
846 options.f = "bar.txt"
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
847 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
848
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
849 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
850 \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
851
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
852 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
853
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
854 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
855 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
856 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
857 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
858 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
859 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
860 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
861 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
862 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
863
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
864 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
865 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
866 options.verbose = 2
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
867 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
868
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
869 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
870 \code{store{\_}true} {[}relevant: \member{dest}]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
871
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
872 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
873 to \member{dest}.
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 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
876 \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
877
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
878 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
879
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
880 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
881 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
882 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
883 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
884 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
885
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
886 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
887 \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
888
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
889 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
890 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
891 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
892 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
893 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
894
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
895 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
896 \code{store} action.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
897
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
898 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
899 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
900 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
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 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
904 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
905 options.tracks = []
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
906 options.tracks.append(int("3"))
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
907 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
908
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
909 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
910 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
911 options.tracks.append(int("4"))
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
912 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
913
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
914 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
915 \code{count} {[}relevant: \member{dest}]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
916
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
917 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
918 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
919 time.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
920
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
921 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
922 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
923 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
924 \end{verbatim}
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 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
927 equivalent of:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
928 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
929 options.verbosity = 0
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
930 options.verbosity += 1
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
931 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
932
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
933 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
934 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
935 options.verbosity += 1
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
936 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
937
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
938 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
939 \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
940 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
941
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
942 Call the function specified by \code{callback}. The signature of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
943 this function should be
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
944 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
945 func(option : Option,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
946 opt : string,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
947 value : any,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
948 parser : OptionParser,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
949 *args, **kwargs)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
950 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
951
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
952 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
953
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
954 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
955 \member{help}
27116
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 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
958 current option parser. The help message is constructed from
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
959 the \var{usage} string passed to OptionParser's constructor and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
960 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
961
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
962 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
963 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
964 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
965
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
966 \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
967 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
968
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
969 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
970 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
971 from optparse import OptionParser, SUPPRESS_HELP
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
972
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
973 parser = OptionParser()
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
974 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
975 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
976 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
977 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
978 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
979 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
980 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
981
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
982 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
983 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
984 (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
985 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
986 usage: foo.py [options]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
987
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
988 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
989 -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
990 -v Be moderately verbose
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
991 --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
992 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
993
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
994 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
995 with \code{sys.exit(0)}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
996
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
997 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
998 \code{version}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
999
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1000 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
1001 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
1002 \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
1003 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
1004 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
1005 \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
1006
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1007 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1008
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1009
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1010 \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
1011
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1012 \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
1013 \code{choice}, \code{float} and \code{complex}. If you need to add new option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1014 types, see section~\ref{optparse-extending}, Extending \module{optparse}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1015
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1016 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
1017 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
1018 callback) as-is.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1019
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1020 Integer arguments are passed to \code{int()} to convert them to Python
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1021 integers. If \code{int()} fails, so will \module{optparse}, although with a more
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1022 useful error message. (Internally, \module{optparse} raises OptionValueError;
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1023 OptionParser catches this exception higher up and terminates your
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1024 program with a useful error message.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1025
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1026 Likewise, \code{float} arguments are passed to \code{float()} for conversion,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1027 \code{long} arguments to \code{long()}, and \code{complex} arguments to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1028 \code{complex()}. Apart from that, they are handled identically to integer
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1029 arguments.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1030
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1031 \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
1032 option attribute (a sequence of strings) defines the set of allowed
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1033 option arguments. \code{optparse.option.check{\_}choice()} compares
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1034 user-supplied option arguments against this master list and raises
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1035 OptionValueError if an invalid string is given.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1036
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1037
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1038 \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
1039
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1040 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
1041 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
1042 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1043 \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
1044 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
1045 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
1046 \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
1047 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
1048 \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
1049 \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
1050 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
1051 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
1052 option strings, all of those option strings become invalid.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1053
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1054 If \code{opt{\_}str} does not occur in any option belonging to this
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1055 OptionParser, raises ValueError.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1056 \end{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1057
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1058
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1059 \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
1060
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1061 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
1062 option strings:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1063 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1064 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
1065 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1066 parser.add_option("-n", "--noisy", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1067 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1068
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1069 (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
1070 subclass with some standard options.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1071
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1072 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
1073 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
1074 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
1075 constructor:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1076 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1077 parser = OptionParser(..., conflict_handler="...")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1078 \end{verbatim}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1079
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1080 or with a separate call:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1081 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1082 parser.set_conflict_handler("...")
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1083 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1084
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1085 The available conflict-handling mechanisms are:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1086 \begin{quote}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1087 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1088 \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
1089 assume option conflicts are a programming error and raise
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1090 OptionConflictError
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1091 \item[\code{resolve}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1092 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
1093 \end{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1094 \end{quote}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1095
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1096 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
1097 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
1098 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1099 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
1100 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
1101 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
1102 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1103
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1104 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
1105 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
1106 \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
1107 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
1108 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
1109 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
1110 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1111 options:
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1112 --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
1113 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1114 -n, --noisy be noisy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1115 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1116
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1117 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
1118 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
1119 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
1120 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
1121 Carrying on with our existing OptionParser:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1122 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1123 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
1124 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1125
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1126 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
1127 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
1128 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1129 options:
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1130 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1131 -n, --noisy be noisy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1132 --dry-run new dry-run option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1133 \end{verbatim}
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1134 % $Id: reference.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
1135
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1136
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1137 \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
1138
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1139 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
1140 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
1141 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
1142 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
1143
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1144 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
1145 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1146 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1147 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
1148
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1149 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1150 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
1151 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
1152
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1153 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1154
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1155
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1156 \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
1157
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1158 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
1159 \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
1160 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
1161 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1162 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
1163 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1164
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1165 \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
1166 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
1167 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
1168 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
1169 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
1170 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
1171 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
1172 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
1173
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1174 \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
1175 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
1176 \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
1177 function signature is:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1178 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1179 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
1180 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1181
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1182 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
1183
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1184 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
1185 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
1186 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1187 \item[\member{type}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1188 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
1189 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
1190 \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
1191 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
1192 \item[\code{nargs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1193 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
1194 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
1195 \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
1196 callback.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1197 \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
1198 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
1199 \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
1200 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
1201 \end{description}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1202
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1203
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1204 \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
1205
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1206 All callbacks are called as follows:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1207 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1208 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
1209 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1210
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1211 where
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1212 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1213 \item[\code{option}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1214 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
1215 \item[\code{opt{\_}str}]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1216 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
1217 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
1218 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
1219 \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
1220 \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
1221 \item[\code{value}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1222 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
1223 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
1224 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
1225 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
1226 \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
1227 the appropriate type.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1228 \item[\code{parser}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1229 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
1230 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
1231 its instance attributes:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1232 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1233 \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
1234 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
1235 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
1236 Feel free to modify \code{parser.largs}, e.g. by adding more
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1237 arguments to it. (This list will become \var{args}, the second
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1238 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
1239 \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
1240 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
1241 \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
1242 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
1243 \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
1244 \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
1245 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
1246 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
1247 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
1248 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
1249 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
1250 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
1251 \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
1252 \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
1253 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
1254 \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
1255 \item[\code{kwargs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1256 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
1257 \code{callback{\_}kwargs}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1258 \end{description}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1259
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1260
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1261 \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
1262
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1263 The callback function should raise OptionValueError if there are any
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1264 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
1265 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
1266 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
1267 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
1268 figuring out what he did wrong.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1269
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1270
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1271 \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
1272
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1273 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
1274 simply records that the option was seen:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1275 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1276 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
1277 parser.saw_foo = True
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1278
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1279 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
1280 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1281
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1282 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
1283
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1284
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1285 \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
1286
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1287 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
1288 \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
1289 command-line.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1290 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1291 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
1292 if parser.values.b:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1293 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
1294 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
1295 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1296 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
1297 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
1298 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1299
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1300
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1301 \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
1302
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1303 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
1304 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
1305 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
1306 generalized.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1307 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1308 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
1309 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
1310 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
1311 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
1312 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1313 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
1314 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
1315 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
1316 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1317
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1318
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1319 \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
1320
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1321 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
1322 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
1323 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
1324 you have to do is this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1325 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1326 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
1327 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
1328 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
1329 % opt_str)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1330 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
1331 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1332 parser.add_option("--foo",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1333 action="callback", callback=check_moon, dest="foo")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1334 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1335
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1336 (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
1337 reader.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1338
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1339
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1340 \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
1341
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1342 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
1343 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
1344 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
1345 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
1346 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
1347 the option takes \code{nargs} arguments.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1348
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1349 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
1350 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1351 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
1352 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
1353 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1354 parser.add_option("--foo",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1355 action="callback", callback=store_value,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1356 type="int", nargs=3, dest="foo")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1357 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1358
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1359 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
1360 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
1361 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
1362
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1363
33636
e5de698ecd4b Get references working (except for references to "Extending optparse",
Greg Ward <gward@python.net>
parents: 33604
diff changeset
1364 \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
1365
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1366 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
1367 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
1368 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
1369 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
1370 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
1371 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
1372 \begin{itemize}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1373 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1374 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
1375
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1376 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1377 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
1378 processing and discard the \code{"-{}-"}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1379
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1380 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1381 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
1382 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
1383
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1384 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1385
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1386 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
1387 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
1388 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
1389 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
1390 this sort of thing directly).
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1391
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1392 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
1393 arguments:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1394 \begin{verbatim}
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1395 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
1396 assert value is None
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1397 done = 0
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1398 value = []
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1399 rargs = parser.rargs
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1400 while rargs:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1401 arg = rargs[0]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1402
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1403 # 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
1404 # 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
1405 # 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
1406 # this.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1407 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
1408 (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
1409 break
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1410 else:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1411 value.append(arg)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1412 del rargs[0]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1413
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1414 setattr(parser.values, option.dest, value)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1415
33604
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken.
Greg Ward <gward@python.net>
parents: 33454
diff changeset
1416 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1417 parser.add_option("-c", "--callback",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1418 action="callback", callback=varargs)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1419 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1420
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1421 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
1422 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
1423 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
1424 \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
1425 % $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
1426