Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/liboptparse.tex @ 32527:0da660e05e69 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
"#if WITH_THREAD" is incorrect; must be #ifdef instead; WITH_THREAD isn't always set to an integer value when it's defined.
author Tim Peters <tim.peters@gmail.com>
date Wed, 07 Jul 2004 20:42:07 +0000
parents 374697478b5a
children 2b10e2b5e81e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1 \section{\module{optparse} ---
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
2 Powerful parser for command line options.}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
3
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
4 \declaremodule{standard}{optparse}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
5 \moduleauthor{Greg Ward}{gward@python.net}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
6 \sectionauthor{Johannes Gijsbers}{jlgijsbers@users.sf.net}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
7 \sectionauthor{Greg Ward}{gward@python.net}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
8
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
9 \modulesynopsis{Powerful, flexible, extensible, easy-to-use command-line
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
10 parsing library.}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
11
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
12 \versionadded{2.3}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
13
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
14 The \module{optparse} module is a powerful, flexible, extensible,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
15 easy-to-use command-line parsing library for Python. Using
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
16 \module{optparse}, you can add intelligent, sophisticated handling of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
17 command-line options to your scripts with very little overhead.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
18
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
19 Here's an example of using \module{optparse} to add some command-line
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
20 options to a simple script:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
21
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
22 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
23 from optparse import OptionParser
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
24
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
25 parser = OptionParser()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
26 parser.add_option("-f", "--file", dest="filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
27 help="write report to FILE", metavar="FILE")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
28 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
29 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
30 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
31
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
32 options, args = parser.parse_args()
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
33 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
34
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
35 With these few lines of code, users of your script can now do the
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
36 ``usual thing'' on the command-line:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
37
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
38 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
39 $ <yourscript> -f outfile --quiet
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
40 $ <yourscript> -qfoutfile
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
41 $ <yourscript> --file=outfile -q
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
42 $ <yourscript> --quiet --file outfile
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
43 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
44
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
45 (All of these result in \code{options.filename == "outfile"} and
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
46 \code{options.verbose == False}, just as you might expect.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
47
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
48 Even niftier, users can run one of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
49 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
50 $ <yourscript> -h
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
51 $ <yourscript> --help
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
52 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
53 and \module{optparse} will print out a brief summary of your script's
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
54 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
55
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
56 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
57 usage: <yourscript> [options]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
58
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
59 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
60 -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
61 -fFILE, --file=FILE write report to FILE
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
62 -q, --quiet don't print status messages to stdout
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
63 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
64
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
65 That's just a taste of the flexibility \module{optparse} gives you in
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
66 parsing your command-line.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
67
28965
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
68 \subsection{Philosophy\label{optparse-philosophy}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
69
28965
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
70 The purpose of \module{optparse} is to make it very easy to provide the
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
71 most standard, obvious, straightforward, and user-friendly user
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
72 interface for \UNIX{} command-line programs. The \module{optparse}
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
73 philosophy is heavily influenced by the \UNIX{} and GNU toolkits, and
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
74 this section is meant to explain that philosophy.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
75
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
76 \subsubsection{Terminology\label{optparse-terminology}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
77
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
78 First, we need to establish some terminology.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
79
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
80 \begin{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
81 \term{argument}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
82 a chunk of text that a user enters on the command-line, and that the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
83 shell passes to \cfunction{execl()} or \cfunction{execv()}. In
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
84 Python, arguments are elements of
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
85 \code{sys.argv[1:]}. (\code{sys.argv[0]} is the name of the program
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
86 being executed; in the context of parsing arguments, it's not very
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
87 important.) \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
88
28965
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
89 It is occasionally desirable to use an argument list other than
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
90 \code{sys.argv[1:]}, so you should read ``argument'' as ``an element of
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
91 \code{sys.argv[1:]}, or of some other list provided as a substitute for
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
92 \code{sys.argv[1:]}''.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
93
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
94 \term{option}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
95 an argument used to supply extra information to guide or customize
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
96 the execution of a program. There are many different syntaxes for
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
97 options; the traditional \UNIX{} syntax is \programopt{-} followed by a
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
98 single letter, e.g. \programopt{-x} or \programopt{-F}. Also,
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
99 traditional \UNIX{} syntax allows multiple options to be merged into a
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
100 single argument, e.g. \programopt{-x -F} is equivalent to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
101 \programopt{-xF}. The GNU project introduced \longprogramopt{}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
102 followed by a series of hyphen-separated words,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
103 e.g. \longprogramopt{file} or \longprogramopt{dry-run}. These are
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
104 the only two option syntaxes provided by \module{optparse}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
105
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
106 Some other option syntaxes that the world has seen include:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
107
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
108 \begin{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
109 \item a hyphen followed by a few letters, e.g. \programopt{-pf} (this is
28961
ac29015ff6a8 Fix various markup errors: use \longprogramopt{} more, and use it
Greg Ward <gward@python.net>
parents: 28675
diff changeset
110 \emph{not} the same as multiple options merged into a single
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
111 argument.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
112 \item a hyphen followed by a whole word, e.g. \programopt{-file} (this is
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
113 technically equivalent to the previous syntax, but they aren't
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
114 usually seen in the same program.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
115 \item a plus sign followed by a single letter, or a few letters,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
116 or a word, e.g. \programopt{+f}, \programopt{+rgb}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
117 \item a slash followed by a letter, or a few letters, or a word, e.g.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
118 \programopt{/f}, \programopt{/file}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
119 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
120
28965
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
121 \module{optparse} does not support these option syntaxes, and it never
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
122 will. (If you really want to use one of those option syntaxes, you'll
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
123 have to subclass \class{OptionParser} and override all the difficult
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
124 bits. But please don't! \module{optparse} does things the traditional
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
125 \UNIX/GNU way deliberately; the first three are non-standard anywhere,
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
126 and the last one makes sense only if you're exclusively targeting
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
127 MS-DOS/Windows and/or VMS.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
128
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
129 \term{option argument}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
130 an argument that follows an option, is closely associated with that
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
131 option, and is consumed from the argument list when the option is.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
132 Often, option arguments may also be included in the same argument as
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
133 the option, e.g. :
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
134
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
135 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
136 ["-f", "foo"]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
137 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
138
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
139 may be equivalent to:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
140
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
141 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
142 ["-ffoo"]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
143 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
144
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
145 (\module{optparse} supports this syntax.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
146
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
147 Some options never take an argument. Some options always take an
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
148 argument. Lots of people want an ``optional option arguments'' feature,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
149 meaning that some options will take an argument if they see it, and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
150 won't if they don't. This is somewhat controversial, because it makes
28965
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
151 parsing ambiguous: if \programopt{-a} and \programopt{-b} are both
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
152 options, and \programopt{-a} takes an optional argument, how do we
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
153 interpret \programopt{-ab}? \module{optparse} does not support optional
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
154 option arguments.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
155
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
156 \term{positional argument}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
157 something leftover in the argument list after options have been
28965
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
158 parsed, i.e., after options and their arguments have been parsed and
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
159 removed from the argument list.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
160
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
161 \term{required option}
28965
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
162 an option that must be supplied on the command-line. The phrase
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
163 ``required option'' is an oxymoron; the presence of ``required options''
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
164 in a program is usually a sign of careless user interface design.
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
165 \module{optparse} doesn't prevent you from implementing required
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
166 options, but doesn't give you much help with it either. See ``Extending
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
167 Examples'' (section~\ref{optparse-extending-examples}) for two ways to
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
168 implement required options with \module{optparse}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
169
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
170 \end{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
171
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
172 For example, consider this hypothetical command-line:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
173
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
174 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
175 prog -v --report /tmp/report.txt foo bar
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
176 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
177
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
178 \programopt{-v} and \longprogramopt{report} are both options. Assuming
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
179 the \longprogramopt{report} option takes one argument,
28965
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
180 \code{/tmp/report.txt} is an option argument. \code{foo} and \code{bar}
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
181 are positional arguments.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
182
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
183 \subsubsection{What are options for?\label{optparse-options}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
184
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
185 Options are used to provide extra information to tune or customize the
28965
4ba763bc5a56 Rename "The Tao of Option Parsing" section to "Philosophy".
Greg Ward <gward@python.net>
parents: 28964
diff changeset
186 execution of a program. In case it wasn't clear, options should be
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
187 \emph{optional}. A program should be able to run just fine with no
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
188 options whatsoever. (Pick a random program from the \UNIX{} or GNU
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
189 toolsets. Can it run without any options at all and still make sense?
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
190 The only exceptions I can think of are \program{find}, \program{tar},
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
191 and \program{dd}---all of which are mutant oddballs that have been
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
192 rightly criticized for their non-standard syntax and confusing
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
193 interfaces.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
194
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
195 Lots of people want their programs to have ``required options''.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
196 Think about it. If it's required, then it's \emph{not optional}! If
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
197 there is a piece of information that your program absolutely requires
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
198 in order to run successfully, that's what positional arguments are
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
199 for. (However, if you insist on adding ``required options'' to your
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
200 programs, look in ``Extending Examples''
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
201 (section~\ref{optparse-extending-examples}) for two ways of
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
202 implementing them with \module{optparse}.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
203
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
204 Consider the humble \program{cp} utility, for copying files. It
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
205 doesn't make much sense to try to copy files without supplying a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
206 destination and at least one source. Hence, \program{cp} fails if you
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
207 run it with no arguments. However, it has a flexible, useful syntax
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
208 that does not rely on options at all:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
209
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
210 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
211 $ cp SOURCE DEST
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
212 $ cp SOURCE ... DEST-DIR
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
213 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
214
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
215 You can get pretty far with just that. Most \program{cp}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
216 implementations provide a bunch of options to tweak exactly how the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
217 files are copied: you can preserve mode and modification time, avoid
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
218 following symlinks, ask before clobbering existing files, etc. But
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
219 none of this distracts from the core mission of \program{cp}, which is
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
220 to copy one file to another, or N files to another directory.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
221
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
222 \subsubsection{What are positional arguments for? \label{optparse-positional-arguments}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
223
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
224 In case it wasn't clear from the above example: positional arguments
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
225 are for those pieces of information that your program absolutely,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
226 positively requires to run.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
227
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
228 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
229 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
230 order to run successfully, it doesn't much matter \emph{how} you get that
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
231 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
232 before they successfully run the program. This applies whether the user
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
233 interface is a command-line, a configuration file, a GUI, or whatever:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
234 if you make that many demands on your users, most of them will just give
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
235 up.
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 In short, try to minimize the amount of information that users are
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
238 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
239 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
240 flexible. That's what options are for. Again, it doesn't matter if
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
241 they are entries in a config file, checkboxes in the ``Preferences''
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
242 dialog of a GUI, or command-line options---the more options you
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
243 implement, the more flexible your program is, and the more complicated
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
244 its implementation becomes. It's quite easy to overwhelm users (and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
245 yourself!) with too much flexibility, so be careful there.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
246
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
247 \subsection{Basic Usage\label{optparse-basic-usage}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
248
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
249 While \module{optparse} is quite flexible and powerful, you don't have
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
250 to jump through hoops or read reams of documentation to get it working
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
251 in basic cases. This document aims to demonstrate some simple usage
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
252 patterns that will get you started using \module{optparse} in your
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
253 scripts.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
254
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
255 To parse a command line with \module{optparse}, you must create an
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
256 \class{OptionParser} instance and populate it. Obviously, you'll have
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
257 to import the \class{OptionParser} classes in any script that uses
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
258 \module{optparse}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
259
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
260 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
261 from optparse import OptionParser
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
262 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
263
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
264 Early on in the main program, create a parser:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
265
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
266 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
267 parser = OptionParser()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
268 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
269
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
270 Then you can start populating the parser with options. Each option is
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
271 really a set of synonymous option strings; most commonly, you'll have
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
272 one short option string and one long option string ---
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
273 e.g. \programopt{-f} and \longprogramopt{file}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
274
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
275 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
276 parser.add_option("-f", "--file", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
277 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
278
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
279 The interesting stuff, of course, is what comes after the option
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
280 strings. For now, we'll only cover four of the things you can put
29055
6dc82dcf5589 Make this format again.
Fred Drake <fdrake@acm.org>
parents: 28966
diff changeset
281 there: \emph{action}, \emph{type}, \emph{dest} (destination), and
6dc82dcf5589 Make this format again.
Fred Drake <fdrake@acm.org>
parents: 28966
diff changeset
282 \emph{help}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
283
29055
6dc82dcf5589 Make this format again.
Fred Drake <fdrake@acm.org>
parents: 28966
diff changeset
284 \subsubsection{The \emph{store} action%
6dc82dcf5589 Make this format again.
Fred Drake <fdrake@acm.org>
parents: 28966
diff changeset
285 \label{optparse-store-action}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
286
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
287 The action tells \module{optparse} what to do when it sees one of the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
288 option strings for this option on the command-line. For example, the
29055
6dc82dcf5589 Make this format again.
Fred Drake <fdrake@acm.org>
parents: 28966
diff changeset
289 action \emph{store} means: take the next argument (or the remainder of
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
290 the current argument), ensure that it is of the correct type, and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
291 store it to your chosen destination.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
292
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
293 For example, let's fill in the ``...'' of that last option:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
294
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
295 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
296 parser.add_option("-f", "--file",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
297 action="store", type="string", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
298 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
299
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
300 Now let's make up a fake command-line and ask \module{optparse} to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
301 parse it:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
302
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
303 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
304 args = ["-f", "foo.txt"]
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
305 options, args = parser.parse_args(args)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
306 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
307
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
308 (Note that if you don't pass an argument list to
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
309 \function{parse_args()}, it automatically uses \code{sys.argv[1:]}.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
310
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
311 When \module{optparse} sees the \programopt{-f}, it consumes the next
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
312 argument---\code{foo.txt}---and stores it in the \member{filename}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
313 attribute of a special object. That object is the first return value
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
314 from \function{parse_args()}, so:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
315
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
316 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
317 print options.filename
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
318 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
319
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
320 will print \code{foo.txt}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
321
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
322 Other option types supported by \module{optparse} are \code{int} and
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
323 \code{float}. 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
324
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
325 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
326 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
327 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
328
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
329 This example doesn't provide a long option, which is perfectly
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
330 acceptable. It also doesn't specify the action---it defaults to
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
331 ``store''.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
332
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
333 Let's parse another fake command-line. This time, we'll jam the option
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
334 argument right up against the option, since \programopt{-n42} (one
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
335 argument) is equivalent to \programopt{-n 42} (two arguments).
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
336
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
337 \begin{verbatim}
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
338 options, args = parser.parse_args(["-n42"])
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
339 print options.num
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
340 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
341
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
342 This prints \code{42}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
343
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
344 Trying out the ``float'' type is left as an exercise for the reader.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
345
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
346 If you don't specify a type, \module{optparse} assumes ``string''.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
347 Combined with the fact that the default action is ``store'', that
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
348 means our first example can be a lot shorter:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
349
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
350 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
351 parser.add_option("-f", "--file", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
352 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
353
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
354 If you don't supply a destination, \module{optparse} figures out a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
355 sensible default from the option strings: if the first long option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
356 string is \longprogramopt{foo-bar}, then the default destination is
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
357 \member{foo_bar}. If there are no long option strings,
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
358 \module{optparse} looks at the first short option: the default
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
359 destination for \programopt{-f} is \member{f}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
360
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
361 Adding types is fairly easy; please refer to
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
362 section~\ref{optparse-adding-types}, ``Adding new types.''
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
363
29055
6dc82dcf5589 Make this format again.
Fred Drake <fdrake@acm.org>
parents: 28966
diff changeset
364 \subsubsection{Other \emph{store_*} actions%
6dc82dcf5589 Make this format again.
Fred Drake <fdrake@acm.org>
parents: 28966
diff changeset
365 \label{optparse-other-store-actions}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
366
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
367 Flag options---set a variable to true or false when a particular
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
368 option is seen---are quite common. \module{optparse} supports them
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
369 with two separate actions, ``store_true'' and ``store_false''. For
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
370 example, you might have a \var{verbose} flag that is turned on with
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
371 \programopt{-v} and off with \programopt{-q}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
372
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
373 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
374 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
375 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
376 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
377
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
378 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
379 perfectly OK. (It just means you have to be a bit careful when setting
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
380 default values---see below.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
381
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
382 When \module{optparse} sees \programopt{-v} on the command line, it sets
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
383 \code{options.verbose} to \code{True}; when it sees \programopt{-q}, it
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
384 sets \code{options.verbose} to \code{False}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
385
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
386 \subsubsection{Setting default values\label{optparse-setting-default-values}}
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 All of the above examples involve setting some variable (the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
389 ``destination'') when certain command-line options are seen. What
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
390 happens if those options are never seen? Since we didn't supply any
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
391 defaults, they are all set to \code{None}. Sometimes, this is just fine (which
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
392 is why it's the default), but sometimes, you want more control. To
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
393 address that need, \module{optparse} lets you supply a default value for
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
394 each 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
395
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
396 First, consider the verbose/quiet example. If we want
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
397 \module{optparse} to set \member{verbose} to \code{True} unless
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
398 \programopt{-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
399
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
400 \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
401 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
402 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
403 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
404
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
405 Oddly enough, this is exactly equivalent:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
406
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
407 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
408 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
409 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
410 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
411
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
412 Those are equivalent because you're supplying a default value for the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
413 option's \emph{destination}, and these two options happen to have the same
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
414 destination (the \member{verbose} variable).
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 Consider this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
417
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
418 \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
419 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
420 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
421 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
422
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
423 Again, the default value for \member{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
424 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
425 counts.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
426
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
427 \subsubsection{Generating help\label{optparse-generating-help}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
428
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
429 The last feature that you will use in every script is
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
430 \module{optparse}'s ability to generate help messages. All you have
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
431 to do is supply a \var{help} argument when you add an option. Let's
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
432 create a new parser and populate it with user-friendly (documented)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
433 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
434
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
435 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
436 usage = "usage: %prog [options] arg1 arg2"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
437 parser = OptionParser(usage=usage)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
438 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
439 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
440 help="make lots of noise [default]")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
441 parser.add_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
442 action="store_false", dest="verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
443 help="be vewwy quiet (I'm hunting wabbits)")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
444 parser.add_option("-f", "--file", dest="filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
445 metavar="FILE", help="write output to FILE"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
446 parser.add_option("-m", "--mode",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
447 default="intermediate",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
448 help="interaction mode: one of 'novice', "
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
449 "'intermediate' [default], 'expert'")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
450 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
451
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
452 If \module{optparse} encounters either \programopt{-h} or
28961
ac29015ff6a8 Fix various markup errors: use \longprogramopt{} more, and use it
Greg Ward <gward@python.net>
parents: 28675
diff changeset
453 \longprogramopt{help} on the command-line, or if you just call
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
454 \method{parser.print_help()}, it prints the following to stdout:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
455
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
456 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
457 usage: <yourscript> [options] arg1 arg2
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
458
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
459 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
460 -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
461 -v, --verbose make lots of noise [default]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
462 -q, --quiet be vewwy quiet (I'm hunting wabbits)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
463 -fFILE, --file=FILE write output to FILE
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
464 -mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
465 [default], 'expert'
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
466 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
467
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
468 There's a lot going on here to help \module{optparse} generate the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
469 best possible help message:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
470
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
471 \begin{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
472 \item the script defines its own usage message:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
473
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
474 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
475 usage = "usage: %prog [options] arg1 arg2"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
476 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
477
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
478 \module{optparse} expands \samp{\%prog} in the usage string to the name of the
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
479 current script, i.e. \code{os.path.basename(sys.argv[0])}. The
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
480 expanded string is then printed before the detailed option help.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
481
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
482 If you don't supply a usage string, \module{optparse} uses a bland but
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
483 sensible default: \code{"usage: \%prog [options]"}, which is fine if your
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
484 script doesn't take any positional arguments.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
485
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
486 \item every option defines a help string, and doesn't worry about
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
487 line-wrapping---\module{optparse} takes care of wrapping lines and
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
488 making the help output look good.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
489
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
490 \item options that take a value indicate this fact in their
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
491 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
492
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
493 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
494 -mMODE, --mode=MODE
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
495 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
496
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
497 Here, ``MODE'' is called the meta-variable: it stands for the argument
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
498 that the user is expected to supply to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
499 \programopt{-m}/\longprogramopt{mode}. By default, \module{optparse}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
500 converts the destination variable name to uppercase and uses that for
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
501 the meta-variable. Sometimes, that's not what you want---for
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
502 example, the \var{filename} option explicitly sets
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
503 \code{metavar="FILE"}, resulting in this automatically-generated
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
504 option description:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
505
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
506 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
507 -fFILE, --file=FILE
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
508 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
509
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
510 This is important for more than just saving space, though: the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
511 manually written help text uses the meta-variable ``FILE'', to clue
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
512 the user in that there's a connection between the formal syntax
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
513 ``-fFILE'' and the informal semantic description ``write output to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
514 FILE''. This is a simple but effective way to make your help text a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
515 lot clearer and more useful for end users.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
516 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
517
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
518 When dealing with many options, it is convenient to group these
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
519 options for better help output. An \class{OptionParser} can contain
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
520 several option groups, each of which can contain several options.
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
521
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
522 Continuing with the parser defined above, adding an
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
523 \class{OptionGroup} to a parser is easy:
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
524
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
525 \begin{verbatim}
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
526 group = OptionGroup(parser, "Dangerous Options",
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
527 "Caution: use these options at your own risk. "
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
528 "It is believed that some of them bite.")
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
529 group.add_option("-g", action="store_true", help="Group option.")
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
530 parser.add_option_group(group)
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
531 \end{verbatim}
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
532
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
533 This would result in the following help output:
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
534
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
535 \begin{verbatim}
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
536 usage: [options] arg1 arg2
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
537
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
538 options:
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
539 -h, --help show this help message and exit
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
540 -v, --verbose make lots of noise [default]
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
541 -q, --quiet be vewwy quiet (I'm hunting wabbits)
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
542 -fFILE, --file=FILE write output to FILE
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
543 -mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
544 [default], 'expert'
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
545
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
546 Dangerous Options:
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
547 Caution: use of these options is at your own risk. It is believed that
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
548 some of them bite.
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
549 -g Group option.
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
550 \end{verbatim}
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
551
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
552
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
553 \subsubsection{Print a version number\label{optparse-print-version}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
554
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
555 Similar to the brief usage string, \module{optparse} can also print a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
556 version string for your program. You have to supply the string, as
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
557 the \var{version} argument to \class{OptionParser}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
558
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
559 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
560 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
561 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
562
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
563 \var{version} can contain anything you like; \code{\%prog} is expanded
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
564 in \var{version} just as with \var{usage}. When you supply it,
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
565 \module{optparse} automatically adds a \longprogramopt{version} option
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
566 to your parser. If it encounters this option on the command line, it
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
567 expands your \var{version} string (by replacing \code{\%prog}), prints
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
568 it to stdout, and exits.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
569
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
570 For example, if your script is called /usr/bin/foo, a user might do:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
571
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
572 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
573 $ /usr/bin/foo --version
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
574 foo 1.0
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
575 \end{verbatim} % $ (avoid confusing emacs)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
576
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
577 \subsubsection{Error-handling\label{optparse-error-handling}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
578
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
579 The one thing you need to know for basic usage is how
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
580 \module{optparse} behaves when it encounters an error on the
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
581 command-line---e.g. \programopt{-n 4x} where \programopt{-n} is an
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
582 integer-valued option. In this case, \module{optparse} prints your
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
583 usage message to stderr, followed by a useful and human-readable error
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
584 message. Then it terminates (calls \function{sys.exit()}) with a
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
585 non-zero exit status.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
586
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
587 If you don't like this, subclass \class{OptionParser} and override the
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
588 \method{error()} method. See section~\ref{optparse-extending},
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
589 ``Extending \module{optparse}.''
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
590
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
591 \subsubsection{Putting it all together\label{optparse-basic-summary}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
592
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
593 Here's what \module{optparse}-based scripts typically look like:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
594
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
595 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
596 from optparse import OptionParser
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
597 [...]
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
598 def main():
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
599 usage = "usage: \%prog [-f] [-v] [-q] firstarg secondarg"
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
600 parser = OptionParser(usage)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
601 parser.add_option("-f", "--file", type="string", dest="filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
602 help="read data from FILENAME")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
603 parser.add_option("-v", "--verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
604 action="store_true", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
605 parser.add_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
606 action="store_false", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
607
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
608 options, args = parser.parse_args()
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
609 if len(args) != 1:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
610 parser.error("incorrect number of arguments")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
611
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
612 if options.verbose:
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
613 print "reading \%s..." \% options.filename
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
614 [... go to work ...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
615
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
616 if __name__ == "__main__":
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
617 main()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
618 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
619
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
620 \subsection{Advanced Usage\label{optparse-advanced-usage}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
621
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
622 \subsubsection{Creating and populating the
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
623 parser\label{optparse-creating-the-parser}}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
624
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
625 There are several ways to populate the parser with options. One way
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
626 is to pass a list of \class{Options} to the \class{OptionParser}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
627 constructor:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
628
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
629 \begin{verbatim}
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
630 from optparse import OptionParser, make_option
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
631 [...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
632 parser = OptionParser(option_list=[
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
633 make_option("-f", "--filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
634 action="store", type="string", dest="filename"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
635 make_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
636 action="store_false", dest="verbose")])
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
637 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
638
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
639 (\function{make_option()} is a factory function for generating
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
640 \class{Option} objects.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
641
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
642 For long option lists, it may be more convenient/readable to create the
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
643 list separately:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
644
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
645 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
646 option_list = [make_option("-f", "--filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
647 action="store", type="string", dest="filename"),
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
648 [... more options ...]
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
649 make_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")]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
651 parser = OptionParser(option_list=option_list)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
652 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
653
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
654 Or, you can use the \method{add_option()} method of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
655 \class{OptionParser} to add options one-at-a-time:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
656
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
657 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
658 parser = OptionParser()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
659 parser.add_option("-f", "--filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
660 action="store", type="string", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
661 parser.add_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
662 action="store_false", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
663 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
664
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
665 This method makes it easier to track down exceptions raised by the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
666 \class{Option} constructor, which are common because of the complicated
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
667 interdependencies among the various keyword arguments. (If you get it
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
668 wrong, \module{optparse} raises \exception{OptionError}.)
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
669
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
670 \method{add_option()} can be called in one of two ways:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
671
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
672 \begin{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
673 \item pass it an \class{Option} instance (as returned by \function{make_option()})
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
674 \item pass it any combination of positional and keyword arguments that
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
675 are acceptable to \function{make_option()} (i.e., to the \class{Option}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
676 constructor), and it will create the \class{Option} instance for you
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
677 (shown above).
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
678 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
679
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
680 \subsubsection{Defining options\label{optparse-defining-options}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
681
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
682 Each \class{Option} instance represents a set of synonymous
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
683 command-line options, i.e. options that have the same meaning and
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
684 effect, but different spellings. You can specify any number of short
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
685 or long option strings, but you must specify at least one option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
686 string.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
687
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
688 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
689
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
690 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
691 make_option("-f", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
692 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
693
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
694 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
695
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
696 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
697 make_option("--foo", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
698 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
699
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
700 The ``...'' represents a set of keyword arguments that define attributes
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
701 of the \class{Option} object. The rules governing which keyword args
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
702 you must supply for a given \class{Option} are fairly complicated, but
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
703 you always have to supply \emph{some}. If you get it wrong,
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
704 \module{optparse} raises an \exception{OptionError} exception explaining
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
705 your mistake.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
706
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
707 The most important attribute of an option is its action, i.e. what to do
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
708 when we encounter this option on the command-line. The possible actions
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
709 are:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
710
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
711 \begin{tableii}{l|l}{code}{Action}{Meaning}
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
712 \lineii{store}{store this option's argument (default)}
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
713 \lineii{store_const}{store a constant value}
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
714 \lineii{store_true}{store a true value}
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
715 \lineii{store_false}{store a false value}
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
716 \lineii{append}{append this option's argument to a list}
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
717 \lineii{count}{increment a counter by one}
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
718 \lineii{callback}{call a specified function}
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
719 \lineii{help}{print a usage message including all options and the
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
720 documentation for them}
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
721 \end{tableii}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
722
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
723 (If you don't supply an action, the default is ``store''. For this
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
724 action, you may also supply \var{type} and \var{dest} keywords; see
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
725 below.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
726
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
727 As you can see, most actions involve storing or updating a value
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
728 somewhere. \module{optparse} always creates a particular object (an
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
729 instance of the \class{Values} class) specifically for this
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
730 purpose. Option arguments (and various other values) are stored as
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
731 attributes of this object, according to the \var{dest} (destination)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
732 argument to \function{make_option()}/\method{add_option()}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
733
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
734 For example, when you call:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
735
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
736 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
737 parser.parse_args()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
738 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
739
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
740 one of the first things \module{optparse} does is create a
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
741 \code{values} object:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
742
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
743 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
744 values = Values()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
745 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
746
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
747 If one of the options in this parser is defined with:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
748
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
749 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
750 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
751 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
752
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
753 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
754
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
755 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
756 -ffoo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
757 -f foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
758 --file=foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
759 --file foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
760 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
761
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
762 then \module{optparse}, on seeing the \programopt{-f} or
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
763 \longprogramopt{file} option, will do the equivalent of this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
764
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
765 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
766 values.filename = "foo"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
767 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
768
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
769 Clearly, the \var{type} and \var{dest} arguments are almost
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
770 as important as \var{action}. \var{action} is the only attribute that
28961
ac29015ff6a8 Fix various markup errors: use \longprogramopt{} more, and use it
Greg Ward <gward@python.net>
parents: 28675
diff changeset
771 is meaningful for \emph{all} options, though, so it is the most
ac29015ff6a8 Fix various markup errors: use \longprogramopt{} more, and use it
Greg Ward <gward@python.net>
parents: 28675
diff changeset
772 important.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
773
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
774 \subsubsection{Option actions\label{optparse-option-actions}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
775
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
776 The various option actions all have slightly different requirements
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
777 and effects. Except for the ``help'' action, you must supply at least
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
778 one other keyword argument when creating the \class{Option}; the exact
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
779 requirements for each action are listed here.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
780
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
781 \begin{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
782 \term{store} [relevant: \var{type}, \var{dest}, \var{nargs}, \var{choices}]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
783
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
784 The option must be followed by an argument, which is converted to a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
785 value according to \var{type} and stored in \var{dest}. If
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
786 \code{nargs > 1}, multiple arguments will be consumed from the command
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
787 line; all will be converted according to \var{type} and stored to
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
788 \var{dest} as a tuple. See section~\ref{optparse-option-types},
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
789 ``Option types,'' below.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
790
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
791 If \var{choices} (a sequence of strings) is supplied, the type
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
792 defaults to ``choice''.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
793
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
794 If \var{type} is not supplied, it defaults to ``string''.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
795
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
796 If \var{dest} is not supplied, \module{optparse} derives a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
797 destination from the first long option strings (e.g.,
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
798 \longprogramopt{foo-bar} becomes \member{foo_bar}). If there are no long
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
799 option strings, \module{optparse} derives a destination from the first
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
800 short option string (e.g., \programopt{-f} becomes \member{f}).
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
801
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
802 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
803
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
804 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
805 make_option("-f")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
806 make_option("-p", type="float", nargs=3, dest="point")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
807 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
808
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
809 Given the following command line:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
810
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
811 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
812 -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
813 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
814
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
815 \module{optparse} will set:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
816
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
817 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
818 values.f = "bar.txt"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
819 values.point = (1.0, -3.5, 4.0)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
820 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
821
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
822 (Actually, \member{values.f} will be set twice, but only the second
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
823 time is visible in the end.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
824
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
825 \term{store_const} [required: \var{const}, \var{dest}]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
826
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
827 The \var{const} value supplied to the \class{Option} constructor is
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
828 stored in \var{dest}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
829
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
830 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
831
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
832 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
833 make_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
834 action="store_const", const=0, dest="verbose"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
835 make_option("-v", "--verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
836 action="store_const", const=1, dest="verbose"),
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
837 make_option("--noisy",
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
838 action="store_const", const=2, dest="verbose"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
839 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
840
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
841 If \longprogramopt{noisy} is seen, \module{optparse} will set:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
842
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
843 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
844 values.verbose = 2
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
845 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
846
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
847 \term{store_true} [required: \var{dest}]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
848
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
849 A special case of ``store_const'' that stores \code{True} to \var{dest}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
850
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
851 \term{store_false} [required: \var{dest}]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
852
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
853 Like ``store_true'', but stores \code{False}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
854
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
855 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
856
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
857 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
858 make_option(None, "--clobber", action="store_true", dest="clobber")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
859 make_option(None, "--no-clobber", action="store_false", dest="clobber")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
860 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
861
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
862 \term{append} [relevant: \var{type}, \var{dest}, \var{nargs}, \var{choices}]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
863
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
864 The option must be followed by an argument, which is appended to the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
865 list in \var{dest}. If no default value for \var{dest} is supplied
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
866 (i.e. the default is \code{None}), an empty list is automatically created when
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
867 \module{optparse} first encounters this option on the command-line.
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
868 If \code{nargs > 1}, multiple arguments are consumed, and a tuple of
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
869 length \var{nargs} is appended to \var{dest}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
870
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
871 The defaults for \var{type} and \var{dest} are the same as for the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
872 ``store'' action.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
873
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
874 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
875
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
876 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
877 make_option("-t", "--tracks", action="append", type="int")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
878 \end{verbatim}
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 If \programopt{-t3} is seen on the command-line, \module{optparse} does the equivalent of:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
881
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
882 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
883 values.tracks = []
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
884 values.tracks.append(int("3"))
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
885 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
886
28961
ac29015ff6a8 Fix various markup errors: use \longprogramopt{} more, and use it
Greg Ward <gward@python.net>
parents: 28675
diff changeset
887 If, a little later on, \longprogramopt{tracks=4} is seen, it does:
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 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
890 values.tracks.append(int("4"))
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
891 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
892
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
893 See ``Error handling'' (section~\ref{optparse-error-handling}) for
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
894 information on how \module{optparse} deals with something like
28961
ac29015ff6a8 Fix various markup errors: use \longprogramopt{} more, and use it
Greg Ward <gward@python.net>
parents: 28675
diff changeset
895 \longprogramopt{tracks=x}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
896
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
897 \term{count} [required: \var{dest}]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
898
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
899 Increment the integer stored at \var{dest}. \var{dest} is set to zero
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
900 before being incremented the first time (unless you supply a default
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
901 value).
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
902
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
903 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
904
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
905 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
906 make_option("-v", action="count", dest="verbosity")
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
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
909 The first time \programopt{-v} is seen on the command line,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
910 \module{optparse} does the equivalent of:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
911
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
912 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
913 values.verbosity = 0
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
914 values.verbosity += 1
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
915 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
916
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
917 Every subsequent occurrence of \programopt{-v} results in:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
918
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
919 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
920 values.verbosity += 1
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
921 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
922
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
923 \term{callback} [required: \var{callback};
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
924 relevant: \var{type}, \var{nargs}, \var{callback_args},
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
925 \var{callback_kwargs}]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
926
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
927 Call the function specified by \var{callback}. The signature of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
928 this function should be:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
929
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
930 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
931 func(option : Option,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
932 opt : string,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
933 value : any,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
934 parser : OptionParser,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
935 *args, **kwargs)
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
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
938 Callback options are covered in detail in
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
939 section~\ref{optparse-callback-options}, ``Callback Options.''
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
940
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
941 \term{help} [required: none]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
942
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
943 Prints a complete help message for all the options in the current
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
944 option parser. The help message is constructed from the \var{usage}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
945 string passed to \class{OptionParser}'s constructor and the \var{help}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
946 string passed to every option.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
947
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
948 If no \var{help} string is supplied for an option, it will still be
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
949 listed in the help message. To omit an option entirely, use the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
950 special value \constant{optparse.SUPPRESS_HELP}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
951
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
952 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
953
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
954 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
955 from optparse import Option, OptionParser, SUPPRESS_HELP
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
956
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
957 usage = "usage: %prog [options]"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
958 parser = OptionParser(usage, option_list=[
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
959 make_option("-h", "--help", action="help"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
960 make_option("-v", action="store_true", dest="verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
961 help="Be moderately verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
962 make_option("--file", dest="filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
963 help="Input file to read data from"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
964 make_option("--secret", help=SUPPRESS_HELP)
29062
c019aa827f86 Fixed spacing and unbalanced brackets or parenthesis.
Raymond Hettinger <python@rcn.com>
parents: 29055
diff changeset
965 ])
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
966 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
967
28961
ac29015ff6a8 Fix various markup errors: use \longprogramopt{} more, and use it
Greg Ward <gward@python.net>
parents: 28675
diff changeset
968 If \module{optparse} sees either \programopt{-h} or
ac29015ff6a8 Fix various markup errors: use \longprogramopt{} more, and use it
Greg Ward <gward@python.net>
parents: 28675
diff changeset
969 \longprogramopt{help} on the command line, it will print something
ac29015ff6a8 Fix various markup errors: use \longprogramopt{} more, and use it
Greg Ward <gward@python.net>
parents: 28675
diff changeset
970 like the following help message to stdout:
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
971
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
972 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
973 usage: <yourscript> [options]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
974
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
975 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
976 -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
977 -v Be moderately verbose
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
978 --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
979 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
980
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
981 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
982 with \code{sys.exit(0)}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
983
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
984 \term{version} [required: none]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
985
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
986 Prints the version number supplied to the \class{OptionParser} to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
987 stdout and exits. The version number is actually formatted and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
988 printed by the \method{print_version()} method of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
989 \class{OptionParser}. Generally only relevant if the \var{version}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
990 argument is supplied to the \class{OptionParser} constructor.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
991 \end{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
992
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
993 \subsubsection{Option types\label{optparse-option-types}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
994
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
995 \module{optparse} supports six option types out of the box: \dfn{string},
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
996 \dfn{int}, \dfn{long}, \dfn{choice}, \dfn{float} and \dfn{complex}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
997 (Of these, string, int, float, and choice are the most commonly used
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
998 ---long and complex are there mainly for completeness.) It's easy to
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
999 add new option types by subclassing the \class{Option} class; see
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1000 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
1001
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1002 Arguments to string options are not checked or converted in any way:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1003 the text on the command line is stored in the destination (or passed
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1004 to the callback) as-is.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1005
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1006 Integer arguments are passed to \function{int()} to convert them to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1007 Python integers. If \function{int()} fails, so will
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1008 \module{optparse}, although with a more useful error message.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1009 Internally, \module{optparse} raises \exception{OptionValueError} in
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1010 \function{optparse.check_builtin()}; at a higher level (in
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
1011 \class{OptionParser}), \module{optparse} catches this exception and
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
1012 terminates your program with a useful error message.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1013
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1014 Likewise, float arguments are passed to \function{float()} for
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1015 conversion, long arguments to \function{long()}, and complex arguments
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1016 to \function{complex()}. Apart from that, they are handled
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1017 identically to integer arguments.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1018
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1019 Choice options are a subtype of string options. A master list or
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1020 tuple of choices (strings) must be passed to the option constructor
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1021 (\function{make_option()} or \method{OptionParser.add_option()}) as
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
1022 the \var{choices} keyword argument. Choice option arguments are
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1023 compared against this master list in
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1024 \function{optparse.check_choice()}, and \exception{OptionValueError}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1025 is raised if an unknown string is given.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1026
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1027 \subsubsection{Querying and manipulating your option parser\label{optparse-querying-and-manipulating}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1028
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1029 Sometimes, it's useful to poke around your option parser and see what's
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1030 there. \class{OptionParser} provides a couple of methods to help you out:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1031
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1032 \begin{methoddesc}{has_option}{opt_str}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1033 Given an option string such as \programopt{-q} or
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1034 \longprogramopt{verbose}, returns true if the \class{OptionParser}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1035 has an option with that option string.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1036 \end{methoddesc}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1037
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1038 \begin{methoddesc}{get_option}{opt_str}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1039 Returns the \class{Option} instance that implements the option
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
1040 string you supplied, or \code{None} if no options implement it.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1041 \end{methoddesc}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1042
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1043 \begin{methoddesc}{remove_option}{opt_str}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1044 If the \class{OptionParser} has an option corresponding to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1045 \var{opt_str}, that option is removed. If that option provided
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1046 any other option strings, all of those option strings become
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1047 invalid.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1048
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1049 If \var{opt_str} does not occur in any option belonging to this
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1050 \class{OptionParser}, raises \exception{ValueError}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1051 \end{methoddesc}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1052
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1053 \subsubsection{Conflicts between options\label{optparse-conflicts}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1054
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1055 If you're not careful, it's easy to define conflicting options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1056
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1057 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1058 parser.add_option("-n", "--dry-run", ...)
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1059 ...
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1060 parser.add_option("-n", "--noisy", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1061 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1062
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1063 (This is even easier to do if you've defined your own
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1064 \class{OptionParser} subclass with some standard options.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1065
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1066 On the assumption that this is usually a mistake, \module{optparse}
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1067 raises an exception (\exception{OptionConflictError}) by default when
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1068 this happens. Since this is an easily-fixed programming error, you
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1069 shouldn't try to catch this exception---fix your mistake and get on
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1070 with life.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1071
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1072 Sometimes, you want newer options to deliberately replace the option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1073 strings used by older options. You can achieve this by calling:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1074
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1075 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1076 parser.set_conflict_handler("resolve")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1077 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1078
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1079 which instructs \module{optparse} to resolve option conflicts
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1080 intelligently.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1081
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1082 Here's how it works: every time you add an option, \module{optparse}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1083 checks for conflicts with previously-added options. If it finds any,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1084 it invokes the conflict-handling mechanism you specify either to the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1085 \class{OptionParser} constructor:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1086
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1087 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1088 parser = OptionParser(..., conflict_handler="resolve")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1089 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1090
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1091 or via the \method{set_conflict_handler()} method.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1092
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
1093 The default conflict-handling mechanism is \code{error}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1094
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1095 Here's an example: first, define an \class{OptionParser} set to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1096 resolve conflicts intelligently:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1097
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")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1100 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1101
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1102 Now add all of our options:
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 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1105 parser.add_option("-n", "--dry-run", ..., help="original dry-run option")
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1106 ...
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1107 parser.add_option("-n", "--noisy", ..., help="be noisy")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1108 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1109
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1110 At this point, \module{optparse} detects that a previously-added option is already
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1111 using the \programopt{-n} option string. Since \code{conflict_handler
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1112 == "resolve"}, it resolves the situation by removing \programopt{-n}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1113 from the earlier option's list of option strings. Now,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1114 \longprogramopt{dry-run} is the only way for the user to activate that
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1115 option. If the user asks for help, the help message will reflect
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1116 that, e.g.:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1117
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1118 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1119 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1120 --dry-run original dry-run option
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1121 ...
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1122 -n, --noisy be noisy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1123 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1124
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1125 Note that it's possible to whittle away the option strings for a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1126 previously-added option until there are none left, and the user has no
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1127 way of invoking that option from the command-line. In that case,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1128 \module{optparse} removes that option completely, so it doesn't show
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1129 up in help text or anywhere else. E.g. if we carry on with our
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1130 existing \class{OptionParser}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1131
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1132 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1133 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
1134 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1135
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1136 At this point, the first \programopt{-n}/\longprogramopt{dry-run}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1137 option is no longer accessible, so \module{optparse} removes it. If
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1138 the user asks for help, they'll get something like this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1139
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1140 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1141 options:
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1142 ...
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1143 -n, --noisy be noisy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1144 --dry-run new dry-run option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1145 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1146
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1147 \subsection{Callback Options\label{optparse-callback-options}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1148
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1149 If \module{optparse}'s built-in actions and types just don't fit the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1150 bill for you, but it's not worth extending \module{optparse} to define
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1151 your own actions or types, you'll probably need to define a callback
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1152 option. Defining callback options is quite easy; the tricky part is
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1153 writing a good callback (the function that is called when
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1154 \module{optparse} encounters the option on the command line).
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1155
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1156 \subsubsection{Defining a callback option\label{optparse-defining-callback-option}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1157
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1158 As always, you can define a callback option either by directly
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1159 instantiating the \class{Option} class, or by using the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1160 \method{add_option()} method of your \class{OptionParser} object. The
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1161 only option attribute you must specify is \var{callback}, the function
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1162 to call:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1163
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1164 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1165 parser.add_option("-c", callback=my_callback)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1166 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1167
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1168 Note that you supply a function object here---so you must have
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1169 already defined a function \function{my_callback()} when you define
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1170 the callback option. In this simple case, \module{optparse} knows
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1171 nothing about the arguments the \programopt{-c} option expects to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1172 take. Usually, this means that the option doesn't take any arguments
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1173 -- the mere presence of \programopt{-c} on the command-line is all it
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1174 needs to know. In some circumstances, though, you might want your
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1175 callback to consume an arbitrary number of command-line arguments.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1176 This is where writing callbacks gets tricky; it's covered later in
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1177 this document.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1178
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1179 There are several other option attributes that you can supply when you
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1180 define an option attribute:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1181
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1182 \begin{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1183 \term{type}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1184 has its usual meaning: as with the ``store'' or ``append'' actions, it
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1185 instructs \module{optparse} to consume one argument that must be
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1186 convertible to \var{type}. Rather than storing the value(s) anywhere,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1187 though, \module{optparse} converts it to \var{type} and passes it to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1188 your callback function.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1189
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1190 \term{nargs}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1191 also has its usual meaning: if it is supplied and \samp{nargs > 1},
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1192 \module{optparse} will consume \var{nargs} arguments, each of which
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1193 must be convertible to \var{type}. It then passes a tuple of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1194 converted values to your callback.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1195
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1196 \term{callback_args}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1197 a tuple of extra positional arguments to pass to the callback.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1198
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1199 \term{callback_kwargs}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1200 a dictionary of extra keyword arguments to pass to the callback.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1201 \end{definitions}
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 \subsubsection{How callbacks are called\label{optparse-callbacks-called}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1204
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1205 All callbacks are called as follows:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1206
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1207 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1208 func(option, opt, value, parser, *args, **kwargs)
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
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1212
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1213 \begin{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1214 \term{option}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1215 is the \class{Option} instance that's calling the callback.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1216
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1217 \term{opt}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1218 is the option string seen on the command-line that's triggering the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1219 callback. (If an abbreviated long option was used, \var{opt} will be
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
1220 the full, canonical option string---for example, if the user puts
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1221 \longprogramopt{foo} on the command-line as an abbreviation for
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1222 \longprogramopt{foobar}, then \var{opt} will be
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1223 \longprogramopt{foobar}.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1224
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1225 \term{value}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1226 is the argument to this option seen on the command-line.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1227 \module{optparse} will only expect an argument if \var{type} is
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1228 set; the type of \var{value} will be the type implied by the
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1229 option's type (see~\ref{optparse-option-types}, ``Option types''). If
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
1230 \var{type} for this option is \code{None} (no argument expected), then
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
1231 \var{value} will be \code{None}. If \samp{nargs > 1}, \var{value} will
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1232 be a tuple of values of the appropriate type.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1233
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1234 \term{parser}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1235 is the \class{OptionParser} instance driving the whole thing, mainly
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1236 useful because you can access some other interesting data through it,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1237 as instance attributes:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1238
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1239 \begin{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1240 \term{parser.rargs}
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
1241 the current remaining argument list, i.e. with \var{opt} (and
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1242 \var{value}, if any) removed, and only the arguments following
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1243 them still there. Feel free to modify \member{parser.rargs},
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1244 e.g. by consuming more arguments.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1245
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1246 \term{parser.largs}
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
1247 the current set of leftover arguments, i.e. arguments that have been
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1248 processed but have not been consumed as options (or arguments to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1249 options). Feel free to modify \member{parser.largs} e.g. by adding
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1250 more arguments to it.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1251
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1252 \term{parser.values}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1253 the object where option values are by default stored. This is useful
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1254 because it lets callbacks use the same mechanism as the rest of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1255 \module{optparse} for storing option values; you don't need to mess
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1256 around with globals or closures. You can also access the value(s) of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1257 any options already encountered on the command-line.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1258 \end{definitions}
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 \term{args}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1261 is a tuple of arbitrary positional arguments supplied via the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1262 \var{callback}_args option attribute.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1263
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1264 \term{kwargs}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1265 is a dictionary of arbitrary keyword arguments supplied via
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1266 \var{callback_kwargs}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1267 \end{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1268
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1269 Since \var{args} and \var{kwargs} are optional (they are only passed
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1270 if you supply \var{callback_args} and/or \var{callback_kwargs} when
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1271 you define your callback option), the minimal callback function is:
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 \begin{verbatim}
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
1274 def my_callback(option, opt, value, parser):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1275 pass
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1276 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1277
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1278 \subsubsection{Error handling\label{optparse-callback-error-handling}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1279
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1280 The callback function should raise \exception{OptionValueError} if
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1281 there are any problems with the option or its
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1282 argument(s). \module{optparse} catches this and terminates the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1283 program, printing the error message you supply to stderr. Your
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1284 message should be clear, concise, accurate, and mention the option at
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1285 fault. Otherwise, the user will have a hard time figuring out what he
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1286 did wrong.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1287
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1288 \subsubsection{Examples\label{optparse-callback-examples}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1289
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1290 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
1291 simply records that the option was seen:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1292
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1293 \begin{verbatim}
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
1294 def record_foo_seen(option, opt, value, parser):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1295 parser.saw_foo = 1
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1296
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1297 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
1298 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1299
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1300 Of course, you could do that with the ``store_true'' action. Here's a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1301 slightly more interesting example: record the fact that
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1302 \programopt{-a} is seen, but blow up if it comes after \programopt{-b}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1303 in the command-line.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1304
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1305 \begin{verbatim}
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
1306 def check_order(option, opt, value, parser):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1307 if parser.values.b:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1308 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
1309 parser.values.a = 1
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1310 ...
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1311 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
1312 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
1313 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1314
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1315 If you want to reuse this callback for several similar options (set a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1316 flag, but blow up if \programopt{-b} has already been seen), it needs
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1317 a bit of work: the error message and the flag that it sets must be
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1318 generalized.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1319
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1320 \begin{verbatim}
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
1321 def check_order(option, opt, value, parser):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1322 if parser.values.b:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1323 raise OptionValueError("can't use %s after -b" % opt)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1324 setattr(parser.values, option.dest, 1)
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1325 ...
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1326 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
1327 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
1328 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
1329 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1330
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1331 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
1332 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
1333 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
1334 you have to do is this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1335
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1336 \begin{verbatim}
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
1337 def check_moon(option, opt, value, parser):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1338 if is_full_moon():
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1339 raise OptionValueError("%s option invalid when moon full" % opt)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1340 setattr(parser.values, option.dest, 1)
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1341 ...
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1342 parser.add_option("--foo",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1343 action="callback", callback=check_moon, dest="foo")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1344 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1345
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1346 (The definition of \code{is_full_moon()} 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
1347 reader.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1348
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1349 \strong{Fixed arguments}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1350
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1351 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
1352 that take a fixed number of arguments. Specifying that a callback
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1353 option takes arguments is similar to defining a ``store'' or
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1354 ``append'' option: if you define \var{type}, then the option takes one
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1355 argument that must be convertible to that type; if you further define
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1356 \var{nargs}, then the option takes that many arguments.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1357
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1358 Here's an example that just emulates the standard ``store'' action:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1359
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1360 \begin{verbatim}
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
1361 def store_value(option, opt, value, parser):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1362 setattr(parser.values, option.dest, value)
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1363 ...
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1364 parser.add_option("--foo",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1365 action="callback", callback=store_value,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1366 type="int", nargs=3, dest="foo")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1367 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1368
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1369 Note that \module{optparse} takes care of consuming 3 arguments and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1370 converting them to integers for you; all you have to do is store them.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1371 (Or whatever: obviously you don't need a callback for this example.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1372 Use your imagination!)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1373
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1374 \strong{Variable arguments}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1375
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1376 Things get hairy when you want an option to take a variable number of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1377 arguments. For this case, you have to write a callback;
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1378 \module{optparse} doesn't provide any built-in capabilities for it.
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1379 You have to deal with the full-blown syntax for conventional \UNIX{}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1380 command-line parsing. (Previously, \module{optparse} took care of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1381 this for you, but I got it wrong. It was fixed at the cost of making
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1382 this kind of callback more complex.) In particular, callbacks have to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1383 worry about bare \longprogramopt{} and \programopt{-} arguments; the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1384 convention is:
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 \begin{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1387 \item bare \longprogramopt{}, if not the argument to some option,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1388 causes command-line processing to halt and the \longprogramopt{}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1389 itself is lost.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1390
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1391 \item bare \programopt{-} similarly causes command-line processing to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1392 halt, but the \programopt{-} itself is kept.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1393
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1394 \item either \longprogramopt{} or \programopt{-} can be option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1395 arguments.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1396 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1397
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1398 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
1399 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
1400 implementation you choose will be based on which trade-offs you're
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1401 willing to make for your application (which is why \module{optparse}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1402 doesn't support this sort of thing directly).
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1403
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1404 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
1405 arguments:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1406
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1407 \begin{verbatim}
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
1408 def varargs(option, opt, value, parser):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1409 assert value is None
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1410 done = 0
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1411 value = []
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1412 rargs = parser.rargs
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1413 while rargs:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1414 arg = rargs[0]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1415
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1416 # 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
1417 # 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
1418 # 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
1419 # this.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1420 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
1421 (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
1422 break
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1423 else:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1424 value.append(arg)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1425 del rargs[0]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1426
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1427 setattr(parser.values, option.dest, value)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1428
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1429 ...
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1430 parser.add_option("-c", "--callback",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1431 action="callback", callback=varargs)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1432 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1433
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1434 The main weakness with this particular implementation is that negative
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1435 numbers in the arguments following \programopt{-c} will be interpreted
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1436 as further options, rather than as arguments to \programopt{-c}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1437 Fixing this is left as an exercise for the reader.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1438
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1439 \subsection{Extending \module{optparse}\label{optparse-extending}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1440
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1441 Since the two major controlling factors in how \module{optparse}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1442 interprets command-line options are the action and type of each
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1443 option, the most likely direction of extension is to add new actions
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1444 and new types.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1445
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1446 Also, the examples section includes several demonstrations of
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
1447 extending \module{optparse} in different ways: e.g. a case-insensitive
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1448 option parser, or two kinds of option parsers that implement
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1449 ``required options''.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1450
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1451 \subsubsection{Adding new types\label{optparse-adding-types}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1452
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1453 To add new types, you need to define your own subclass of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1454 \module{optparse}'s \class{Option} class. This class has a couple of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1455 attributes that define \module{optparse}'s types: \member{TYPES} and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1456 \member{TYPE_CHECKER}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1457
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1458 \member{TYPES} is a tuple of type names; in your subclass, simply
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1459 define a new tuple \member{TYPES} that builds on the standard one.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1460
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1461 \member{TYPE_CHECKER} is a dictionary mapping type names to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1462 type-checking functions. A type-checking function has the following
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1463 signature:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1464
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1465 \begin{verbatim}
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
1466 def check_foo(option : Option, opt : string, value : string)
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
1467 -> foo
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1468 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1469
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1470 You can name it whatever you like, and make it return any type you
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1471 like. The value returned by a type-checking function will wind up in
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1472 the \class{OptionValues} instance returned by
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1473 \method{OptionParser.parse_args()}, or be passed to callbacks as the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1474 \var{value} parameter.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1475
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1476 Your type-checking function should raise \exception{OptionValueError}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1477 if it encounters any problems. \exception{OptionValueError} takes a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1478 single string argument, which is passed as-is to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1479 \class{OptionParser}'s \method{error()} method, which in turn prepends
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1480 the program name and the string ``error:'' and prints everything to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1481 stderr before terminating the process.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1482
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1483 Here's a silly example that demonstrates adding a ``complex'' option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1484 type to parse Python-style complex numbers on the command line. (This
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1485 is even sillier than it used to be, because \module{optparse} 1.3 adds
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1486 built-in support for complex numbers [purely for completeness], but
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1487 never mind.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1488
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1489 First, the necessary imports:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1490
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1491 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1492 from copy import copy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1493 from optparse import Option, OptionValueError
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1494 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1495
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1496 You need to define your type-checker first, since it's referred to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1497 later (in the \member{TYPE_CHECKER} class attribute of your
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1498 \class{Option} subclass):
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1499
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1500 \begin{verbatim}
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
1501 def check_complex(option, opt, value):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1502 try:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1503 return complex(value)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1504 except ValueError:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1505 raise OptionValueError(
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1506 "option %s: invalid complex value: %r" % (opt, value))
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1507 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1508
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1509 Finally, the \class{Option} subclass:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1510
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1511 \begin{verbatim}
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
1512 class MyOption(Option):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1513 TYPES = Option.TYPES + ("complex",)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1514 TYPE_CHECKER = copy(Option.TYPE_CHECKER)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1515 TYPE_CHECKER["complex"] = check_complex
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1516 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1517
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1518 (If we didn't make a \function{copy()} of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1519 \member{Option.TYPE_CHECKER}, we would end up modifying the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1520 \member{TYPE_CHECKER} attribute of \module{optparse}'s Option class.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1521 This being Python, nothing stops you from doing that except good
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1522 manners and common sense.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1523
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1524 That's it! Now you can write a script that uses the new option type
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1525 just like any other \module{optparse}-based script, except you have to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1526 instruct your \class{OptionParser} to use \class{MyOption} instead of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1527 \class{Option}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1528
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1529 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1530 parser = OptionParser(option_class=MyOption)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1531 parser.add_option("-c", action="store", type="complex", dest="c")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1532 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1533
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1534 Alternately, you can build your own option list and pass it to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1535 \class{OptionParser}; if you don't use \method{add_option()} in the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1536 above way, you don't need to tell \class{OptionParser} which option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1537 class to use:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1538
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1539 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1540 option_list = [MyOption("-c", action="store", type="complex", dest="c")]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1541 parser = OptionParser(option_list=option_list)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1542 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1543
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1544 \subsubsection{Adding new actions\label{optparse-adding-actions}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1545
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1546 Adding new actions is a bit trickier, because you have to understand
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1547 that \module{optparse} has a couple of classifications for actions:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1548
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1549 \begin{definitions}
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1550 \term{``store'' actions}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1551 actions that result in \module{optparse} storing a value to an attribute
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1552 of the OptionValues instance; these options require a \var{dest}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1553 attribute to be supplied to the Option constructor
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1554 \term{``typed'' actions}
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1555 actions that take a value from the command line and expect it to be
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1556 of a certain type; or rather, a string that can be converted to a
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1557 certain type. These options require a \var{type} attribute to the
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1558 Option constructor.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1559 \end{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1560
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1561 Some default ``store'' actions are \var{store}, \var{store_const},
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1562 \var{append}, and \var{count}. The default ``typed'' actions are
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1563 \var{store}, \var{append}, and \var{callback}.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1564
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1565 When you add an action, you need to decide if it's a ``store'' action,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1566 a ``typed'', neither, or both. Three class attributes of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1567 \class{Option} (or your \class{Option} subclass) control this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1568
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1569 \begin{memberdesc}{ACTIONS}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1570 All actions must be listed as strings in ACTIONS.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1571 \end{memberdesc}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1572 \begin{memberdesc}{STORE_ACTIONS}
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1573 ``store'' actions are additionally listed here.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1574 \end{memberdesc}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1575 \begin{memberdesc}{TYPED_ACTIONS}
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1576 ``typed'' actions are additionally listed here.
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1577 \end{memberdesc}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1578
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1579 In order to actually implement your new action, you must override
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1580 \class{Option}'s \method{take_action()} method and add a case that
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1581 recognizes your action.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1582
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1583 For example, let's add an ``extend'' action. This is similar to the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1584 standard ``append'' action, but instead of taking a single value from
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1585 the command-line and appending it to an existing list, ``extend'' will
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1586 take multiple values in a single comma-delimited string, and extend an
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1587 existing list with them. That is, if \longprogramopt{names} is an
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1588 ``extend'' option of type string, the command line:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1589
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1590 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1591 --names=foo,bar --names blah --names ding,dong
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1592 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1593
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1594 would result in a list:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1595
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1596 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1597 ["foo", "bar", "blah", "ding", "dong"]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1598 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1599
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1600 Again we define a subclass of \class{Option}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1601
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1602 \begin{verbatim}
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
1603 class MyOption(Option):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1604
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1605 ACTIONS = Option.ACTIONS + ("extend",)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1606 STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1607 TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1608
31434
374697478b5a fix whitespace style (inconsistent with the rest of the docs)
Fred Drake <fdrake@acm.org>
parents: 31426
diff changeset
1609 def take_action(self, action, dest, opt, value, values, parser):
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1610 if action == "extend":
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1611 lvalue = value.split(",")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1612 values.ensure_value(dest, []).extend(lvalue)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1613 else:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1614 Option.take_action(
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1615 self, action, dest, opt, value, values, parser)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1616 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1617
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1618 Features of note:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1619
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1620 \begin{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1621 \item ``extend'' both expects a value on the command-line and stores that
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1622 value somewhere, so it goes in both \member{STORE_ACTIONS} and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1623 \member{TYPED_ACTIONS}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1624
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1625 \item \method{MyOption.take_action()} implements just this one new
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1626 action, and passes control back to \method{Option.take_action()} for
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1627 the standard \module{optparse} actions.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1628
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1629 \item \var{values} is an instance of the \class{Values} class, which
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1630 provides the very useful \method{ensure_value()}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1631 method. \method{ensure_value()} is essentially \function{getattr()}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1632 with a safety valve; it is called as:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1633
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1634 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1635 values.ensure_value(attr, value)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1636 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1637 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1638
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1639 If the \member{attr} attribute of \var{values} doesn't exist or is
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
1640 \code{None}, then \method{ensure_value()} first sets it to \var{value}, and
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1641 then returns \var{value}. This is very handy for actions like
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1642 ``extend'', ``append'', and ``count'', all of which accumulate data in
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1643 a variable and expect that variable to be of a certain type (a list
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1644 for the first two, an integer for the latter). Using
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1645 \method{ensure_value()} means that scripts using your action don't
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1646 have to worry about setting a default value for the option
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
1647 destinations in question; they can just leave the default as \code{None} and
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1648 \method{ensure_value()} will take care of getting it right when it's
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1649 needed.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1650
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1651 \subsubsection{Other reasons to extend \module{optparse}\label{optparse-extending-other-reasons}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1652
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1653 Adding new types and new actions are the big, obvious reasons why you
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1654 might want to extend \module{optparse}. I can think of at least two
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1655 other areas to play with.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1656
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1657 First, the simple one: \class{OptionParser} tries to be helpful by
28966
350ee31aab0c Scattered wording and typographical improvements (up to but not
Greg Ward <gward@python.net>
parents: 28965
diff changeset
1658 calling \function{sys.exit()} when appropriate, i.e. when there's an
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1659 error on the command-line or when the user requests help. In the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1660 former case, the traditional course of letting the script crash with a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1661 traceback is unacceptable; it will make users think there's a bug in
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1662 your script when they make a command-line error. In the latter case,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1663 there's generally not much point in carrying on after printing a help
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1664 message.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1665
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1666 If this behaviour bothers you, it shouldn't be too hard to ``fix'' it.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1667 You'll have to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1668
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1669 \begin{enumerate}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1670 \item subclass OptionParser and override the error() method
28962
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1671 \item subclass Option and override the take_action() method---you'll
189fdae8f492 Use TeX quotes -- ``foo'' -- as appropriate.
Greg Ward <gward@python.net>
parents: 28961
diff changeset
1672 need to provide your own handling of the ``help'' action that
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1673 doesn't call sys.exit()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1674 \end{enumerate}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1675
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1676 The second, much more complex, possibility is to override the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1677 command-line syntax implemented by \module{optparse}. In this case,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1678 you'd leave the whole machinery of option actions and types alone, but
29902
9f60c3ee985a Lots of markup cleanups to avoid warnings from the GNU info generation;
Fred Drake <fdrake@acm.org>
parents: 29062
diff changeset
1679 rewrite the code that processes \code{sys.argv}. You'll need to
27116
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1680 subclass \class{OptionParser} in any case; depending on how radical a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1681 rewrite you want, you'll probably need to override one or all of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1682 \method{parse_args()}, \method{_process_long_opt()}, and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1683 \method{_process_short_opts()}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1684
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1685 Both of these are left as an exercise for the reader. I have not
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1686 tried to implement either myself, since I'm quite happy with
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1687 \module{optparse}'s default behaviour (naturally).
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1688
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1689 Happy hacking, and don't forget: Use the Source, Luke.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1690
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1691 \subsubsection{Examples\label{optparse-extending-examples}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1692
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1693 Here are a few examples of extending the \module{optparse} module.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1694
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1695 First, let's change the option-parsing to be case-insensitive:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1696
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1697 \verbatiminput{caseless.py}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1698
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1699 And two ways of implementing ``required options'' with
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1700 \module{optparse}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1701
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1702 Version 1: Add a method to \class{OptionParser} which applications
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1703 must call after parsing arguments:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1704
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1705 \verbatiminput{required_1.py}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1706
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1707 Version 2: Extend \class{Option} and add a \member{required}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1708 attribute; extend \class{OptionParser} to ensure that required options
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1709 are present after parsing:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1710
28675
1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup
Fred Drake <fdrake@acm.org>
parents: 27116
diff changeset
1711 \verbatiminput{required_2.py}
31425
46224690a365 add references between getopt and optparse docs
Skip Montanaro <skip@pobox.com>
parents: 29902
diff changeset
1712
46224690a365 add references between getopt and optparse docs
Skip Montanaro <skip@pobox.com>
parents: 29902
diff changeset
1713 \begin{seealso}
31426
f2fd4e5ddf19 fix markup
Fred Drake <fdrake@acm.org>
parents: 31425
diff changeset
1714 \seemodule{getopt}{More traditional \UNIX-style command line option parsing.}
31425
46224690a365 add references between getopt and optparse docs
Skip Montanaro <skip@pobox.com>
parents: 29902
diff changeset
1715 \end{seealso}