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

annotate Doc/lib/liboptparse.tex @ 33091:48100a01ac7c 2.3

Ignore the locale's encoding if it is an empty string.

author	Martin v. Löwis <martin@v.loewis.de>
date	Thu, 12 Aug 2004 13:14:20 +0000
parents	9f60c3ee985a
children	46224690a365

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

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/liboptparse.tex @ 33091:48100a01ac7c 2.3