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

annotate Doc/lib/liboptparse.tex @ 38664:7619216bbc19 2.4

Bug #1502728: Correctly link against librt library on HP-UX. (backport from rev. 46743)

author	Georg Brandl <georg@python.org>
date	Thu, 08 Jun 2006 12:54:16 +0000
parents	a917e2c476f6
children

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
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	38 \code{options} object returned by \method{parse{\_}args()} based on user-supplied
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	39 command-line values. When \method{parse{\_}args()} returns from parsing this
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	40 command line, \code{options.filename} will be \code{"outfile"} and
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	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 {}
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	290 \code{options}, an object containing values for all of your options{---}e.g. if \code{"-{}-file"} takes a single string argument, then
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	291 \code{options.file} will be the filename supplied by the user, or
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	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 {}
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	295 \code{args}, the list of positional arguments leftover after parsing
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	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
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	312 attribute of \code{options}.
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	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
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	336 argument, \code{"foo.txt"}, and stores it in \code{options.filename}. So,
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	337 after this call to \method{parse{\_}args()}, \code{options.filename} is
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	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
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	382 \code{verbose} flag that is turned on with \code{"-v"} and off with \code{"-q"}:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	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
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	424 \code{verbose} to \code{True} unless \code{"-q"} is seen, then we can do this:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	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
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	444 Again, the default value for \code{verbose} will be \code{True}: the last
28966 350ee31aab0c Scattered wording and typographical improvements (up to but not Greg Ward <gward@python.net> parents: 28965 diff changeset	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
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	569 Note that \code{"{\%}prog"} is expanded just like it is in \code{usage}. Apart
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	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
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	583 \subsubsection{How \module{optparse} handles errors\label{optparse-how-optparse-handles-errors}}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	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
35271 a917e2c476f6 SF #1204347: typo fix. Greg Ward <gward@python.net> parents: 34777 diff changeset	587 erroneous calls to \code{parser.add{\_}option()}, e.g. invalid option strings,
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	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}
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	662 % $Id: tutorial.txt 417 2004-10-01 01:12:16Z 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
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	668 \subsubsection{Creating the parser\label{optparse-creating-parser}}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	669
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	670 The first step in using \module{optparse} is to create an OptionParser instance:
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	671 \begin{verbatim}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	672 parser = OptionParser(...)
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	673 \end{verbatim}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	674
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	675 The OptionParser constructor has no required arguments, but a number of
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	676 optional keyword arguments. You should always pass them as keyword
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	677 arguments, i.e. do not rely on the order in which the arguments are
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	678 declared.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	679 \begin{quote}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	680 \begin{description}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	681 \item[\code{usage} (default: \code{"{\%}prog {[}options]"})]
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	682 The usage summary to print when your program is run incorrectly or
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	683 with a help option. When \module{optparse} prints the usage string, it expands
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	684 \code{{\%}prog} to \code{os.path.basename(sys.argv{[}0])} (or to \code{prog} if
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	685 you passed that keyword argument). To suppress a usage message,
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	686 pass the special value \code{optparse.SUPPRESS{\_}USAGE}.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	687 \item[\code{option{\_}list} (default: \code{{[}]})]
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	688 A list of Option objects to populate the parser with. The options
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	689 in \code{option{\_}list} are added after any options in
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	690 \code{standard{\_}option{\_}list} (a class attribute that may be set by
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	691 OptionParser subclasses), but before any version or help options.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	692 Deprecated; use \method{add{\_}option()} after creating the parser instead.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	693 \item[\code{option{\_}class} (default: optparse.Option)]
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	694 Class to use when adding options to the parser in \method{add{\_}option()}.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	695 \item[\code{version} (default: \code{None})]
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	696 A version string to print when the user supplies a version option.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	697 If you supply a true value for \code{version}, \module{optparse} automatically adds
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	698 a version option with the single option string \code{"-{}-version"}. The
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	699 substring \code{"{\%}prog"} is expanded the same as for \code{usage}.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	700 \item[\code{conflict{\_}handler} (default: \code{"error"})]
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	701 Specifies what to do when options with conflicting option strings
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	702 are added to the parser; see section~\ref{optparse-conflicts-between-options}, Conflicts between options.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	703 \item[\code{description} (default: \code{None})]
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	704 A paragraph of text giving a brief overview of your program. \module{optparse}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	705 reformats this paragraph to fit the current terminal width and
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	706 prints it when the user requests help (after \code{usage}, but before
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	707 the list of options).
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	708 \item[\code{formatter} (default: a new IndentedHelpFormatter)]
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	709 An instance of optparse.HelpFormatter that will be used for
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	710 printing help text. \module{optparse} provides two concrete classes for this
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	711 purpose: IndentedHelpFormatter and TitledHelpFormatter.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	712 \item[\code{add{\_}help{\_}option} (default: \code{True})]
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	713 If true, \module{optparse} will add a help option (with option strings \code{"-h"}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	714 and \code{"-{}-help"}) to the parser.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	715 \item[\code{prog}]
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	716 The string to use when expanding \code{"{\%}prog"} in \code{usage} and
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	717 \code{version} instead of \code{os.path.basename(sys.argv{[}0])}.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	718 \end{description}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	719 \end{quote}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	720
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	721
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	722 \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	723
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	724 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	725 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	726 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	727 ways:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	728 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	729 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	730 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	731
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	732 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	733 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	734 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	735 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	736
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	737 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	738
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	739 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	740 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	741 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	742 option_list = [
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	743 make_option("-f", "--filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	744 action="store", type="string", dest="filename"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	745 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	746 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	747 ]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	748 parser = OptionParser(option_list=option_list)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	749 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	750
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	751 (\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	752 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	753 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	754 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	755 directly.)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	756
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	757
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	758 \subsubsection{Defining options\label{optparse-defining-options}}
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 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	761 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	762 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	763 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	764
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	765 The canonical way to create an Option instance is with the
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	766 \method{add{\_}option()} method of \class{OptionParser}:
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	767 \begin{verbatim}
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	768 parser.add_option(opt_str[, ...], attr=value, ...)
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	769 \end{verbatim}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	770
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	771 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	772 \begin{verbatim}
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	773 parser.add_option("-f", attr=value, ...)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	774 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	775
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	776 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	777 \begin{verbatim}
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	778 parser.add_option("--foo", attr=value, ...)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	779 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	780
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	781 The keyword arguments define attributes of the new Option object. The
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	782 most important option attribute is \member{action}, and it largely determines
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	783 which other attributes are relevant or required. If you pass irrelevant
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	784 option attributes, or fail to pass required ones, \module{optparse} raises an
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	785 OptionError exception explaining your mistake.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	786
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	787 An options's \emph{action} determines what \module{optparse} does when it encounters this
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	788 option on the command-line. The standard option actions hard-coded into
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	789 \module{optparse} are:
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	790 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	791 \item[\code{store}]
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	792 store this option's argument (default)
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	793 \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	794 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	795 \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	796 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	797 \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	798 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	799 \item[\code{append}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	800 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	801 \item[\code{count}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	802 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	803 \item[\code{callback}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	804 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	805 \item[\member{help}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	806 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	807 documentation for them
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	808 \end{description}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	809
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	810 (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	811 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	812 below.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	813
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	814 As you can see, most actions involve storing or updating a value
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	815 somewhere. \module{optparse} always creates a special object for this,
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	816 conventionally called \code{options} (it happens to be an instance of
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	817 \code{optparse.Values}). Option arguments (and various other values) are
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	818 stored as attributes of this object, according to the \member{dest}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	819 (destination) option attribute.
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 For example, when you call
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	822 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	823 parser.parse_args()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	824 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	825
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	826 one of the first things \module{optparse} does is create the \code{options} object:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	827 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	828 options = Values()
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	829 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	830
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	831 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	832 \begin{verbatim}
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	833 parser.add_option("-f", "--file", action="store", type="string", dest="filename")
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	834 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	835
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	836 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	837 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	838 -ffoo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	839 -f foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	840 --file=foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	841 --file foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	842 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	843
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	844 then \module{optparse}, on seeing this option, will do the equivalent of
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	845 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	846 options.filename = "foo"
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 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	850 \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	851 options.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	852
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	853
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	854 \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	855
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	856 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	857 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	858 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	859 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	860 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	861 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	862 \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	863
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	864 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	865 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	866 \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	867 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	868 \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	869 types'' section below.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	870
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	871 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	872 defaults to \code{choice}.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	873
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	874 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	875
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	876 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	877 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	878 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	879 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	880
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	881 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	882 \begin{verbatim}
33604 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("-f")
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	884 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	885 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	886
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	887 As it parses the command line
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	888 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	889 -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	890 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	891
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	892 \module{optparse} will set
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	893 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	894 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	895 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	896 options.f = "bar.txt"
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	897 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	898
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	899 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	900 \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	901
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	902 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	903
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	904 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	905 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	906 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	907 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	908 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	909 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	910 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	911 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	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 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	915 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	916 options.verbose = 2
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	917 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	918
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	919 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	920 \code{store{\_}true} {[}relevant: \member{dest}]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	921
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	922 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	923 to \member{dest}.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	924
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	925 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	926 \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	927
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	928 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	929
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	930 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	931 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	932 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	933 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	934 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	935
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	936 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	937 \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	938
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	939 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	940 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	941 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	942 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	943 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	944
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	945 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	946 \code{store} action.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	947
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	948 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	949 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	950 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	951 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	952
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	953 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	954 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	955 options.tracks = []
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	956 options.tracks.append(int("3"))
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	957 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	958
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	959 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	960 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	961 options.tracks.append(int("4"))
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	962 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	963
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	964 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	965 \code{count} {[}relevant: \member{dest}]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	966
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	967 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	968 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	969 time.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	970
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	971 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	972 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	973 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	974 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	975
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	976 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	977 equivalent of:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	978 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	979 options.verbosity = 0
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	980 options.verbosity += 1
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	981 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	982
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	983 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	984 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	985 options.verbosity += 1
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	986 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	987
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	988 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	989 \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	990 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	991
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	992 Call the function specified by \code{callback}, which is called as
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	993 \begin{verbatim}
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	994 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	995 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	996
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	997 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	998
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	999 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1000 \member{help}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1001
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1002 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	1003 current option parser. The help message is constructed from
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1004 the \code{usage} string passed to OptionParser's constructor and
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1005 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	1006
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1007 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	1008 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	1009 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	1010
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1011 \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	1012 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	1013
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1014 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1015 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1016 from optparse import OptionParser, SUPPRESS_HELP
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1017
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1018 parser = OptionParser()
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1019 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	1020 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	1021 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	1022 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	1023 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	1024 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	1025 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1026
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1027 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	1028 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	1029 (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	1030 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1031 usage: foo.py [options]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1032
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1033 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1034 -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	1035 -v Be moderately verbose
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1036 --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	1037 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1038
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1039 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	1040 with \code{sys.exit(0)}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1041
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1042 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1043 \code{version}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1044
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1045 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	1046 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	1047 \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	1048 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	1049 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	1050 \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	1051
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1052 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1053
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1054
34775 a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1055 \subsubsection{Option attributes\label{optparse-option-attributes}}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1056
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1057 The following option attributes may be passed as keyword arguments
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1058 to \code{parser.add{\_}option()}. If you pass an option attribute
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1059 that is not relevant to a particular option, or fail to pass a required
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1060 option attribute, \module{optparse} raises OptionError.
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1061 \begin{itemize}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1062 \item {}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1063 \member{action} (default: \code{"store"})
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1064
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1065 Determines \module{optparse}'s behaviour when this option is seen on the command
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1066 line; the available options are documented above.
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1067
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1068 \item {}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1069 \member{type} (default: \code{"string"})
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1070
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1071 The argument type expected by this option (e.g., \code{"string"} or
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1072 \code{"int"}); the available option types are documented below.
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1073
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1074 \item {}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1075 \member{dest} (default: derived from option strings)
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1076
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1077 If the option's action implies writing or modifying a value somewhere,
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1078 this tells \module{optparse} where to write it: \member{dest} names an attribute of the
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1079 \code{options} object that \module{optparse} builds as it parses the command line.
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1080
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1081 \item {}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1082 \code{default} (deprecated)
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1083
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1084 The value to use for this option's destination if the option is not
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1085 seen on the command line. Deprecated; use \code{parser.set{\_}defaults()}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1086 instead.
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1087
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1088 \item {}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1089 \code{nargs} (default: 1)
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1090
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1091 How many arguments of type \member{type} should be consumed when this
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1092 option is seen. If {\textgreater} 1, \module{optparse} will store a tuple of values to
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1093 \member{dest}.
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1094
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1095 \item {}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1096 \code{const}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1097
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1098 For actions that store a constant value, the constant value to store.
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1099
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1100 \item {}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1101 \code{choices}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1102
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1103 For options of type \code{"choice"}, the list of strings the user
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1104 may choose from.
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1105
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1106 \item {}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1107 \code{callback}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1108
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1109 For options with action \code{"callback"}, the callable to call when this
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1110 option is seen. See section~\ref{optparse-option-callbacks}, Option Callbacks for detail on the arguments
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1111 passed to \code{callable}.
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1112
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1113 \item {}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1114 \code{callback{\_}args}, \code{callback{\_}kwargs}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1115
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1116 Additional positional and keyword arguments to pass to \code{callback}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1117 after the four standard callback arguments.
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1118
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1119 \item {}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1120 \member{help}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1121
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1122 Help text to print for this option when listing all available options
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1123 after the user supplies a \member{help} option (such as \code{"-{}-help"}).
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1124 If no help text is supplied, the option will be listed without help
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1125 text. To hide this option, use the special value \code{SUPPRESS{\_}HELP}.
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1126
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1127 \item {}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1128 \code{metavar} (default: derived from option strings)
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1129
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1130 Stand-in for the option argument(s) to use when printing help text.
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1131 See section~\ref{optparse-tutorial}, the tutorial for an example.
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1132
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1133 \end{itemize}
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1134
a305fedca1bf List all option attributes (closes SF #993601). Greg Ward <gward@python.net> parents: 34774 diff changeset	1135
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1136 \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	1137
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1138 \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	1139 \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	1140 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	1141
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1142 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	1143 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	1144 callback) as-is.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1145
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1146 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	1147 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	1148 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	1149 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	1150 program with a useful error message.)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1151
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1152 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	1153 \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	1154 \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	1155 arguments.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1156
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1157 \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	1158 option attribute (a sequence of strings) defines the set of allowed
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1159 option arguments. \code{optparse.check{\_}choice()} compares
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1160 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	1161 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	1162
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1163
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1164 \subsubsection{Parsing arguments\label{optparse-parsing-arguments}}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1165
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1166 The whole point of creating and populating an OptionParser is to call
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1167 its \method{parse{\_}args()} method:
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1168 \begin{verbatim}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1169 (options, args) = parser.parse_args(args=None, options=None)
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1170 \end{verbatim}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1171
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1172 where the input parameters are
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1173 \begin{description}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1174 \item[\code{args}]
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1175 the list of arguments to process (\code{sys.argv{[}1:]} by default)
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1176 \item[\code{options}]
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1177 object to store option arguments in (a new instance of
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1178 optparse.Values by default)
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1179 \end{description}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1180
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1181 and the return values are
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1182 \begin{description}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1183 \item[\code{options}]
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1184 the same object as was passed in as \code{options}, or the new
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1185 optparse.Values instance created by \module{optparse}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1186 \item[\code{args}]
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1187 the leftover positional arguments after all options have been
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1188 processed
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1189 \end{description}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1190
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1191 The most common usage is to supply neither keyword argument. If you
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1192 supply a \code{values} object, it will be repeatedly modified with a
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1193 \code{setattr()} call for every option argument written to an option
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1194 destination, and finally returned by \method{parse{\_}args()}.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1195
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1196 If \method{parse{\_}args()} encounters any errors in the argument list, it calls
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1197 the OptionParser's \method{error()} method with an appropriate end-user error
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1198 message. This ultimately terminates your process with an exit status of
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1199 2 (the traditional \UNIX{} exit status for command-line errors).
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1200
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1201
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1202 \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	1203
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1204 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	1205 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	1206 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1207 \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	1208 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	1209 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	1210 \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	1211 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	1212 \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	1213 \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	1214 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	1215 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	1216 option strings, all of those option strings become invalid.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1217 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	1218 OptionParser, raises ValueError.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1219 \end{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1220
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1221
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1222 \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	1223
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1224 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	1225 option strings:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1226 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1227 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	1228 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1229 parser.add_option("-n", "--noisy", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1230 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1231
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1232 (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	1233 subclass with some standard options.)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1234
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1235 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	1236 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	1237 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	1238 constructor:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1239 \begin{verbatim}
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1240 parser = OptionParser(..., conflict_handler=handler)
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1241 \end{verbatim}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1242
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1243 or with a separate call:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1244 \begin{verbatim}
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1245 parser.set_conflict_handler(handler)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1246 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1247
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1248 The available conflict handlers are:
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1249 \begin{quote}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1250 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1251 \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	1252 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	1253 OptionConflictError
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1254 \item[\code{resolve}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1255 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	1256 \end{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1257 \end{quote}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1258
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1259 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	1260 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	1261 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1262 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	1263 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	1264 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	1265 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1266
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1267 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	1268 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	1269 \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	1270 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	1271 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	1272 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	1273 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1274 options:
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1275 --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	1276 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1277 -n, --noisy be noisy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1278 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1279
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1280 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	1281 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	1282 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	1283 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	1284 Carrying on with our existing OptionParser:
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1285 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1286 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	1287 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1288
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1289 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	1290 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	1291 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1292 options:
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1293 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1294 -n, --noisy be noisy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1295 --dry-run new dry-run option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1296 \end{verbatim}
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1297
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1298
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1299 \subsubsection{Other methods\label{optparse-other-methods}}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1300
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1301 OptionParser supports several other public methods:
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1302 \begin{itemize}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1303 \item {}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1304 \code{set{\_}usage(usage)}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1305
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1306 Set the usage string according to the rules described above for the
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1307 \code{usage} constructor keyword argument. Passing \code{None} sets the
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1308 default usage string; use \code{SUPPRESS{\_}USAGE} to suppress a usage
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1309 message.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1310
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1311 \item {}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1312 \code{enable{\_}interspersed{\_}args()}, \code{disable{\_}interspersed{\_}args()}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1313
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1314 Enable/disable positional arguments interspersed with options, similar
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1315 to GNU getopt (enabled by default). For example, if \code{"-a"} and
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1316 \code{"-b"} are both simple options that take no arguments, \module{optparse}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1317 normally accepts this syntax:
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1318 \begin{verbatim}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1319 prog -a arg1 -b arg2
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1320 \end{verbatim}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1321
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1322 and treats it as equivalent to
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1323 \begin{verbatim}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1324 prog -a -b arg1 arg2
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1325 \end{verbatim}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1326
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1327 To disable this feature, call \code{disable{\_}interspersed{\_}args()}. This
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1328 restores traditional \UNIX{} syntax, where option parsing stops with the
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1329 first non-option argument.
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1330
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1331 \item {}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1332 \code{set{\_}defaults(dest=value, ...)}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1333
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1334 Set default values for several option destinations at once. Using
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1335 \method{set{\_}defaults()} is the preferred way to set default values for
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1336 options, since multiple options can share the same destination. For
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1337 example, if several ``mode'' options all set the same destination, any
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1338 one of them can set the default, and the last one wins:
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1339 \begin{verbatim}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1340 parser.add_option("--advanced", action="store_const",
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1341 dest="mode", const="advanced",
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1342 default="novice") # overridden below
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1343 parser.add_option("--novice", action="store_const",
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1344 dest="mode", const="novice",
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1345 default="advanced") # overrides above setting
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1346 \end{verbatim}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1347
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1348 To avoid this confusion, use \method{set{\_}defaults()}:
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1349 \begin{verbatim}
35271 a917e2c476f6 SF #1204347: typo fix. Greg Ward <gward@python.net> parents: 34777 diff changeset	1350 parser.set_defaults(mode="advanced")
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1351 parser.add_option("--advanced", action="store_const",
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1352 dest="mode", const="advanced")
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1353 parser.add_option("--novice", action="store_const",
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1354 dest="mode", const="novice")
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1355 \end{verbatim}
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1356
9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1357 \end{itemize}
34776 04fa132c9023 Regenerate from Optik reST source to ensure CVS Id tags are up-to-date. Greg Ward <gward@python.net> parents: 34775 diff changeset	1358 % $Id: reference.txt 503 2005-03-19 17:01:27Z gward $
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1359
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1360
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1361 \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	1362
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1363 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	1364 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	1365 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	1366 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	1367
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1368 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	1369 \begin{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1370 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1371 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	1372
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 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	1375 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	1376
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1377 \end{itemize}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1378
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1379
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1380 \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	1381
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1382 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	1383 \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	1384 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	1385 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1386 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	1387 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1388
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1389 \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	1390 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	1391 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	1392 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	1393 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	1394 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	1395 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	1396 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	1397
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1398 \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	1399 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	1400 \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	1401 function signature is:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1402 \begin{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1403 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	1404 \end{verbatim}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1405
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1406 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	1407
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1408 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	1409 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	1410 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1411 \item[\member{type}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1412 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	1413 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	1414 \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	1415 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	1416 \item[\code{nargs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1417 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	1418 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	1419 \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	1420 callback.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1421 \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	1422 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	1423 \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	1424 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	1425 \end{description}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1426
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1427
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1428 \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	1429
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1430 All callbacks are called as follows:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1431 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1432 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	1433 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1434
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1435 where
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1436 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1437 \item[\code{option}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1438 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	1439 \item[\code{opt{\_}str}]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1440 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	1441 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	1442 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	1443 \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	1444 \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	1445 \item[\code{value}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1446 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	1447 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	1448 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	1449 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	1450 \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	1451 the appropriate type.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1452 \item[\code{parser}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1453 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	1454 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	1455 its instance attributes:
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1456 \begin{description}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1457 \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	1458 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	1459 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	1460 Feel free to modify \code{parser.largs}, e.g. by adding more
34774 9d80e63004cd Beef up optparse reference docs -- now much closer to documenting the Greg Ward <gward@python.net> parents: 34287 diff changeset	1461 arguments to it. (This list will become \code{args}, the second
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1462 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	1463 \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	1464 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	1465 \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	1466 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	1467 \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	1468 \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	1469 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	1470 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	1471 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	1472 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	1473 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	1474 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	1475 \end{description}
34287 3ec54c5f7081 SF bug #1090139: presentation typo in lib: 6.21.4.2 How callbacks are called Raymond Hettinger <python@rcn.com> parents: 33974 diff changeset	1476 \item[\code{args}]
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1477 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	1478 \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	1479 \item[\code{kwargs}]
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1480 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	1481 \code{callback{\_}kwargs}.
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1482 \end{description}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1483
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1484
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1485 \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	1486
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1487 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	1488 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	1489 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	1490 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	1491 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	1492 figuring out what he did wrong.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1493
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1494
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1495 \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	1496
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1497 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	1498 simply records that the option was seen:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1499 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1500 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	1501 parser.saw_foo = True
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1502
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1503 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	1504 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1505
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1506 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	1507
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1508
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1509 \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	1510
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1511 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	1512 \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	1513 command-line.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1514 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1515 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	1516 if parser.values.b:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1517 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	1518 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	1519 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1520 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	1521 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	1522 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1523
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1524
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1525 \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	1526
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1527 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	1528 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	1529 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	1530 generalized.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1531 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1532 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	1533 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	1534 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	1535 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	1536 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1537 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	1538 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	1539 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	1540 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1541
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1542
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1543 \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	1544
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1545 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	1546 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	1547 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	1548 you have to do is this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1549 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1550 def check_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	1551 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	1552 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	1553 % opt_str)
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1554 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	1555 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1556 parser.add_option("--foo",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1557 action="callback", callback=check_moon, dest="foo")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1558 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1559
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1560 (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	1561 reader.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1562
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1563
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1564 \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	1565
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1566 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	1567 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	1568 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	1569 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	1570 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	1571 the option takes \code{nargs} arguments.
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1572
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1573 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	1574 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1575 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	1576 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	1577 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1578 parser.add_option("--foo",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1579 action="callback", callback=store_value,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1580 type="int", nargs=3, dest="foo")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1581 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1582
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1583 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	1584 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	1585 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	1586
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1587
33636 e5de698ecd4b Get references working (except for references to "Extending optparse", Greg Ward <gward@python.net> parents: 33604 diff changeset	1588 \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	1589
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1590 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	1591 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	1592 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	1593 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	1594 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	1595 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	1596 \begin{itemize}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1597 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1598 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	1599
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1600 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1601 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	1602 processing and discard the \code{"-{}-"}
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1603
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1604 \item {}
641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1605 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	1606 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	1607
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1608 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1609
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1610 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	1611 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	1612 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	1613 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	1614 this sort of thing directly).
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1615
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1616 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	1617 arguments:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1618 \begin{verbatim}
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1619 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	1620 assert value is None
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1621 done = 0
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1622 value = []
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1623 rargs = parser.rargs
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1624 while rargs:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1625 arg = rargs[0]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1626
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1627 # 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	1628 # 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	1629 # 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	1630 # this.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1631 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	1632 (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	1633 break
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1634 else:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1635 value.append(arg)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1636 del rargs[0]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1637
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1638 setattr(parser.values, option.dest, value)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1639
33604 641152fb7d88 Major overhaul to reflect Optik 1.5. Section references currently broken. Greg Ward <gward@python.net> parents: 33454 diff changeset	1640 [...]
27116 a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1641 parser.add_option("-c", "--callback",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1642 action="callback", callback=varargs)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1643 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1644
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1645 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	1646 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	1647 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	1648 \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	1649 % $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	1650
34777 336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1651
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1652 \subsection{Extending \module{optparse}\label{optparse-extending-optparse}}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1653
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1654 Since the two major controlling factors in how \module{optparse} interprets
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1655 command-line options are the action and type of each option, the most
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1656 likely direction of extension is to add new actions and new types.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1657
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1658 Also, the \code{examples/} directory of the source distribution includes
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1659 several demonstrations of extending \module{optparse} in different ways: e.g. a
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1660 case-insensitive option parser, or two kinds of option parsers that
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1661 implement ``required options''.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1662
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1663
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1664 \subsubsection{Adding new types\label{optparse-adding-new-types}}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1665
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1666 To add new types, you need to define your own subclass of \module{optparse}'s Option
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1667 class. This class has a couple of attributes that define \module{optparse}'s types:
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1668 \member{TYPES} and \member{TYPE{\_}CHECKER}.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1669
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1670 \member{TYPES} is a tuple of type names; in your subclass, simply define a new
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1671 tuple \member{TYPES} that builds on the standard one.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1672
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1673 \member{TYPE{\_}CHECKER} is a dictionary mapping type names to type-checking
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1674 functions. A type-checking function has the following signature:
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1675 \begin{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1676 def check_mytype(option, opt, value)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1677 \end{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1678
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1679 where \code{option} is an \class{Option} instance, \code{opt} is an option string
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1680 (e.g., \code{"-f"}), and \code{value} is the string from the command line that
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1681 must be checked and converted to your desired type. \code{check{\_}mytype()}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1682 should return an object of the hypothetical type \code{mytype}. The value
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1683 returned by a type-checking function will wind up in the OptionValues
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1684 instance returned by \method{OptionParser.parse{\_}args()}, or be passed to a
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1685 callback as the \code{value} parameter.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1686
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1687 Your type-checking function should raise OptionValueError if it
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1688 encounters any problems. OptionValueError takes a single string
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1689 argument, which is passed as-is to OptionParser's \method{error()} method,
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1690 which in turn prepends the program name and the string \code{"error:"} and
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1691 prints everything to stderr before terminating the process.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1692
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1693 Here's a silly example that demonstrates adding a \code{complex} option
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1694 type to parse Python-style complex numbers on the command line. (This
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1695 is even sillier than it used to be, because \module{optparse} 1.3 added built-in
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1696 support for complex numbers, but never mind.)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1697
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1698 First, the necessary imports:
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1699 \begin{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1700 from copy import copy
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1701 from optparse import Option, OptionValueError
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1702 \end{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1703
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1704 You need to define your type-checker first, since it's referred to later
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1705 (in the \member{TYPE{\_}CHECKER} class attribute of your Option subclass):
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1706 \begin{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1707 def check_complex(option, opt, value):
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1708 try:
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1709 return complex(value)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1710 except ValueError:
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1711 raise OptionValueError(
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1712 "option %s: invalid complex value: %r" % (opt, value))
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1713 \end{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1714
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1715 Finally, the Option subclass:
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1716 \begin{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1717 class MyOption (Option):
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1718 TYPES = Option.TYPES + ("complex",)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1719 TYPE_CHECKER = copy(Option.TYPE_CHECKER)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1720 TYPE_CHECKER["complex"] = check_complex
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1721 \end{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1722
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1723 (If we didn't make a \function{copy()} of \member{Option.TYPE{\_}CHECKER}, we would end
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1724 up modifying the \member{TYPE{\_}CHECKER} attribute of \module{optparse}'s Option class.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1725 This being Python, nothing stops you from doing that except good manners
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1726 and common sense.)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1727
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1728 That's it! Now you can write a script that uses the new option type
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1729 just like any other \module{optparse}-based script, except you have to instruct your
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1730 OptionParser to use MyOption instead of Option:
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1731 \begin{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1732 parser = OptionParser(option_class=MyOption)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1733 parser.add_option("-c", type="complex")
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1734 \end{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1735
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1736 Alternately, you can build your own option list and pass it to
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1737 OptionParser; if you don't use \method{add{\_}option()} in the above way, you
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1738 don't need to tell OptionParser which option class to use:
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1739 \begin{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1740 option_list = [MyOption("-c", action="store", type="complex", dest="c")]
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1741 parser = OptionParser(option_list=option_list)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1742 \end{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1743
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1744
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1745 \subsubsection{Adding new actions\label{optparse-adding-new-actions}}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1746
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1747 Adding new actions is a bit trickier, because you have to understand
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1748 that \module{optparse} has a couple of classifications for actions:
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1749 \begin{description}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1750 \item[``store'' actions]
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1751 actions that result in \module{optparse} storing a value to an attribute of the
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1752 current OptionValues instance; these options require a \member{dest}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1753 attribute to be supplied to the Option constructor
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1754 \item[``typed'' actions]
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1755 actions that take a value from the command line and expect it to be
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1756 of a certain type; or rather, a string that can be converted to a
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1757 certain type. These options require a \member{type} attribute to the
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1758 Option constructor.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1759 \end{description}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1760
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1761 These are overlapping sets: some default ``store'' actions are \code{store},
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1762 \code{store{\_}const}, \code{append}, and \code{count}, while the default ``typed''
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1763 actions are \code{store}, \code{append}, and \code{callback}.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1764
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1765 When you add an action, you need to decide if it's a ``store'' action, a
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1766 ``typed'' action, neither, or both. Three class attributes of
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1767 Option (or your Option subclass) control this:
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1768 \begin{description}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1769 \item[\member{ACTIONS}]
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1770 all actions must be listed in ACTIONS
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1771 \item[\member{STORE{\_}ACTIONS}]
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1772 ``store'' actions are additionally listed here
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1773 \item[\member{TYPED{\_}ACTIONS}]
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1774 ``typed'' actions are additionally listed here
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1775 \end{description}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1776
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1777 In order to actually implement your new action, you must override
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1778 Option's \method{take{\_}action()} method and add a case that recognizes your
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1779 action.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1780
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1781 For example, let's add an \code{extend} action. This is similar to the
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1782 standard \code{append} action, but instead of taking a single value from
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1783 the command-line and appending it to an existing list, \code{extend} will
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1784 take multiple values in a single comma-delimited string, and extend an
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1785 existing list with them. That is, if \code{"-{}-names"} is an \code{extend}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1786 option of type \code{string}, the command line
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1787 \begin{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1788 --names=foo,bar --names blah --names ding,dong
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1789 \end{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1790
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1791 would result in a list
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1792 \begin{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1793 ["foo", "bar", "blah", "ding", "dong"]
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1794 \end{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1795
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1796 Again we define a subclass of Option:
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1797 \begin{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1798 class MyOption (Option):
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1799
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1800 ACTIONS = Option.ACTIONS + ("extend",)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1801 STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1802 TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1803
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1804 def take_action(self, action, dest, opt, value, values, parser):
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1805 if action == "extend":
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1806 lvalue = value.split(",")
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1807 values.ensure_value(dest, []).extend(lvalue)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1808 else:
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1809 Option.take_action(
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1810 self, action, dest, opt, value, values, parser)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1811 \end{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1812
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1813 Features of note:
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1814 \begin{itemize}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1815 \item {}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1816 \code{extend} both expects a value on the command-line and stores that
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1817 value somewhere, so it goes in both \member{STORE{\_}ACTIONS} and
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1818 \member{TYPED{\_}ACTIONS}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1819
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1820 \item {}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1821 \method{MyOption.take{\_}action()} implements just this one new action, and
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1822 passes control back to \method{Option.take{\_}action()} for the standard
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1823 \module{optparse} actions
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1824
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1825 \item {}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1826 \code{values} is an instance of the optparse{\_}parser.Values class,
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1827 which provides the very useful \method{ensure{\_}value()} method.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1828 \method{ensure{\_}value()} is essentially \function{getattr()} with a safety valve;
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1829 it is called as
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1830 \begin{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1831 values.ensure_value(attr, value)
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1832 \end{verbatim}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1833
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1834 If the \code{attr} attribute of \code{values} doesn't exist or is None, then
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1835 ensure{\_}value() first sets it to \code{value}, and then returns 'value.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1836 This is very handy for actions like \code{extend}, \code{append}, and
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1837 \code{count}, all of which accumulate data in a variable and expect that
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1838 variable to be of a certain type (a list for the first two, an integer
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1839 for the latter). Using \method{ensure{\_}value()} means that scripts using
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1840 your action don't have to worry about setting a default value for the
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1841 option destinations in question; they can just leave the default as
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1842 None and \method{ensure{\_}value()} will take care of getting it right when
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1843 it's needed.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1844
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1845 \end{itemize}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1846
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1847
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1848 \subsubsection{Other reasons to extend \module{optparse}\label{optparse-other-reasons-to-extend-optparse}}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1849
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1850 Adding new types and new actions are the big, obvious reasons why you
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1851 might want to extend \module{optparse}. I can think of at least two other areas to
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1852 play with.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1853
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1854 First, the simple one: OptionParser tries to be helpful by calling
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1855 \function{sys.exit()} when appropriate, i.e. when there's an error on the
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1856 command line or when the user requests help. In the former case, the
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1857 traditional course of letting the script crash with a traceback is
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1858 unacceptable; it will make users think there's a bug in your script when
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1859 they make a command-line error. In the latter case, there's generally
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1860 not much point in carrying on after printing a help message.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1861
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1862 If this behaviour bothers you, it shouldn't be too hard to ``fix'' it.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1863 You'll have to
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1864 \newcounter{listcnt1}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1865 \begin{list}{\arabic{listcnt1})}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1866 {
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1867 \usecounter{listcnt1}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1868 \setlength{\rightmargin}{\leftmargin}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1869 }
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1870 \item {}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1871 subclass OptionParser and override \method{error()}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1872
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1873 \item {}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1874 subclass Option and override \method{take{\_}action()}{---}you'll
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1875 need to provide your own handling of the \member{help} action that
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1876 doesn't call \function{sys.exit()}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1877
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1878 \end{list}
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1879
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1880 The second, much more complex, possibility is to override the
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1881 command-line syntax implemented by \module{optparse}. In this case, you'd leave the
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1882 whole machinery of option actions and types alone, but rewrite the code
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1883 that processes \var{sys.argv}. You'll need to subclass OptionParser in any
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1884 case; depending on how radical a rewrite you want, you'll probably need
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1885 to override one or all of \method{parse{\_}args()}, \method{{\_}process{\_}long{\_}opt()}, and
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1886 \method{{\_}process{\_}short{\_}opts()}.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1887
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1888 Both of these are left as an exercise for the reader. I have not tried
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1889 to implement either myself, since I'm quite happy with \module{optparse}'s default
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1890 behaviour (naturally).
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1891
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1892 Happy hacking, and don't forget: Use the Source, Luke.
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1893 % $Id: extending.txt 413 2004-09-28 00:59:13Z greg $
336fea406fcf SF #1086675: restore "Extending optparse" section (which was dropped Greg Ward <gward@python.net> parents: 34776 diff changeset	1894

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/liboptparse.tex @ 38664:7619216bbc19 2.4