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

annotate Doc/lib/liboptparse.tex @ 38745:ab253cd497d2 legacy-trunk

SF #1366250: optparse docs: fix inconsistency in variable name; minor tweaks.

author	Greg Ward <gward@python.net>
date	Sun, 11 Jun 2006 14:42:41 +0000
parents	3125099b3497
children	a3fda843234e

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

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/liboptparse.tex @ 38745:ab253cd497d2 legacy-trunk