cpython-lru_cache-weakref: Doc/lib/liboptparse.tex annotate

annotate Doc/lib/liboptparse.tex @ 34161:ca2ca1aeb080 2.4

Check in missing png version of pyfav.gif.

author	Johannes Gijsbers <jlg@dds.nl>
date	Mon, 13 Dec 2004 13:11:42 +0000
parents	d25615ef5d8f
children	3ec54c5f7081

rev	line source
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1 \section{\module{optparse} --- More powerful command line option parser}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	2 \declaremodule{standard}{optparse}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	3 \moduleauthor{Greg Ward}{gward@python.net}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	4 \modulesynopsis{More convenient, flexible, and powerful command-line parsing library.}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	5 \versionadded{2.3}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	6 \sectionauthor{Greg Ward}{gward@python.net}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	7 % An intro blurb used only when generating LaTeX docs for the Python
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	8 % manual (based on README.txt).
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	9
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	10 \code{optparse} is a more convenient, flexible, and powerful library for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	11 parsing command-line options than \code{getopt}. \code{optparse} uses a more
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	12 declarative style of command-line parsing: you create an instance of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	13 \class{OptionParser}, populate it with options, and parse the command line.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	14 \code{optparse} allows users to specify options in the conventional GNU/POSIX
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	15 syntax, and additionally generates usage and help messages for you.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	16
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	17 Here's an example of using \code{optparse} in a simple script:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	18 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	19 from optparse import OptionParser
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	20 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	21 parser = OptionParser()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	22 parser.add_option("-f", "--file", dest="filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	23 help="write report to FILE", metavar="FILE")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	24 parser.add_option("-q", "--quiet",
28964 2e9956d01de3 Use True/False instead of 1/0 when talking about store_true/store_false. Greg Ward <gward@python.net> parents: 28962 diff changeset	25 action="store_false", dest="verbose", default=True,
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	26 help="don't print status messages to stdout")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	27
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	28 (options, args) = parser.parse_args()
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	29 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	30
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	31 With these few lines of code, users of your script can now do the
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	32 ``usual thing'' on the command-line, for example:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	33 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	34 <yourscript> --file=outfile -q
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	35 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	36
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	37 As it parses the command line, \code{optparse} sets attributes of the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	38 \var{options} object returned by \method{parse{\_}args()} based on user-supplied
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	39 command-line values. When \method{parse{\_}args()} returns from parsing this
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	40 command line, \var{options.filename} will be \code{"outfile"} and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	41 \code{options.verbose} will be \code{False}. \code{optparse} supports both long
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	42 and short options, allows short options to be merged together, and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	43 allows options to be associated with their arguments in a variety of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	44 ways. Thus, the following command lines are all equivalent to the above
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	45 example:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	46 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	47 <yourscript> -f outfile --quiet
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	48 <yourscript> --quiet --file outfile
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	49 <yourscript> -q -foutfile
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	50 <yourscript> -qfoutfile
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	51 \end{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	52
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	53 Additionally, users can run one of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	54 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	55 <yourscript> -h
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	56 <yourscript> --help
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	57 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	58
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	59 and \code{optparse} will print out a brief summary of your script's
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	60 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	61 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	62 usage: <yourscript> [options]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	63
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	64 options:
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	65 -h, --help show this help message and exit
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	66 -f FILE, --file=FILE write report to FILE
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	67 -q, --quiet don't print status messages to stdout
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	68 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	69
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	70 where the value of \emph{yourscript} is determined at runtime (normally
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	71 from \code{sys.argv{[}0]}).
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	72 % $Id: intro.txt 413 2004-09-28 00:59:13Z greg $
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	73
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	74
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	75 \subsection{Background\label{optparse-background}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	76
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	77 \module{optparse} was explicitly designed to encourage the creation of programs with
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	78 straightforward, conventional command-line interfaces. To that end, it
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	79 supports only the most common command-line syntax and semantics
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	80 conventionally used under \UNIX{}. If you are unfamiliar with these
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	81 conventions, read this section to acquaint yourself with them.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	82
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	83
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	84 \subsubsection{Terminology\label{optparse-terminology}}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	85 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	86 \item[argument]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	87 a string entered on the command-line, and passed by the shell to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	88 \code{execl()} or \code{execv()}. In Python, arguments are elements of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	89 \code{sys.argv{[}1:]} (\code{sys.argv{[}0]} is the name of the program being
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	90 executed). \UNIX{} shells also use the term ``word''.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	91
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	92 It is occasionally desirable to substitute an argument list other
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	93 than \code{sys.argv{[}1:]}, so you should read ``argument'' as ``an element of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	94 \code{sys.argv{[}1:]}, or of some other list provided as a substitute for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	95 \code{sys.argv{[}1:]}''.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	96 \item[option ]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	97 an argument used to supply extra information to guide or customize the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	98 execution of a program. There are many different syntaxes for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	99 options; the traditional \UNIX{} syntax is a hyphen (``-'') followed by a
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	100 single letter, e.g. \code{"-x"} or \code{"-F"}. Also, traditional \UNIX{}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	101 syntax allows multiple options to be merged into a single argument,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	102 e.g. \code{"-x -F"} is equivalent to \code{"-xF"}. The GNU project
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	103 introduced \code{"-{}-"} followed by a series of hyphen-separated words,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	104 e.g. \code{"-{}-file"} or \code{"-{}-dry-run"}. These are the only two option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	105 syntaxes provided by \module{optparse}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	106
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	107 Some other option syntaxes that the world has seen include:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	108 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	109 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	110 a hyphen followed by a few letters, e.g. \code{"-pf"} (this is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	111 \emph{not} the same as multiple options merged into a single argument)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	112
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	113 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	114 a hyphen followed by a whole word, e.g. \code{"-file"} (this is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	115 technically equivalent to the previous syntax, but they aren't
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	116 usually seen in the same program)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	117
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	118 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	119 a plus sign followed by a single letter, or a few letters,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	120 or a word, e.g. \code{"+f"}, \code{"+rgb"}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	121
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	122 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	123 a slash followed by a letter, or a few letters, or a word, e.g.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	124 \code{"/f"}, \code{"/file"}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	125
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	126 \end{itemize}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	127
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	128 These option syntaxes are not supported by \module{optparse}, and they never will
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	129 be. This is deliberate: the first three are non-standard on any
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	130 environment, and the last only makes sense if you're exclusively
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	131 targeting VMS, MS-DOS, and/or Windows.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	132 \item[option argument]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	133 an argument that follows an option, is closely associated with that
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	134 option, and is consumed from the argument list when that option is.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	135 With \module{optparse}, option arguments may either be in a separate argument
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	136 from their option:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	137 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	138 -f foo
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	139 --file foo
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	140 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	141
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	142 or included in the same argument:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	143 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	144 -ffoo
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	145 --file=foo
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	146 \end{verbatim}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	147
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	148 Typically, a given option either takes an argument or it doesn't.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	149 Lots of people want an ``optional option arguments'' feature, meaning
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	150 that some options will take an argument if they see it, and won't if
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	151 they don't. This is somewhat controversial, because it makes parsing
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	152 ambiguous: if \code{"-a"} takes an optional argument and \code{"-b"} is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	153 another option entirely, how do we interpret \code{"-ab"}? Because of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	154 this ambiguity, \module{optparse} does not support this feature.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	155 \item[positional argument]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	156 something leftover in the argument list after options have been
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	157 parsed, i.e. after options and their arguments have been parsed and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	158 removed from the argument list.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	159 \item[required option]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	160 an option that must be supplied on the command-line; note that the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	161 phrase ``required option'' is self-contradictory in English. \module{optparse}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	162 doesn't prevent you from implementing required options, but doesn't
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	163 give you much help at it either. See \code{examples/required{\_}1.py} and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	164 \code{examples/required{\_}2.py} in the \module{optparse} source distribution for two
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	165 ways to implement required options with \module{optparse}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	166 \end{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	167
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	168 For example, consider this hypothetical command-line:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	169 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	170 prog -v --report /tmp/report.txt foo bar
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	171 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	172
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	173 \code{"-v"} and \code{"-{}-report"} are both options. Assuming that
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	174 \longprogramopt{report} takes one argument, \code{"/tmp/report.txt"} is an option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	175 argument. \code{"foo"} and \code{"bar"} are positional arguments.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	176
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	177
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	178 \subsubsection{What are options for?\label{optparse-what-options-for}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	179
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	180 Options are used to provide extra information to tune or customize the
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	181 execution of a program. In case it wasn't clear, options are usually
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	182 \emph{optional}. A program should be able to run just fine with no options
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	183 whatsoever. (Pick a random program from the \UNIX{} or GNU toolsets. Can
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	184 it run without any options at all and still make sense? The main
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	185 exceptions are \code{find}, \code{tar}, and \code{dd}{---}all of which are mutant
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	186 oddballs that have been rightly criticized for their non-standard syntax
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	187 and confusing interfaces.)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	188
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	189 Lots of people want their programs to have ``required options''. Think
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	190 about it. If it's required, then it's \emph{not optional}! If there is a
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	191 piece of information that your program absolutely requires in order to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	192 run successfully, that's what positional arguments are for.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	193
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	194 As an example of good command-line interface design, consider the humble
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	195 \code{cp} utility, for copying files. It doesn't make much sense to try to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	196 copy files without supplying a destination and at least one source.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	197 Hence, \code{cp} fails if you run it with no arguments. However, it has a
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	198 flexible, useful syntax that does not require any options at all:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	199 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	200 cp SOURCE DEST
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	201 cp SOURCE ... DEST-DIR
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	202 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	203
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	204 You can get pretty far with just that. Most \code{cp} implementations
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	205 provide a bunch of options to tweak exactly how the files are copied:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	206 you can preserve mode and modification time, avoid following symlinks,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	207 ask before clobbering existing files, etc. But none of this distracts
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	208 from the core mission of \code{cp}, which is to copy either one file to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	209 another, or several files to another directory.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	210
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	211
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	212 \subsubsection{What are positional arguments for?\label{optparse-what-positional-arguments-for}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	213
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	214 Positional arguments are for those pieces of information that your
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	215 program absolutely, positively requires to run.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	216
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	217 A good user interface should have as few absolute requirements as
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	218 possible. If your program requires 17 distinct pieces of information in
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	219 order to run successfully, it doesn't much matter \emph{how} you get that
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	220 information from the user{---}most people will give up and walk away
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	221 before they successfully run the program. This applies whether the user
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	222 interface is a command-line, a configuration file, or a GUI: if you make
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	223 that many demands on your users, most of them will simply give up.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	224
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	225 In short, try to minimize the amount of information that users are
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	226 absolutely required to supply{---}use sensible defaults whenever
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	227 possible. Of course, you also want to make your programs reasonably
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	228 flexible. That's what options are for. Again, it doesn't matter if
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	229 they are entries in a config file, widgets in the ``Preferences'' dialog
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	230 of a GUI, or command-line options{---}the more options you implement, the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	231 more flexible your program is, and the more complicated its
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	232 implementation becomes. Too much flexibility has drawbacks as well, of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	233 course; too many options can overwhelm users and make your code much
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	234 harder to maintain.
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	235 % $Id: tao.txt 413 2004-09-28 00:59:13Z greg $
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	236
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	237
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	238 \subsection{Tutorial\label{optparse-tutorial}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	239
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	240 While \module{optparse} is quite flexible and powerful, it's also straightforward to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	241 use in most cases. This section covers the code patterns that are
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	242 common to any \module{optparse}-based program.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	243
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	244 First, you need to import the OptionParser class; then, early in the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	245 main program, create an OptionParser instance:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	246 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	247 from optparse import OptionParser
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	248 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	249 parser = OptionParser()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	250 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	251
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	252 Then you can start defining options. The basic syntax is:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	253 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	254 parser.add_option(opt_str, ...,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	255 attr=value, ...)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	256 \end{verbatim}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	257
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	258 Each option has one or more option strings, such as \code{"-f"} or
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	259 \code{"-{}-file"}, and several option attributes that tell \module{optparse} what to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	260 expect and what to do when it encounters that option on the command
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	261 line.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	262
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	263 Typically, each option will have one short option string and one long
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	264 option string, e.g.:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	265 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	266 parser.add_option("-f", "--file", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	267 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	268
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	269 You're free to define as many short option strings and as many long
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	270 option strings as you like (including zero), as long as there is at
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	271 least one option string overall.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	272
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	273 The option strings passed to \method{add{\_}option()} are effectively labels for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	274 the option defined by that call. For brevity, we will frequently refer
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	275 to \emph{encountering an option} on the command line; in reality, \module{optparse}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	276 encounters \emph{option strings} and looks up options from them.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	277
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	278 Once all of your options are defined, instruct \module{optparse} to parse your
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	279 program's command line:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	280 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	281 (options, args) = parser.parse_args()
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	282 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	283
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	284 (If you like, you can pass a custom argument list to \method{parse{\_}args()},
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	285 but that's rarely necessary: by default it uses \code{sys.argv{[}1:]}.)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	286
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	287 \method{parse{\_}args()} returns two values:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	288 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	289 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	290 \var{options}, an object containing values for all of your options{---}e.g. if \code{"-{}-file"} takes a single string argument, then
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	291 \var{options.file} will be the filename supplied by the user, or
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	292 \code{None} if the user did not supply that option
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	293
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	294 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	295 \var{args}, the list of positional arguments leftover after parsing
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	296 options
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	297
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	298 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	299
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	300 This tutorial section only covers the four most important option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	301 attributes: \member{action}, \member{type}, \member{dest} (destination), and \member{help}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	302 Of these, \member{action} is the most fundamental.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	303
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	304
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	305 \subsubsection{Understanding option actions\label{optparse-understanding-option-actions}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	306
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	307 Actions tell \module{optparse} what to do when it encounters an option on the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	308 command line. There is a fixed set of actions hard-coded into \module{optparse};
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	309 adding new actions is an advanced topic covered in section~\ref{optparse-extending}, Extending \module{optparse}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	310 Most actions tell \module{optparse} to store a value in some variable{---}for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	311 example, take a string from the command line and store it in an
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	312 attribute of \var{options}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	313
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	314 If you don't specify an option action, \module{optparse} defaults to \code{store}.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	315
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	316
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	317 \subsubsection{The store action\label{optparse-store-action}}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	318
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	319 The most common option action is \code{store}, which tells \module{optparse} to take
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	320 the next argument (or the remainder of the current argument), ensure
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	321 that it is of the correct type, and store it to your chosen destination.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	322
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	323 For example:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	324 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	325 parser.add_option("-f", "--file",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	326 action="store", type="string", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	327 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	328
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	329 Now let's make up a fake command line and ask \module{optparse} to parse it:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	330 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	331 args = ["-f", "foo.txt"]
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	332 (options, args) = parser.parse_args(args)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	333 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	334
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	335 When \module{optparse} sees the option string \code{"-f"}, it consumes the next
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	336 argument, \code{"foo.txt"}, and stores it in \var{options.filename}. So,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	337 after this call to \method{parse{\_}args()}, \var{options.filename} is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	338 \code{"foo.txt"}.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	339
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	340 Some other option types supported by \module{optparse} are \code{int} and \code{float}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	341 Here's an option that expects an integer argument:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	342 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	343 parser.add_option("-n", type="int", dest="num")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	344 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	345
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	346 Note that this option has no long option string, which is perfectly
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	347 acceptable. Also, there's no explicit action, since the default is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	348 \code{store}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	349
28966 350ee31aab0c Scattered wording and typographical improvements (up to but not Greg Ward <gward@python.net> parents: 28965 diff changeset	350 Let's parse another fake command-line. This time, we'll jam the option
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	351 argument right up against the option: since \code{"-n42"} (one argument) is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	352 equivalent to \code{"-n 42"} (two arguments), the code
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	353 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	354 (options, args) = parser.parse_args(["-n42"])
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	355 print options.num
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	356 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	357
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	358 will print \code{"42"}.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	359
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	360 If you don't specify a type, \module{optparse} assumes \code{string}. Combined with the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	361 fact that the default action is \code{store}, that means our first example
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	362 can be a lot shorter:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	363 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	364 parser.add_option("-f", "--file", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	365 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	366
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	367 If you don't supply a destination, \module{optparse} figures out a sensible default
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	368 from the option strings: if the first long option string is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	369 \code{"-{}-foo-bar"}, then the default destination is \code{foo{\_}bar}. If there
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	370 are no long option strings, \module{optparse} looks at the first short option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	371 string: the default destination for \code{"-f"} is \code{f}.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	372
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	373 \module{optparse} also includes built-in \code{long} and \code{complex} types. Adding
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	374 types is covered in section~\ref{optparse-extending}, Extending \module{optparse}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	375
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	376
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	377 \subsubsection{Handling boolean (flag) options\label{optparse-handling-boolean-options}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	378
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	379 Flag options{---}set a variable to true or false when a particular option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	380 is seen{---}are quite common. \module{optparse} supports them with two separate
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	381 actions, \code{store{\_}true} and \code{store{\_}false}. For example, you might have a
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	382 \var{verbose} flag that is turned on with \code{"-v"} and off with \code{"-q"}:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	383 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	384 parser.add_option("-v", action="store_true", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	385 parser.add_option("-q", action="store_false", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	386 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	387
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	388 Here we have two different options with the same destination, which is
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	389 perfectly OK. (It just means you have to be a bit careful when setting
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	390 default values{---}see below.)
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	391
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	392 When \module{optparse} encounters \code{"-v"} on the command line, it sets
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	393 \code{options.verbose} to \code{True}; when it encounters \code{"-q"},
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	394 \code{options.verbose} is set to \code{False}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	395
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	396
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	397 \subsubsection{Other actions\label{optparse-other-actions}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	398
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	399 Some other actions supported by \module{optparse} are:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	400 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	401 \item[\code{store{\_}const}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	402 store a constant value
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	403 \item[\code{append}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	404 append this option's argument to a list
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	405 \item[\code{count}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	406 increment a counter by one
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	407 \item[\code{callback}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	408 call a specified function
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	409 \end{description}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	410
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	411 These are covered in section~\ref{optparse-reference-guide}, Reference Guide and section~\ref{optparse-option-callbacks}, Option Callbacks.
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	412
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	413
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	414 \subsubsection{Default values\label{optparse-default-values}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	415
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	416 All of the above examples involve setting some variable (the
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	417 ``destination'') when certain command-line options are seen. What happens
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	418 if those options are never seen? Since we didn't supply any defaults,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	419 they are all set to \code{None}. This is usually fine, but sometimes you
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	420 want more control. \module{optparse} lets you supply a default value for each
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	421 destination, which is assigned before the command line is parsed.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	422
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	423 First, consider the verbose/quiet example. If we want \module{optparse} to set
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	424 \var{verbose} to \code{True} unless \code{"-q"} is seen, then we can do this:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	425 \begin{verbatim}
28964 2e9956d01de3 Use True/False instead of 1/0 when talking about store_true/store_false. Greg Ward <gward@python.net> parents: 28962 diff changeset	426 parser.add_option("-v", action="store_true", dest="verbose", default=True)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	427 parser.add_option("-q", action="store_false", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	428 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	429
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	430 Since default values apply to the \emph{destination} rather than to any
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	431 particular option, and these two options happen to have the same
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	432 destination, this is exactly equivalent:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	433 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	434 parser.add_option("-v", action="store_true", dest="verbose")
28964 2e9956d01de3 Use True/False instead of 1/0 when talking about store_true/store_false. Greg Ward <gward@python.net> parents: 28962 diff changeset	435 parser.add_option("-q", action="store_false", dest="verbose", default=True)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	436 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	437
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	438 Consider this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	439 \begin{verbatim}
28964 2e9956d01de3 Use True/False instead of 1/0 when talking about store_true/store_false. Greg Ward <gward@python.net> parents: 28962 diff changeset	440 parser.add_option("-v", action="store_true", dest="verbose", default=False)
2e9956d01de3 Use True/False instead of 1/0 when talking about store_true/store_false. Greg Ward <gward@python.net> parents: 28962 diff changeset	441 parser.add_option("-q", action="store_false", dest="verbose", default=True)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	442 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	443
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	444 Again, the default value for \var{verbose} will be \code{True}: the last
28966 350ee31aab0c Scattered wording and typographical improvements (up to but not Greg Ward <gward@python.net> parents: 28965 diff changeset	445 default value supplied for any particular destination is the one that
350ee31aab0c Scattered wording and typographical improvements (up to but not Greg Ward <gward@python.net> parents: 28965 diff changeset	446 counts.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	447
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	448 A clearer way to specify default values is the \method{set{\_}defaults()}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	449 method of OptionParser, which you can call at any time before calling
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	450 \method{parse{\_}args()}:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	451 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	452 parser.set_defaults(verbose=True)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	453 parser.add_option(...)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	454 (options, args) = parser.parse_args()
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	455 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	456
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	457 As before, the last value specified for a given option destination is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	458 the one that counts. For clarity, try to use one method or the other of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	459 setting default values, not both.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	460
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	461
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	462 \subsubsection{Generating help\label{optparse-generating-help}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	463
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	464 \module{optparse}'s ability to generate help and usage text automatically is useful
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	465 for creating user-friendly command-line interfaces. All you have to do
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	466 is supply a \member{help} value for each option, and optionally a short usage
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	467 message for your whole program. Here's an OptionParser populated with
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	468 user-friendly (documented) options:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	469 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	470 usage = "usage: %prog [options] arg1 arg2"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	471 parser = OptionParser(usage=usage)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	472 parser.add_option("-v", "--verbose",
28964 2e9956d01de3 Use True/False instead of 1/0 when talking about store_true/store_false. Greg Ward <gward@python.net> parents: 28962 diff changeset	473 action="store_true", dest="verbose", default=True,
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	474 help="make lots of noise [default]")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	475 parser.add_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	476 action="store_false", dest="verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	477 help="be vewwy quiet (I'm hunting wabbits)")
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	478 parser.add_option("-f", "--filename",
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	479 metavar="FILE", help="write output to FILE"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	480 parser.add_option("-m", "--mode",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	481 default="intermediate",
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	482 help="interaction mode: novice, intermediate, "
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	483 "or expert [default: %default]")
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	484 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	485
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	486 If \module{optparse} encounters either \code{"-h"} or \code{"-{}-help"} on the command-line,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	487 or if you just call \method{parser.print{\_}help()}, it prints the following to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	488 standard output:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	489 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	490 usage: <yourscript> [options] arg1 arg2
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	491
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	492 options:
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	493 -h, --help show this help message and exit
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	494 -v, --verbose make lots of noise [default]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	495 -q, --quiet be vewwy quiet (I'm hunting wabbits)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	496 -f FILE, --filename=FILE
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	497 write output to FILE
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	498 -m MODE, --mode=MODE interaction mode: novice, intermediate, or
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	499 expert [default: intermediate]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	500 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	501
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	502 (If the help output is triggered by a help option, \module{optparse} exits after
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	503 printing the help text.)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	504
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	505 There's a lot going on here to help \module{optparse} generate the best possible
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	506 help message:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	507 \begin{itemize}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	508 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	509 the script defines its own usage message:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	510 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	511 usage = "usage: %prog [options] arg1 arg2"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	512 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	513
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	514 \module{optparse} expands \code{"{\%}prog"} in the usage string to the name of the current
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	515 program, i.e. \code{os.path.basename(sys.argv{[}0])}. The expanded string
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	516 is then printed before the detailed option help.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	517
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	518 If you don't supply a usage string, \module{optparse} uses a bland but sensible
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	519 default: ``\code{usage: {\%}prog {[}options]"}, which is fine if your script
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	520 doesn't take any positional arguments.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	521
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	522 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	523 every option defines a help string, and doesn't worry about line-
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	524 wrapping{---}\module{optparse} takes care of wrapping lines and making the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	525 help output look good.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	526
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	527 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	528 options that take a value indicate this fact in their
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	529 automatically-generated help message, e.g. for the ``mode'' option:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	530 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	531 -m MODE, --mode=MODE
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	532 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	533
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	534 Here, ``MODE'' is called the meta-variable: it stands for the argument
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	535 that the user is expected to supply to \programopt{-m}/\longprogramopt{mode}. By default,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	536 \module{optparse} converts the destination variable name to uppercase and uses
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	537 that for the meta-variable. Sometimes, that's not what you want{---}for example, the \longprogramopt{filename} option explicitly sets
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	538 \code{metavar="FILE"}, resulting in this automatically-generated option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	539 description:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	540 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	541 -f FILE, --filename=FILE
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	542 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	543
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	544 This is important for more than just saving space, though: the
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	545 manually written help text uses the meta-variable ``FILE'' to clue the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	546 user in that there's a connection between the semi-formal syntax ``-f
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	547 FILE'' and the informal semantic description ``write output to FILE''.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	548 This is a simple but effective way to make your help text a lot
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	549 clearer and more useful for end users.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	550
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	551 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	552 options that have a default value can include \code{{\%}default} in
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	553 the help string{---}\module{optparse} will replace it with \function{str()} of the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	554 option's default value. If an option has no default value (or the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	555 default value is \code{None}), \code{{\%}default} expands to \code{none}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	556
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	557 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	558
28675 1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup Fred Drake <fdrake@acm.org> parents: 27116 diff changeset	559
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	560 \subsubsection{Printing a version string\label{optparse-printing-version-string}}
28675 1556a38d5278 - accepted (slightly) modified version of docs for the OptionGroup Fred Drake <fdrake@acm.org> parents: 27116 diff changeset	561
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	562 Similar to the brief usage string, \module{optparse} can also print a version string
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	563 for your program. You have to supply the string as the \code{version}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	564 argument to OptionParser:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	565 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	566 parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	567 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	568
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	569 Note that \code{"{\%}prog"} is expanded just like it is in \var{usage}. Apart
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	570 from that, \code{version} can contain anything you like. When you supply
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	571 it, \module{optparse} automatically adds a \code{"-{}-version"} option to your parser.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	572 If it encounters this option on the command line, it expands your
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	573 \code{version} string (by replacing \code{"{\%}prog"}), prints it to stdout, and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	574 exits.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	575
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	576 For example, if your script is called \code{/usr/bin/foo}:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	577 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	578 $ /usr/bin/foo --version
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	579 foo 1.0
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	580 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	581
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	582
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	583 \subsubsection{How \module{optparse} handles errors\label{optparse-how-optik-handles-errors}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	584
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	585 There are two broad classes of errors that \module{optparse} has to worry about:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	586 programmer errors and user errors. Programmer errors are usually
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	587 erroneous calls to \code{parse.add{\_}option()}, e.g. invalid option strings,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	588 unknown option attributes, missing option attributes, etc. These are
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	589 dealt with in the usual way: raise an exception (either
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	590 \code{optparse.OptionError} or \code{TypeError}) and let the program crash.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	591
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	592 Handling user errors is much more important, since they are guaranteed
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	593 to happen no matter how stable your code is. \module{optparse} can automatically
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	594 detect some user errors, such as bad option arguments (passing \code{"-n
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	595 4x"} where \programopt{-n} takes an integer argument), missing arguments
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	596 (\code{"-n"} at the end of the command line, where \programopt{-n} takes an argument
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	597 of any type). Also, you can call \code{parser.error()} to signal an
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	598 application-defined error condition:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	599 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	600 (options, args) = parser.parse_args()
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	601 [...]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	602 if options.a and options.b:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	603 parser.error("options -a and -b are mutually exclusive")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	604 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	605
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	606 In either case, \module{optparse} handles the error the same way: it prints the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	607 program's usage message and an error message to standard error and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	608 exits with error status 2.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	609
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	610 Consider the first example above, where the user passes \code{"4x"} to an
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	611 option that takes an integer:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	612 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	613 $ /usr/bin/foo -n 4x
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	614 usage: foo [options]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	615
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	616 foo: error: option -n: invalid integer value: '4x'
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	617 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	618
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	619 Or, where the user fails to pass a value at all:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	620 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	621 $ /usr/bin/foo -n
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	622 usage: foo [options]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	623
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	624 foo: error: -n option requires an argument
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	625 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	626
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	627 \module{optparse}-generated error messages take care always to mention the option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	628 involved in the error; be sure to do the same when calling
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	629 \code{parser.error()} from your application code.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	630
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	631 If \module{optparse}'s default error-handling behaviour does not suite your needs,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	632 you'll need to subclass OptionParser and override \code{exit()} and/or
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	633 \method{error()}.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	634
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	635
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	636 \subsubsection{Putting it all together\label{optparse-putting-it-all-together}}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	637
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	638 Here's what \module{optparse}-based scripts usually look like:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	639 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	640 from optparse import OptionParser
28966 350ee31aab0c Scattered wording and typographical improvements (up to but not Greg Ward <gward@python.net> parents: 28965 diff changeset	641 [...]
350ee31aab0c Scattered wording and typographical improvements (up to but not Greg Ward <gward@python.net> parents: 28965 diff changeset	642 def main():
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	643 usage = "usage: %prog [options] arg"
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	644 parser = OptionParser(usage)
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	645 parser.add_option("-f", "--file", dest="filename",
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	646 help="read data from FILENAME")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	647 parser.add_option("-v", "--verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	648 action="store_true", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	649 parser.add_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	650 action="store_false", dest="verbose")
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	651 [...]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	652 (options, args) = parser.parse_args()
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	653 if len(args) != 1:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	654 parser.error("incorrect number of arguments")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	655 if options.verbose:
33454 3daa6633f017 Patch #1025800: remove TeX quoting from verbatim section. Thanks Dima Dorfman! Johannes Gijsbers <jlg@dds.nl> parents: 32609 diff changeset	656 print "reading %s..." % options.filename
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	657 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	658
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	659 if __name__ == "__main__":
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	660 main()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	661 \end{verbatim}
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	662 % $Id: tutorial.txt 415 2004-09-30 02:26:17Z greg $
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	663
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	664
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	665 \subsection{Reference Guide\label{optparse-reference-guide}}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	666
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	667
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	668 \subsubsection{Populating the parser\label{optparse-populating-parser}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	669
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	670 There are several ways to populate the parser with options. The
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	671 preferred way is by using \code{OptionParser.add{\_}option()}, as shown in
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	672 section~\ref{optparse-tutorial}, the tutorial. \method{add{\_}option()} can be called in one of two
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	673 ways:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	674 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	675 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	676 pass it an Option instance (as returned by \function{make{\_}option()})
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	677
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	678 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	679 pass it any combination of positional and keyword arguments that are
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	680 acceptable to \function{make{\_}option()} (i.e., to the Option constructor),
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	681 and it will create the Option instance for you
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	682
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	683 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	684
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	685 The other alternative is to pass a list of pre-constructed Option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	686 instances to the OptionParser constructor, as in:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	687 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	688 option_list = [
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	689 make_option("-f", "--filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	690 action="store", type="string", dest="filename"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	691 make_option("-q", "--quiet",
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	692 action="store_false", dest="verbose"),
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	693 ]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	694 parser = OptionParser(option_list=option_list)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	695 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	696
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	697 (\function{make{\_}option()} is a factory function for creating Option instances;
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	698 currently it is an alias for the Option constructor. A future version
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	699 of \module{optparse} may split Option into several classes, and \function{make{\_}option()}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	700 will pick the right class to instantiate. Do not instantiate Option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	701 directly.)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	702
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	703
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	704 \subsubsection{Defining options\label{optparse-defining-options}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	705
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	706 Each Option instance represents a set of synonymous command-line option
33974 d25615ef5d8f SF #1063757: fix markup error (had LaTeX markup in the reST source, Greg Ward <gward@python.net> parents: 33636 diff changeset	707 strings, e.g. \programopt{-f} and \longprogramopt{file}. You can
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	708 specify any number of short or long option strings, but you must specify
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	709 at least one overall option string.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	710
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	711 The canonical way to create an Option instance is by calling
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	712 \function{make{\_}option()}, so that is what will be shown here. However, the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	713 most common and convenient way is to use \code{parser.add{\_}option()}. Note
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	714 that \function{make{\_}option()} and \code{parser.add{\_}option()} have identical call
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	715 signatures:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	716 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	717 make_option(opt_str, ..., attr=value, ...)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	718 parser.add_option(opt_str, ..., attr=value, ...)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	719 \end{verbatim}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	720
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	721 To define an option with only a short option string:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	722 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	723 make_option("-f", attr=value, ...)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	724 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	725
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	726 And to define an option with only a long option string:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	727 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	728 make_option("--foo", attr=value, ...)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	729 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	730
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	731 The \code{attr=value} keyword arguments define option attributes,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	732 i.e. attributes of the Option object. The most important option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	733 attribute is \member{action}, and it largely determines what other attributes
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	734 are relevant or required. If you pass irrelevant option attributes, or
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	735 fail to pass required ones, \module{optparse} raises an OptionError exception
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	736 explaining your mistake.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	737
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	738 An options's \emph{action} determines what \module{optparse} does when it encounters
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	739 this option on the command-line. The actions hard-coded into \module{optparse} are:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	740 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	741 \item[\code{store}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	742 store this option's argument {[}default]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	743 \item[\code{store{\_}const}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	744 store a constant value
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	745 \item[\code{store{\_}true}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	746 store a true value
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	747 \item[\code{store{\_}false}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	748 store a false value
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	749 \item[\code{append}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	750 append this option's argument to a list
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	751 \item[\code{count}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	752 increment a counter by one
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	753 \item[\code{callback}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	754 call a specified function
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	755 \item[\member{help}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	756 print a usage message including all options and the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	757 documentation for them
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	758 \end{description}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	759
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	760 (If you don't supply an action, the default is \code{store}. For this
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	761 action, you may also supply \member{type} and \member{dest} option attributes; see
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	762 below.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	763
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	764 As you can see, most actions involve storing or updating a value
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	765 somewhere. \module{optparse} always creates an instance of \code{optparse.Values}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	766 specifically for this purpose; we refer to this instance as \var{options}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	767 Option arguments (and various other values) are stored as attributes of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	768 this object, according to the \member{dest} (destination) option attribute.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	769
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	770 For example, when you call
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	771 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	772 parser.parse_args()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	773 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	774
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	775 one of the first things \module{optparse} does is create the \var{options} object:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	776 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	777 options = Values()
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	778 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	779
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	780 If one of the options in this parser is defined with
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	781 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	782 make_option("-f", "--file", action="store", type="string", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	783 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	784
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	785 and the command-line being parsed includes any of the following:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	786 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	787 -ffoo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	788 -f foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	789 --file=foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	790 --file foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	791 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	792
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	793 then \module{optparse}, on seeing the \programopt{-f} or \longprogramopt{file} option, will do the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	794 equivalent of
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	795 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	796 options.filename = "foo"
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	797 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	798
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	799 The \member{type} and \member{dest} option attributes are almost as important as
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	800 \member{action}, but \member{action} is the only one that makes sense for \emph{all}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	801 options.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	802
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	803
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	804 \subsubsection{Standard option actions\label{optparse-standard-option-actions}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	805
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	806 The various option actions all have slightly different requirements and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	807 effects. Most actions have several relevant option attributes which you
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	808 may specify to guide \module{optparse}'s behaviour; a few have required attributes,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	809 which you must specify for any option using that action.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	810 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	811 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	812 \code{store} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	813
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	814 The option must be followed by an argument, which is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	815 converted to a value according to \member{type} and stored in
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	816 \member{dest}. If \code{nargs} {\textgreater} 1, multiple arguments will be consumed
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	817 from the command line; all will be converted according to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	818 \member{type} and stored to \member{dest} as a tuple. See the ``Option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	819 types'' section below.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	820
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	821 If \code{choices} is supplied (a list or tuple of strings), the type
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	822 defaults to \code{choice}.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	823
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	824 If \member{type} is not supplied, it defaults to \code{string}.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	825
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	826 If \member{dest} is not supplied, \module{optparse} derives a destination from the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	827 first long option string (e.g., \code{"-{}-foo-bar"} implies \code{foo{\_}bar}).
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	828 If there are no long option strings, \module{optparse} derives a destination from
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	829 the first short option string (e.g., \code{"-f"} implies \code{f}).
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	830
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	831 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	832 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	833 parser.add_option("-f")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	834 parser.add_option("-p", type="float", nargs=3, dest="point")
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	835 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	836
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	837 As it parses the command line
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	838 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	839 -f foo.txt -p 1 -3.5 4 -fbar.txt
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	840 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	841
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	842 \module{optparse} will set
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	843 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	844 options.f = "foo.txt"
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	845 options.point = (1.0, -3.5, 4.0)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	846 options.f = "bar.txt"
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	847 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	848
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	849 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	850 \code{store{\_}const} {[}required: \code{const}; relevant: \member{dest}]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	851
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	852 The value \code{const} is stored in \member{dest}.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	853
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	854 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	855 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	856 parser.add_option("-q", "--quiet",
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	857 action="store_const", const=0, dest="verbose")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	858 parser.add_option("-v", "--verbose",
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	859 action="store_const", const=1, dest="verbose")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	860 parser.add_option("--noisy",
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	861 action="store_const", const=2, dest="verbose")
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	862 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	863
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	864 If \code{"-{}-noisy"} is seen, \module{optparse} will set
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	865 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	866 options.verbose = 2
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	867 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	868
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	869 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	870 \code{store{\_}true} {[}relevant: \member{dest}]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	871
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	872 A special case of \code{store{\_}const} that stores a true value
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	873 to \member{dest}.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	874
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	875 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	876 \code{store{\_}false} {[}relevant: \member{dest}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	877
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	878 Like \code{store{\_}true}, but stores a false value.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	879
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	880 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	881 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	882 parser.add_option("--clobber", action="store_true", dest="clobber")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	883 parser.add_option("--no-clobber", action="store_false", dest="clobber")
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	884 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	885
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	886 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	887 \code{append} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	888
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	889 The option must be followed by an argument, which is appended to the
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	890 list in \member{dest}. If no default value for \member{dest} is supplied, an
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	891 empty list is automatically created when \module{optparse} first encounters this
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	892 option on the command-line. If \code{nargs} {\textgreater} 1, multiple arguments are
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	893 consumed, and a tuple of length \code{nargs} is appended to \member{dest}.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	894
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	895 The defaults for \member{type} and \member{dest} are the same as for the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	896 \code{store} action.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	897
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	898 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	899 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	900 parser.add_option("-t", "--tracks", action="append", type="int")
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	901 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	902
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	903 If \code{"-t3"} is seen on the command-line, \module{optparse} does the equivalent of:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	904 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	905 options.tracks = []
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	906 options.tracks.append(int("3"))
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	907 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	908
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	909 If, a little later on, \code{"-{}-tracks=4"} is seen, it does:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	910 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	911 options.tracks.append(int("4"))
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	912 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	913
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	914 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	915 \code{count} {[}relevant: \member{dest}]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	916
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	917 Increment the integer stored at \member{dest}. If no default value is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	918 supplied, \member{dest} is set to zero before being incremented the first
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	919 time.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	920
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	921 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	922 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	923 parser.add_option("-v", action="count", dest="verbosity")
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	924 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	925
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	926 The first time \code{"-v"} is seen on the command line, \module{optparse} does the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	927 equivalent of:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	928 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	929 options.verbosity = 0
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	930 options.verbosity += 1
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	931 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	932
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	933 Every subsequent occurrence of \code{"-v"} results in
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	934 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	935 options.verbosity += 1
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	936 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	937
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	938 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	939 \code{callback} {[}required: \code{callback};
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	940 relevant: \member{type}, \code{nargs}, \code{callback{\_}args}, \code{callback{\_}kwargs}]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	941
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	942 Call the function specified by \code{callback}. The signature of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	943 this function should be
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	944 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	945 func(option : Option,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	946 opt : string,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	947 value : any,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	948 parser : OptionParser,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	949 args, *kwargs)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	950 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	951
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	952 See section~\ref{optparse-option-callbacks}, Option Callbacks for more detail.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	953
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	954 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	955 \member{help}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	956
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	957 Prints a complete help message for all the options in the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	958 current option parser. The help message is constructed from
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	959 the \var{usage} string passed to OptionParser's constructor and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	960 the \member{help} string passed to every option.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	961
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	962 If no \member{help} string is supplied for an option, it will still be
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	963 listed in the help message. To omit an option entirely, use
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	964 the special value \code{optparse.SUPPRESS{\_}HELP}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	965
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	966 \module{optparse} automatically adds a \member{help} option to all OptionParsers, so
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	967 you do not normally need to create one.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	968
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	969 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	970 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	971 from optparse import OptionParser, SUPPRESS_HELP
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	972
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	973 parser = OptionParser()
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	974 parser.add_option("-h", "--help", action="help"),
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	975 parser.add_option("-v", action="store_true", dest="verbose",
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	976 help="Be moderately verbose")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	977 parser.add_option("--file", dest="filename",
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	978 help="Input file to read data from"),
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	979 parser.add_option("--secret", help=SUPPRESS_HELP)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	980 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	981
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	982 If \module{optparse} sees either \code{"-h"} or \code{"-{}-help"} on the command line, it
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	983 will print something like the following help message to stdout
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	984 (assuming \code{sys.argv{[}0]} is \code{"foo.py"}):
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	985 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	986 usage: foo.py [options]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	987
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	988 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	989 -h, --help Show this help message and exit
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	990 -v Be moderately verbose
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	991 --file=FILENAME Input file to read data from
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	992 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	993
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	994 After printing the help message, \module{optparse} terminates your process
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	995 with \code{sys.exit(0)}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	996
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	997 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	998 \code{version}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	999
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1000 Prints the version number supplied to the OptionParser to stdout and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1001 exits. The version number is actually formatted and printed by the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1002 \code{print{\_}version()} method of OptionParser. Generally only relevant
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1003 if the \code{version} argument is supplied to the OptionParser
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1004 constructor. As with \member{help} options, you will rarely create
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1005 \code{version} options, since \module{optparse} automatically adds them when needed.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1006
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1007 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1008
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1009
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1010 \subsubsection{Standard option types\label{optparse-standard-option-types}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1011
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1012 \module{optparse} has six built-in option types: \code{string}, \code{int}, \code{long},
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1013 \code{choice}, \code{float} and \code{complex}. If you need to add new option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1014 types, see section~\ref{optparse-extending}, Extending \module{optparse}.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1015
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1016 Arguments to string options are not checked or converted in any way: the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1017 text on the command line is stored in the destination (or passed to the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1018 callback) as-is.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1019
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1020 Integer arguments are passed to \code{int()} to convert them to Python
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1021 integers. If \code{int()} fails, so will \module{optparse}, although with a more
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1022 useful error message. (Internally, \module{optparse} raises OptionValueError;
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1023 OptionParser catches this exception higher up and terminates your
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1024 program with a useful error message.)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1025
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1026 Likewise, \code{float} arguments are passed to \code{float()} for conversion,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1027 \code{long} arguments to \code{long()}, and \code{complex} arguments to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1028 \code{complex()}. Apart from that, they are handled identically to integer
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1029 arguments.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1030
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1031 \code{choice} options are a subtype of \code{string} options. The \code{choices}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1032 option attribute (a sequence of strings) defines the set of allowed
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1033 option arguments. \code{optparse.option.check{\_}choice()} compares
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1034 user-supplied option arguments against this master list and raises
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1035 OptionValueError if an invalid string is given.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1036
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1037
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1038 \subsubsection{Querying and manipulating your option parser\label{optparse-querying-manipulating-option-parser}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1039
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1040 Sometimes, it's useful to poke around your option parser and see what's
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1041 there. OptionParser provides a couple of methods to help you out:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1042 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1043 \item[\code{has{\_}option(opt{\_}str)}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1044 Return true if the OptionParser has an option with
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1045 option string \code{opt{\_}str} (e.g., \code{"-q"} or \code{"-{}-verbose"}).
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1046 \item[\code{get{\_}option(opt{\_}str)}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1047 Returns the Option instance with the option string \code{opt{\_}str}, or
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1048 \code{None} if no options have that option string.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1049 \item[\code{remove{\_}option(opt{\_}str)}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1050 If the OptionParser has an option corresponding to \code{opt{\_}str},
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1051 that option is removed. If that option provided any other
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1052 option strings, all of those option strings become invalid.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1053
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1054 If \code{opt{\_}str} does not occur in any option belonging to this
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1055 OptionParser, raises ValueError.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1056 \end{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1057
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1058
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1059 \subsubsection{Conflicts between options\label{optparse-conflicts-between-options}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1060
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1061 If you're not careful, it's easy to define options with conflicting
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1062 option strings:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1063 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1064 parser.add_option("-n", "--dry-run", ...)
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1065 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1066 parser.add_option("-n", "--noisy", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1067 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1068
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1069 (This is particularly true if you've defined your own OptionParser
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1070 subclass with some standard options.)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1071
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1072 Every time you add an option, \module{optparse} checks for conflicts with existing
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1073 options. If it finds any, it invokes the current conflict-handling
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1074 mechanism. You can set the conflict-handling mechanism either in the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1075 constructor:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1076 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1077 parser = OptionParser(..., conflict_handler="...")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1078 \end{verbatim}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1079
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1080 or with a separate call:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1081 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1082 parser.set_conflict_handler("...")
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1083 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1084
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1085 The available conflict-handling mechanisms are:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1086 \begin{quote}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1087 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1088 \item[\code{error} (default)]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1089 assume option conflicts are a programming error and raise
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1090 OptionConflictError
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1091 \item[\code{resolve}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1092 resolve option conflicts intelligently (see below)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1093 \end{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1094 \end{quote}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1095
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1096 As an example, let's define an OptionParser that resolves conflicts
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1097 intelligently and add conflicting options to it:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1098 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1099 parser = OptionParser(conflict_handler="resolve")
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1100 parser.add_option("-n", "--dry-run", ..., help="do no harm")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1101 parser.add_option("-n", "--noisy", ..., help="be noisy")
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1102 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1103
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1104 At this point, \module{optparse} detects that a previously-added option is already
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1105 using the \code{"-n"} option string. Since \code{conflict{\_}handler} is
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1106 \code{"resolve"}, it resolves the situation by removing \code{"-n"} from the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1107 earlier option's list of option strings. Now \code{"-{}-dry-run"} is the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1108 only way for the user to activate that option. If the user asks for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1109 help, the help message will reflect that:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1110 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1111 options:
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1112 --dry-run do no harm
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1113 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1114 -n, --noisy be noisy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1115 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1116
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1117 It's possible to whittle away the option strings for a previously-added
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1118 option until there are none left, and the user has no way of invoking
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1119 that option from the command-line. In that case, \module{optparse} removes that
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1120 option completely, so it doesn't show up in help text or anywhere else.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1121 Carrying on with our existing OptionParser:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1122 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1123 parser.add_option("--dry-run", ..., help="new dry-run option")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1124 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1125
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1126 At this point, the original \programopt{-n/-{}-dry-run} option is no longer
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1127 accessible, so \module{optparse} removes it, leaving this help text:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1128 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1129 options:
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1130 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1131 -n, --noisy be noisy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1132 --dry-run new dry-run option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1133 \end{verbatim}
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1134 % $Id: reference.txt 415 2004-09-30 02:26:17Z greg $
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1135
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1136
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1137 \subsection{Option Callbacks\label{optparse-option-callbacks}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1138
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1139 When \module{optparse}'s built-in actions and types aren't quite enough for your
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1140 needs, you have two choices: extend \module{optparse} or define a callback option.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1141 Extending \module{optparse} is more general, but overkill for a lot of simple
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1142 cases. Quite often a simple callback is all you need.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1143
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1144 There are two steps to defining a callback option:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1145 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1146 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1147 define the option itself using the \code{callback} action
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1148
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1149 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1150 write the callback; this is a function (or method) that
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1151 takes at least four arguments, as described below
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1152
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1153 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1154
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1155
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1156 \subsubsection{Defining a callback option\label{optparse-defining-callback-option}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1157
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1158 As always, the easiest way to define a callback option is by using the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1159 \code{parser.add{\_}option()} method. Apart from \member{action}, the only option
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1160 attribute you must specify is \code{callback}, the function to call:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1161 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1162 parser.add_option("-c", action="callback", callback=my_callback)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1163 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1164
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1165 \code{callback} is a function (or other callable object), so you must have
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1166 already defined \code{my{\_}callback()} when you create this callback option.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1167 In this simple case, \module{optparse} doesn't even know if \programopt{-c} takes any
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1168 arguments, which usually means that the option takes no arguments{---}the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1169 mere presence of \programopt{-c} on the command-line is all it needs to know. In
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1170 some circumstances, though, you might want your callback to consume an
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1171 arbitrary number of command-line arguments. This is where writing
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1172 callbacks gets tricky; it's covered later in this section.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1173
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1174 \module{optparse} always passes four particular arguments to your callback, and it
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1175 will only pass additional arguments if you specify them via
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1176 \code{callback{\_}args} and \code{callback{\_}kwargs}. Thus, the minimal callback
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1177 function signature is:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1178 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1179 def my_callback(option, opt, value, parser):
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1180 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1181
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1182 The four arguments to a callback are described below.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1183
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1184 There are several other option attributes that you can supply when you
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1185 define a callback option:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1186 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1187 \item[\member{type}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1188 has its usual meaning: as with the \code{store} or \code{append} actions,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1189 it instructs \module{optparse} to consume one argument and convert it to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1190 \member{type}. Rather than storing the converted value(s) anywhere,
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1191 though, \module{optparse} passes it to your callback function.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1192 \item[\code{nargs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1193 also has its usual meaning: if it is supplied and {\textgreater} 1, \module{optparse} will
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1194 consume \code{nargs} arguments, each of which must be convertible to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1195 \member{type}. It then passes a tuple of converted values to your
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1196 callback.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1197 \item[\code{callback{\_}args}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1198 a tuple of extra positional arguments to pass to the callback
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1199 \item[\code{callback{\_}kwargs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1200 a dictionary of extra keyword arguments to pass to the callback
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1201 \end{description}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1202
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1203
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1204 \subsubsection{How callbacks are called\label{optparse-how-callbacks-called}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1205
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1206 All callbacks are called as follows:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1207 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1208 func(option, opt_str, value, parser, args, *kwargs)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1209 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1210
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1211 where
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1212 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1213 \item[\code{option}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1214 is the Option instance that's calling the callback
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1215 \item[\code{opt{\_}str}]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1216 is the option string seen on the command-line that's triggering the
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1217 callback. (If an abbreviated long option was used, \code{opt{\_}str} will
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1218 be the full, canonical option string{---}e.g. if the user puts
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1219 \code{"-{}-foo"} on the command-line as an abbreviation for
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1220 \code{"-{}-foobar"}, then \code{opt{\_}str} will be \code{"-{}-foobar"}.)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1221 \item[\code{value}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1222 is the argument to this option seen on the command-line. \module{optparse} will
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1223 only expect an argument if \member{type} is set; the type of \code{value}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1224 will be the type implied by the option's type. If \member{type} for this
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1225 option is \code{None} (no argument expected), then \code{value} will be
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1226 \code{None}. If \code{nargs} {\textgreater} 1, \code{value} will be a tuple of values of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1227 the appropriate type.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1228 \item[\code{parser}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1229 is the OptionParser instance driving the whole thing, mainly
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1230 useful because you can access some other interesting data through
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1231 its instance attributes:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1232 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1233 \item[\code{parser.largs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1234 the current list of leftover arguments, ie. arguments that have
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1235 been consumed but are neither options nor option arguments.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1236 Feel free to modify \code{parser.largs}, e.g. by adding more
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1237 arguments to it. (This list will become \var{args}, the second
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1238 return value of \method{parse{\_}args()}.)
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1239 \item[\code{parser.rargs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1240 the current list of remaining arguments, ie. with \code{opt{\_}str} and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1241 \code{value} (if applicable) removed, and only the arguments
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1242 following them still there. Feel free to modify
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1243 \code{parser.rargs}, e.g. by consuming more arguments.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1244 \item[\code{parser.values}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1245 the object where option values are by default stored (an
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1246 instance of optparse.OptionValues). This lets callbacks use the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1247 same mechanism as the rest of \module{optparse} for storing option values;
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1248 you don't need to mess around with globals or closures. You can
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1249 also access or modify the value(s) of any options already
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1250 encountered on the command-line.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1251 \end{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1252 \item[\var{args}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1253 is a tuple of arbitrary positional arguments supplied via the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1254 \code{callback{\_}args} option attribute.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1255 \item[\code{kwargs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1256 is a dictionary of arbitrary keyword arguments supplied via
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1257 \code{callback{\_}kwargs}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1258 \end{description}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1259
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1260
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1261 \subsubsection{Raising errors in a callback\label{optparse-raising-errors-in-callback}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1262
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1263 The callback function should raise OptionValueError if there are any
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1264 problems with the option or its argument(s). \module{optparse} catches this and
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1265 terminates the program, printing the error message you supply to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1266 stderr. Your message should be clear, concise, accurate, and mention
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1267 the option at fault. Otherwise, the user will have a hard time
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1268 figuring out what he did wrong.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1269
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1270
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1271 \subsubsection{Callback example 1: trivial callback\label{optparse-callback-example-1}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1272
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1273 Here's an example of a callback option that takes no arguments, and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1274 simply records that the option was seen:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1275 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1276 def record_foo_seen(option, opt_str, value, parser):
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1277 parser.saw_foo = True
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1278
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1279 parser.add_option("--foo", action="callback", callback=record_foo_seen)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1280 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1281
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1282 Of course, you could do that with the \code{store{\_}true} action.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1283
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1284
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1285 \subsubsection{Callback example 2: check option order\label{optparse-callback-example-2}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1286
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1287 Here's a slightly more interesting example: record the fact that
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1288 \code{"-a"} is seen, but blow up if it comes after \code{"-b"} in the
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1289 command-line.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1290 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1291 def check_order(option, opt_str, value, parser):
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1292 if parser.values.b:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1293 raise OptionValueError("can't use -a after -b")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1294 parser.values.a = 1
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1295 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1296 parser.add_option("-a", action="callback", callback=check_order)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1297 parser.add_option("-b", action="store_true", dest="b")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1298 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1299
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1300
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1301 \subsubsection{Callback example 3: check option order (generalized)\label{optparse-callback-example-3}}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1302
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1303 If you want to re-use this callback for several similar options (set a
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1304 flag, but blow up if \code{"-b"} has already been seen), it needs a bit of
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1305 work: the error message and the flag that it sets must be
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1306 generalized.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1307 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1308 def check_order(option, opt_str, value, parser):
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1309 if parser.values.b:
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1310 raise OptionValueError("can't use %s after -b" % opt_str)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1311 setattr(parser.values, option.dest, 1)
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1312 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1313 parser.add_option("-a", action="callback", callback=check_order, dest='a')
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1314 parser.add_option("-b", action="store_true", dest="b")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1315 parser.add_option("-c", action="callback", callback=check_order, dest='c')
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1316 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1317
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1318
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1319 \subsubsection{Callback example 4: check arbitrary condition\label{optparse-callback-example-4}}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1320
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1321 Of course, you could put any condition in there{---}you're not limited
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1322 to checking the values of already-defined options. For example, if
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1323 you have options that should not be called when the moon is full, all
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1324 you have to do is this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1325 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1326 def check_moon(option, opt_str, value, parser):
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1327 if is_moon_full():
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1328 raise OptionValueError("%s option invalid when moon is full"
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1329 % opt_str)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1330 setattr(parser.values, option.dest, 1)
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1331 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1332 parser.add_option("--foo",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1333 action="callback", callback=check_moon, dest="foo")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1334 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1335
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1336 (The definition of \code{is{\_}moon{\_}full()} is left as an exercise for the
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1337 reader.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1338
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1339
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1340 \subsubsection{Callback example 5: fixed arguments\label{optparse-callback-example-5}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1341
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1342 Things get slightly more interesting when you define callback options
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1343 that take a fixed number of arguments. Specifying that a callback
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1344 option takes arguments is similar to defining a \code{store} or \code{append}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1345 option: if you define \member{type}, then the option takes one argument that
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1346 must be convertible to that type; if you further define \code{nargs}, then
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1347 the option takes \code{nargs} arguments.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1348
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1349 Here's an example that just emulates the standard \code{store} action:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1350 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1351 def store_value(option, opt_str, value, parser):
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1352 setattr(parser.values, option.dest, value)
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1353 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1354 parser.add_option("--foo",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1355 action="callback", callback=store_value,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1356 type="int", nargs=3, dest="foo")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1357 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1358
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1359 Note that \module{optparse} takes care of consuming 3 arguments and converting them
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1360 to integers for you; all you have to do is store them. (Or whatever;
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1361 obviously you don't need a callback for this example.)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1362
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1363
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1364 \subsubsection{Callback example 6: variable arguments\label{optparse-callback-example-6}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1365
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1366 Things get hairy when you want an option to take a variable number of
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1367 arguments. For this case, you must write a callback, as \module{optparse} doesn't
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1368 provide any built-in capabilities for it. And you have to deal with
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1369 certain intricacies of conventional \UNIX{} command-line parsing that \module{optparse}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1370 normally handles for you. In particular, callbacks should implement
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1371 the conventional rules for bare \code{"-{}-"} and \code{"-"} arguments:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1372 \begin{itemize}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1373 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1374 either \code{"-{}-"} or \code{"-"} can be option arguments
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1375
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1376 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1377 bare \code{"-{}-"} (if not the argument to some option): halt command-line
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1378 processing and discard the \code{"-{}-"}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1379
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1380 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1381 bare \code{"-"} (if not the argument to some option): halt command-line
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1382 processing but keep the \code{"-"} (append it to \code{parser.largs})
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1383
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1384 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1385
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1386 If you want an option that takes a variable number of arguments, there
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1387 are several subtle, tricky issues to worry about. The exact
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1388 implementation you choose will be based on which trade-offs you're
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1389 willing to make for your application (which is why \module{optparse} doesn't support
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1390 this sort of thing directly).
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1391
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1392 Nevertheless, here's a stab at a callback for an option with variable
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1393 arguments:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1394 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1395 def vararg_callback(option, opt_str, value, parser):
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1396 assert value is None
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1397 done = 0
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1398 value = []
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1399 rargs = parser.rargs
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1400 while rargs:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1401 arg = rargs[0]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1402
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1403 # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1404 # etc. Note that this also stops on "-3" or "-3.0", so if
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1405 # your option takes numeric values, you will need to handle
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1406 # this.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1407 if ((arg[:2] == "--" and len(arg) > 2) or
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1408 (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")):
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1409 break
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1410 else:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1411 value.append(arg)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1412 del rargs[0]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1413
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1414 setattr(parser.values, option.dest, value)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1415
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1416 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1417 parser.add_option("-c", "--callback",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1418 action="callback", callback=varargs)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1419 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1420
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1421 The main weakness with this particular implementation is that negative
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1422 numbers in the arguments following \code{"-c"} will be interpreted as
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1423 further options (probably causing an error), rather than as arguments to
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1424 \code{"-c"}. Fixing this is left as an exercise for the reader.
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1425 % $Id: callbacks.txt 415 2004-09-30 02:26:17Z greg $
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1426

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/liboptparse.tex @ 34161:ca2ca1aeb080 2.4