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

annotate Doc/lib/liboptparse.tex @ 28646:193b8aec00ce legacy-trunk

Changes from Jonathan Riehl to allow his pgen extension (PEP 269) to work. This includes some more code that used to be part of pgen in the main parser; I'm okay with that. I'll see if the Windows build needs work next.

author	Guido van Rossum <guido@python.org>
date	Thu, 17 Apr 2003 14:55:42 +0000
parents	a2f17f4a6a22
children	1556a38d5278

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
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	24 [...]
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",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	29 action="store_false", dest="verbose", default=1,
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
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	36 "usual thing" on the command-line:
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
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	46 \code{options.verbose == 0} ...just as you might expect.)
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
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	68 \subsection{The Tao of Option Parsing\label{optparse-tao}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	69
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	70 \module{optparse} is an implementation of what I have always
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	71 considered the most obvious, straightforward, and user-friendly way to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	72 design a user interface for command-line programs. In short, I have
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	73 fairly firm ideas of the Right Way (and the many Wrong Ways) to do
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	74 argument parsing, and \module{optparse} reflects many of those ideas.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	75 This section is meant to explain this philosophy, which in turn is
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	76 heavily influenced by the Unix and GNU toolkits.
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 \subsubsection{Terminology\label{optparse-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 First, we need to establish some terminology.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	81
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	82 \begin{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	83 \term{argument}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	84 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	85 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	86 Python, arguments are elements of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	87 \var{sys.argv[1:]}. (\var{sys.argv[0]} is the name of the program
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	88 being executed; in the context of parsing arguments, it's not very
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	89 important.) Unix shells also use the term ``word''.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	90
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	91 It's occasionally desirable to substitute an argument list other
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	92 than \var{sys.argv[1:]}, so you should read ``argument'' as ``an element of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	93 \var{sys.argv[1:]}, or of some other list provided as a substitute for
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	94 \var{sys.argv[1:]}''.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	95
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	96 \term{option}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	97 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	98 the execution of a program. There are many different syntaxes for
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	99 options; the traditional Unix syntax is \programopt{-} followed by a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	100 single letter, e.g. \programopt{-x} or \programopt{-F}. Also,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	101 traditional Unix syntax allows multiple options to be merged into a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	102 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	103 \programopt{-xF}. The GNU project introduced \longprogramopt{}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	104 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	105 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	106 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	107
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	108 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	109
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	110 \begin{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	111 \item a hyphen followed by a few letters, e.g. \programopt{-pf} (this is
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	112 not the same as multiple options merged into a single
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	113 argument.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	114 \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	115 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	116 usually seen in the same program.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	117 \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	118 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	119 \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	120 \programopt{/f}, \programopt{/file}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	121 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	122
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	123 These option syntaxes are not supported by \module{optparse}, and they
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	124 never will be. (If you really want to use one of those option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	125 syntaxes, you'll have to subclass OptionParser and override all the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	126 difficult bits. But please don't! \module{optparse} does things the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	127 traditional Unix/GNU way deliberately; the first three are
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	128 non-standard anywhere, and the last one makes sense only if you're
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	129 exclusively targeting MS-DOS/Windows and/or VMS.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	130
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	131 \term{option argument}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	132 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	133 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	134 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	135 the option, e.g. :
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	136
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	137 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	138 ["-f", "foo"]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	139 \end{verbatim}
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 may be equivalent to:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	142
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	143 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	144 ["-ffoo"]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	145 \end{verbatim}
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 (\module{optparse} supports this syntax.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	148
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	149 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	150 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	151 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	152 won't if they don't. This is somewhat controversial, because it makes
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	153 parsing ambiguous: if \programopt{-a} takes an optional argument and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	154 \programopt{-b} is another option entirely, how do we interpret
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	155 \programopt{-ab}? \module{optparse} does not currently support this.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	156
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	157 \term{positional argument}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	158 something leftover in the argument list after options have been
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	159 parsed, ie. after options and their arguments have been parsed and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	160 removed from the argument list.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	161
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	162 \term{required option}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	163 an option that must be supplied on the command-line; the phrase
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	164 "required option" is an oxymoron and I personally consider it poor UI
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	165 design. \module{optparse} doesn't prevent you from implementing
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	166 required options, but doesn't give you much help at it either. See
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	167 Extending Examples (section \ref{optparse-extending-examples}) for two
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	168 ways to implement required options with \module{optparse}.
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,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	180 ``/tmp/report.txt'' is an option argument. ``foo'' and ``bar'' are
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	181 positional arguments.
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
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	186 execution of a program. In case it wasn't clear, options are usually
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
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	188 options whatsoever. (Pick a random program from the Unix or GNU
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?
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	190 The only exceptions I can think of are find, tar, and dd -- all of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	191 which are mutant oddballs that have been rightly criticized for their
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	192 non-standard syntax and confusing interfaces.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	193
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	194 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	195 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	196 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	197 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	198 for. (However, if you insist on adding ``required options'' to your
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	199 programs, look in Extending Examples (section
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	200 \ref{optparse-extending-examples}) for two ways of implementing them
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	201 with \module{optparse}.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	202
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	203 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	204 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	205 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	206 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	207 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	208
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	209 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	210 $ cp SOURCE DEST
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	211 $ cp SOURCE ... DEST-DIR
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	212 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	213
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	214 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	215 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	216 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	217 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	218 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	219 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	220
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	221 \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	222
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	223 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	224 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	225 positively requires to run.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	226
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	227 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	228 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	229 order to run successfully, it doesn't much matter \emph{how} you get that
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	230 information from the user -- most people will give up and walk away
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	231 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	232 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	233 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	234 up.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	235
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	236 In short, try to minimize the amount of information that users are
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	237 absolutely required to supply -- use sensible defaults whenever
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	238 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	239 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	240 they are entries in a config file, checkboxes in the ``Preferences''
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	241 dialog of a GUI, or command-line options -- the more options you
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	242 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	243 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	244 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	245
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	246 \subsection{Basic Usage\label{optparse-basic-usage}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	247
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	248 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	249 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	250 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	251 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	252 scripts.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	253
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	254 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	255 \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	256 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	257 \module{optparse}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	258
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	259 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	260 from optparse import OptionParser
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	261 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	262
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	263 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	264
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	265 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	266 parser = OptionParser()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	267 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	268
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	269 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	270 really a set of synonymous option strings; most commonly, you'll have
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	271 one short option string and one long option string --
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	272 e.g. \programopt{-f} and \longprogramopt{file}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	273
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	274 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	275 parser.add_option("-f", "--file", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	276 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	277
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	278 The interesting stuff, of course, is what comes after the option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	279 strings. In this document, we'll only cover four of the things you
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	280 can put there: \var{action}, \var{type}, \var{dest} (destination), and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	281 \var{help}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	282
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	283 \subsubsection{The "store" action\label{optparse-store-action}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	284
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	285 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	286 option strings for this option on the command-line. For example, the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	287 action \var{store} means: take the next argument (or the remainder of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	288 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	289 store it to your chosen destination.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	290
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	291 For example, let's fill in the "..." of that last option:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	292
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	293 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	294 parser.add_option("-f", "--file",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	295 action="store", type="string", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	296 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	297
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	298 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	299 parse it:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	300
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	301 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	302 args = ["-f", "foo.txt"]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	303 (options, args) = parser.parse_args(args)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	304 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	305
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	306 (Note that if you don't pass an argument list to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	307 \function{parse_args()}, it automatically uses \var{sys.argv[1:]}.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	308
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	309 When \module{optparse} sees the \programopt{-f}, it sucks in the next
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	310 argument -- ``foo.txt'' -- and stores it in the \var{filename}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	311 attribute of a special object. That object is the first return value
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	312 from \programopt{parse_args()}, so:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	313
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	314 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	315 print options.filename
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	316 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	317
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	318 will print ``foo.txt''.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	319
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	320 Other option types supported by \module{optparse} are ``int'' and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	321 ``float''. Here's an option that expects an integer argument:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	322
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	323 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	324 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	325 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	326
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	327 Note that I didn't supply a long option, which is perfectly acceptable.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	328 I also didn't specify the action -- it defaults to ``store''.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	329
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	330 Let's parse another fake command-line. This time, we'll jam the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	331 option argument right up against the option -- \programopt{-n42} (one
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	332 argument) is equivalent to \programopt{-n 42} (two arguments). :
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	333
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	334 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	335 (options, args) = parser.parse_args(["-n42"])
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	336 print options.num
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	337 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	338
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	339 will print ``42''.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	340
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	341 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	342
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	343 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	344 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	345 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	346
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	347 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	348 parser.add_option("-f", "--file", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	349 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	350
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	351 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	352 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	353 string is \longprogramopt{foo-bar}, then the default destination is
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	354 \var{foo_bar}. If there are no long option strings,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	355 \module{optparse} looks at the first short option: the default
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	356 destination for \programopt{-f} is \var{f}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	357
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	358 Adding types is fairly easy; please refer to section
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	359 \ref{optparse-adding-types}: Adding new types.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	360
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	361 \subsubsection{Other "store_*" actions\label{optparse-other-store-actions}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	362
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	363 Flag options -- set a variable to true or false when a particular
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	364 option is seen -- are quite common. \module{optparse} supports them
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	365 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	366 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	367 \programopt{-v} and off with \programopt{-q}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	368
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	369 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	370 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	371 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	372 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	373
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	374 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	375 perfectly OK. (It just means you have to be a bit careful when setting
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	376 default values -- see below.)
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 When \module{optparse} sees \programopt{-v} on the command line, it
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	379 sets the \var{verbose} attribute of the special {option values}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	380 object to 1; when it sees \programopt{-q}, it sets \var{verbose} to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	381 0.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	382
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	383 \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	384
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	385 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	386 ``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	387 happens if those options are never seen? Since we didn't supply any
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	388 defaults, they are all set to None. Sometimes, this is just fine
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	389 (which is why it's the default), but sometimes, you want more control.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	390 To address that need, \module{optparse} lets you supply a default
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	391 value for each destination, which is assigned before the command-line
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	392 is parsed.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	393
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	394 First, consider the verbose/quiet example. If we want
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	395 \module{optparse} to set \var{verbose} to 1 unless -q is seen, then
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	396 we can do this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	397
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	398 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	399 parser.add_option("-v", action="store_true", dest="verbose", default=1)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	400 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	401 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	402
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	403 Oddly enough, this is exactly equivalent:
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 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	406 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	407 parser.add_option("-q", action="store_false", dest="verbose", default=1)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	408 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	409
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	410 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	411 option's \emph{destination}, and these two options happen to have the same
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	412 destination (the \var{verbose} variable).
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	413
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	414 Consider this:
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 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	417 parser.add_option("-v", action="store_true", dest="verbose", default=0)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	418 parser.add_option("-q", action="store_false", dest="verbose", default=1)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	419 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	420
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	421 Again, the default value for \var{verbose} will be 1: the last
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	422 default value supplied for any particular destination attribute is the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	423 one that counts.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	424
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	425 \subsubsection{Generating help\label{optparse-generating-help}}
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 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	428 \module{optparse}'s ability to generate help messages. All you have
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	429 to do is supply a \var{help} value when you add an option. Let's
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	430 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	431 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	432
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	433 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	434 usage = "usage: %prog [options] arg1 arg2"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	435 parser = OptionParser(usage=usage)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	436 parser.add_option("-v", "--verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	437 action="store_true", dest="verbose", default=1,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	438 help="make lots of noise [default]")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	439 parser.add_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	440 action="store_false", dest="verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	441 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	442 parser.add_option("-f", "--file", dest="filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	443 metavar="FILE", help="write output to FILE"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	444 parser.add_option("-m", "--mode",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	445 default="intermediate",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	446 help="interaction mode: one of 'novice', "
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	447 "'intermediate' [default], 'expert'")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	448 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	449
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	450 If \module{optparse} encounters either \programopt{-h} or
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	451 \longprogramopt{--help} on the command-line, or if you just call
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	452 \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	453
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	454 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	455 usage: <yourscript> [options] arg1 arg2
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	456
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	457 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	458 -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	459 -v, --verbose make lots of noise [default]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	460 -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	461 -fFILE, --file=FILE write output to FILE
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	462 -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	463 [default], 'expert'
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	464 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	465
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	466 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	467 best possible help message:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	468
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	469 \begin{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	470 \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	471
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	472 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	473 usage = "usage: %prog [options] arg1 arg2"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	474 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	475
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	476 \module{optparse} expands "\%prog" in the usage string to the name of the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	477 current script, ie. \code{os.path.basename(sys.argv[0])}. The
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	478 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	479
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	480 If you don't supply a usage string, \module{optparse} uses a bland but
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	481 sensible default: ``usage: \%prog [options]'', which is fine if your
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	482 script doesn't take any positional arguments.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	483
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	484 \item every option defines a help string, and doesn't worry about
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	485 line-wrapping -- \module{optparse} takes care of wrapping lines and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	486 making the help output look good.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	487
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	488 \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	489 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	490
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	491 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	492 -mMODE, --mode=MODE
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	493 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	494
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	495 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	496 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	497 \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	498 converts the destination variable name to uppercase and uses that for
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	499 the meta-variable. Sometimes, that's not what you want -- for
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	500 example, the \var{filename} option explicitly sets
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	501 \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	502 option description:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	503
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	504 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	505 -fFILE, --file=FILE
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	506 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	507
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	508 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	509 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	510 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	511 ``-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	512 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	513 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	514 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	515
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	516 \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	517
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	518 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	519 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	520 the \var{version} argument to \class{OptionParser}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	521
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	522 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	523 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	524 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	525
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	526 Note that ``\%prog'' is expanded just like it is in \var{usage}. Apart from
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	527 that, \var{version} can contain anything you like. When you supply it,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	528 \module{optparse} automatically adds a\ longprogramopt{version} option to your
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	529 parser. If it encounters this option on the command line, it expands
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	530 your \var{version} string (by replacing ``\%prog''), prints it to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	531 stdout, and exits.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	532
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	533 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	534
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	535 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	536 $ /usr/bin/foo --version
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	537 foo 1.0
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	538 $
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	539 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	540
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	541 \subsubsection{Error-handling\label{optparse-error-handling}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	542
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	543 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	544 \module{optparse} behaves when it encounters an error on the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	545 command-line -- e.g. \programopt{-n4x} where \programopt{-n} is an
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	546 integer-valued option. \module{optparse} prints your usage message to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	547 stderr, followed by a useful and human-readable error message. Then
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	548 it terminates (calls \function{sys.exit()}) with a non-zero exit
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	549 status.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	550
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	551 If you don't like this, subclass \class{OptionParser} and override the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	552 \method{error()} method. See section \ref{optparse-extending}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	553 Extending \module{optparse}.
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 \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	556
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	557 Here's what my \module{optparse}-based scripts usually look like:
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 from optparse import OptionParser
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	561
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	562 [...]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	563
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	564 def main ():
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	565 usage = "usage: %prog [options] arg"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	566 parser = OptionParser(usage)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	567 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	568 help="read data from FILENAME")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	569 parser.add_option("-v", "--verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	570 action="store_true", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	571 parser.add_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	572 action="store_false", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	573 [... more options ...]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	574
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	575 (options, args) = parser.parse_args()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	576 if len(args) != 1:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	577 parser.error("incorrect number of arguments")
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 if options.verbose:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	580 print "reading %s..." % options.filename
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	581
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	582 [... go to work ...]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	583
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	584 if __name__ == "__main__":
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	585 main()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	586 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	587
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	588 \subsection{Advanced Usage\label{optparse-advanced-usage}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	589
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	590 This is reference documentation. If you haven't read the basic
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	591 documentation in section \ref{optparse-basic-usage}, do so now.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	592
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	593 \subsubsection{Creating and populating the parser\label{optparse-creating-the-parser}}
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 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	596 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	597 constructor:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	598
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	599 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	600 parser = OptionParser(option_list=[
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	601 make_option("-f", "--filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	602 action="store", type="string", dest="filename"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	603 make_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	604 action="store_false", dest="verbose")])
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	605 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	606
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	607 (As of \module{optparse} 1.3, \function{make_option()} is an alias for
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	608 the \class{Option} class, ie. this just calls the \class{Option}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	609 constructor. A future version of \module{optparse} will probably
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	610 split \class{Option} into several classes, and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	611 \function{make_option()} will become a factory function that picks the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	612 right class to instantiate.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	613
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	614 For long option lists, it's often more convenient/readable to create the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	615 list separately:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	616
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	617 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	618 option_list = [make_option("-f", "--filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	619 action="store", type="string", dest="filename"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	620 # ... 17 other options ...
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	621 make_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	622 action="store_false", dest="verbose")]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	623 parser = OptionParser(option_list=option_list)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	624 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	625
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	626 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	627 \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	628
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	629 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	630 parser = OptionParser()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	631 parser.add_option("-f", "--filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	632 action="store", type="string", dest="filename")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	633 parser.add_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	634 action="store_false", dest="verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	635 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	636
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	637 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	638 \class{Option} constructor, which are common because of the complicated
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	639 interdependencies among the various keyword arguments -- if you get it
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	640 wrong, \module{optparse} raises \exception{OptionError}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	641
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	642 \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	643
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	644 \begin{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	645 \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	646 \item pass it any combination of positional and keyword arguments that
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	647 are acceptable to \function{make_option()} (ie., to the \class{Option}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	648 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	649 (shown above).
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	650 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	651
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	652 \subsubsection{Defining options\label{optparse-defining-options}}
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 Each \class{Option} instance represents a set of synonymous
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	655 command-line options, ie. options that have the same meaning and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	656 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	657 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	658 string.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	659
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	660 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	661
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	662 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	663 make_option("-f", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	664 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	665
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	666 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	667
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	668 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	669 make_option("--foo", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	670 \end{verbatim}
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 The ``...'' represents a set of keyword arguments that define
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	673 attributes of the \class{Option} object. Just which keyword args you
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	674 must supply for a given \class{Option} is fairly complicated (see the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	675 various \method{_check_*()} methods in the \class{Option} class if you
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	676 don't believe me), but you always have to supply \emph{some}. If you
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	677 get it wrong, \module{optparse} raises an \exception{OptionError}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	678 exception explaining your mistake.
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 The most important attribute of an option is its action, ie. what to do
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	681 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	682 are:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	683
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	684 \begin{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	685 \term{store} [default]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	686 store this option's argument.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	687 \term{store_const}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	688 store a constant value.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	689 \term{store_true}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	690 store a true value.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	691 \term{store_false}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	692 store a false value.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	693 \term{append}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	694 append this option's argument to a list.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	695 \term{count}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	696 increment a counter by one.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	697 \term{callback}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	698 call a specified function.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	699 \term{help}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	700 print a usage message including all options and the documentation for
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	701 them.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	702 \end{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	703
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	704 (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	705 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	706 below.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	707
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	708 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	709 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	710 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	711 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	712 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	713 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	714
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	715 For example, when you call:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	716
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	717 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	718 parser.parse_args()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	719 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	720
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	721 one of the first things \module{optparse} does is create a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	722 \var{values} object:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	723
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	724 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	725 values = Values()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	726 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	727
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	728 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	729
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	730 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	731 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	732 \end{verbatim}
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 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	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 -ffoo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	738 -f foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	739 --file=foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	740 --file foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	741 \end{verbatim}
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 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	744 \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	745
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	746 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	747 values.filename = "foo"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	748 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	749
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	750 Clearly, the \var{type} and \var{dest} arguments are (usually) almost
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	751 as important as \var{action}. \var{action} is the only attribute that
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	752 is meaningful for all options, though, so it is the most important.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	753
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	754 \subsubsection{Option actions\label{optparse-option-actions}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	755
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	756 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	757 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	758 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	759 requirements for each action are listed here.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	760
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	761 \begin{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	762 \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	763
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	764 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	765 value according to \var{type} and stored in \var{dest}. If
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	766 \var{nargs} > 1, multiple arguments will be consumed from the command
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	767 line; all will be converted according to \var{type} and stored to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	768 \var{dest} as a tuple. See section \ref{optparse-option-types}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	769 Option types below.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	770
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	771 If \var{choices} is supplied (a list or tuple of strings), the type
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	772 defaults to ``choice''.
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 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	775
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	776 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	777 destination from the first long option strings (e.g.,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	778 \longprogramopt{foo-bar} -> \var{foo_bar}). If there are no long
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	779 option strings, \module{optparse} derives a destination from the first
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	780 short option string (e.g., \programopt{-f} -> \var{f}).
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	781
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	782 Example:
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 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	785 make_option("-f")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	786 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	787 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	788
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	789 Given the following command line:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	790
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	791 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	792 -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	793 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	794
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	795 \module{optparse} will set:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	796
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	797 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	798 values.f = "bar.txt"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	799 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	800 \end{verbatim}
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 (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	803 time is visible in the end.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	804
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	805 \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	806
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	807 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	808 stored in \var{dest}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	809
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	810 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	811
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	812 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	813 make_option("-q", "--quiet",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	814 action="store_const", const=0, dest="verbose"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	815 make_option("-v", "--verbose",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	816 action="store_const", const=1, dest="verbose"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	817 make_option(None, "--noisy",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	818 action="store_const", const=2, dest="verbose"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	819 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	820
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	821 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	822
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	823 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	824 values.verbose = 2
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	825 \end{verbatim}
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 \term{store_true} [required: \var{dest}]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	828
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	829 A special case of ``store_const'' that stores a true value
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	830 (specifically, the integer 1) to \var{dest}.
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 \term{store_false} [required: \var{dest}]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	833
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	834 Like ``store_true'', but stores a false value (the integer 0).
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	835
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	836 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	837
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	838 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	839 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	840 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	841 \end{verbatim}
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 \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	844
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	845 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	846 list in \var{dest}. If no default value for \var{dest} is supplied
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	847 (ie. the default is None), an empty list is automatically created when
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	848 \module{optparse} first encounters this option on the command-line.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	849 If \samp{nargs > 1}, multiple arguments are consumed, and a tuple of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	850 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	851
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	852 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	853 ``store'' action.
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("-t", "--tracks", action="append", type="int")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	859 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	860
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	861 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	862
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	863 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	864 values.tracks = []
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	865 values.tracks.append(int("3"))
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	866 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	867
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	868 If, a little later on, \samp{--tracks=4} is seen, it does:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	869
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	870 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	871 values.tracks.append(int("4"))
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	872 \end{verbatim}
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 See Error handling (section \ref{optparse-error-handling}) for
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	875 information on how \module{optparse} deals with something like
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	876 \samp{--tracks=x}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	877
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	878 \term{count} [required: \var{dest}]
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 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	881 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	882 value).
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	883
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	884 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	885
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	886 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	887 make_option("-v", action="count", dest="verbosity")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	888 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	889
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	890 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	891 \module{optparse} does the equivalent of:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	892
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	893 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	894 values.verbosity = 0
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	895 values.verbosity += 1
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	896 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	897
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	898 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	899
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	900 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	901 values.verbosity += 1
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	902 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	903
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	904 \term{callback} [required: \var{'callback'};
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	905 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	906 \var{callback_kwargs}]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	907
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	908 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	909 this function should be:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	910
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	911 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	912 func(option : Option,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	913 opt : string,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	914 value : any,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	915 parser : OptionParser,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	916 args, *kwargs)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	917 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	918
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	919 Callback options are covered in detail in section
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	920 \ref{optparse-callback-options}: Callback Options.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	921
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	922 \term{help} [required: none]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	923
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	924 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	925 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	926 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	927 string passed to every option.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	928
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	929 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	930 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	931 special value \constant{optparse.SUPPRESS_HELP}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	932
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	933 Example:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	934
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	935 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	936 from optparse import Option, OptionParser, SUPPRESS_HELP
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	937
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	938 usage = "usage: %prog [options]"
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	939 parser = OptionParser(usage, option_list=[
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	940 make_option("-h", "--help", action="help"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	941 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	942 help="Be moderately verbose")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	943 make_option("--file", dest="filename",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	944 help="Input file to read data from"),
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	945 make_option("--secret", help=SUPPRESS_HELP)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	946 \end{verbatim}
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 \module{optparse} sees either \longprogramopt{-h} or \longprogramopt{help} on
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	949 the command line, it will print something like the following help
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	950 message to stdout:
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 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	953 usage: <yourscript> [options]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	954
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	955 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	956 -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	957 -v Be moderately verbose
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	958 --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	959 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	960
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	961 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	962 with \code{sys.exit(0)}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	963
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	964 \term{version} [required: none]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	965
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	966 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	967 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	968 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	969 \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	970 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	971 \end{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	972
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	973 \subsubsection{Option types\label{optparse-option-types}}
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 \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	976 \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	977 (Of these, string, int, float, and choice are the most commonly used
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	978 -- long and complex are there mainly for completeness.) It's easy to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	979 add new option types by subclassing the \class{Option} class; see
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	980 section \ref{optparse-extending}: Extending \module{optparse}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	981
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	982 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	983 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	984 to the callback) as-is.
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 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	987 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	988 \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	989 Internally, \module{optparse} raises \exception{OptionValueError} in
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	990 \function{optparse.check_builtin()}; at a higher level (in
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	991 \class{OptionParser}) this is caught and \module{optparse} terminates
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	992 your program with a useful error message.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	993
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	994 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	995 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	996 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	997 identically to integer arguments.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	998
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	999 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	1000 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	1001 (\function{make_option()} or \method{OptionParser.add_option()}) as
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1002 the ``choices'' keyword argument. Choice option arguments are
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1003 compared against this master list in
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1004 \function{optparse.check_choice()}, and \exception{OptionValueError}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1005 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	1006
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1007 \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	1008
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1009 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	1010 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	1011
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1012 \begin{methoddesc}{has_option}{opt_str}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1013 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	1014 \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	1015 has an option with that option string.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1016 \end{methoddesc}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1017
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1018 \begin{methoddesc}{get_option}{opt_str}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1019 Returns the \class{Option} instance that implements the option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1020 string you supplied, or None if no options implement it.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1021 \end{methoddesc}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1022
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1023 \begin{methoddesc}{remove_option}{opt_str}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1024 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	1025 \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	1026 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	1027 invalid.
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 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	1030 \class{OptionParser}, raises \exception{ValueError}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1031 \end{methoddesc}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1032
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1033 \subsubsection{Conflicts between options\label{optparse-conflicts}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1034
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1035 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	1036
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1037 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1038 parser.add_option("-n", "--dry-run", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1039 [...]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1040 parser.add_option("-n", "--noisy", ...)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1041 \end{verbatim}
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 (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	1044 \class{OptionParser} subclass with some standard options.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1045
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1046 On the assumption that this is usually a mistake, \module{optparse}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1047 1.2 and later raise an exception (\exception{OptionConflictError}) by
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1048 default when this happens. Since this is an easily-fixed programming
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1049 error, you shouldn't try to catch this exception -- fix your mistake
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1050 and get on with life.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1051
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1052 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	1053 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	1054
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1055 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1056 parser.set_conflict_handler("resolve")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1057 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1058
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1059 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	1060 intelligently.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1061
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1062 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	1063 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	1064 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	1065 \class{OptionParser} constructor:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1066
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1067 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1068 parser = OptionParser(..., conflict_handler="resolve")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1069 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1070
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1071 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	1072
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1073 The default conflict-handling mechanism is ``error''. The only other
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1074 one is ``ignore'', which restores the (arguably broken) behaviour of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1075 \module{optparse} 1.1 and earlier.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1076
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1077 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	1078 resolve conflicts intelligently:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1079
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1080 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1081 parser = OptionParser(conflict_handler="resolve")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1082 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1083
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1084 Now add all of our options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1085
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1086 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1087 parser.add_option("-n", "--dry-run", ..., help="original dry-run option")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1088 [...]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1089 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	1090 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1091
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1092 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	1093 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	1094 == "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	1095 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	1096 \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	1097 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	1098 that, e.g.:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1099
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1100 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1101 options:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1102 --dry-run original dry-run option
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 -n, --noisy be noisy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1105 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1106
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1107 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	1108 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	1109 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	1110 \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	1111 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	1112 existing \class{OptionParser}:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1113
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1114 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1115 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	1116 \end{verbatim}
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 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	1119 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	1120 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	1121
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1122 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1123 options:
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 -n, --noisy be noisy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1126 --dry-run new dry-run option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1127 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1128
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1129 \subsection{Callback Options\label{optparse-callback-options}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1130
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1131 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	1132 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	1133 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	1134 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	1135 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	1136 \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	1137
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1138 \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	1139
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1140 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	1141 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	1142 \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	1143 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	1144 to call:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1145
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1146 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1147 parser.add_option("-c", callback=my_callback)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1148 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1149
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1150 Note that you supply a function object here -- so you must have
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1151 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	1152 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	1153 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	1154 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	1155 -- 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	1156 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	1157 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	1158 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	1159 this document.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1160
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1161 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	1162 define an option attribute:
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{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1165 \term{type}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1166 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	1167 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	1168 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	1169 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	1170 your callback function.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1171
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1172 \term{nargs}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1173 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	1174 \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	1175 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	1176 converted values to your callback.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1177
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1178 \term{callback_args}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1179 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	1180
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1181 \term{callback_kwargs}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1182 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	1183 \end{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1184
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1185 \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	1186
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1187 All callbacks are called as follows:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1188
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1189 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1190 func(option, opt, value, parser, args, *kwargs)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1191 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1192
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1193 where
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1194
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1195 \begin{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1196 \term{option}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1197 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	1198
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1199 \term{opt}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1200 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	1201 callback. (If an abbreviated long option was used, \var{opt} will be
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1202 the full, canonical option string -- e.g. if the user puts
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1203 \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	1204 \longprogramopt{foobar}, then \var{opt} will be
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1205 \longprogramopt{foobar}.)
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 \term{value}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1208 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	1209 \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	1210 set; the type of \var{value} will be the type implied by the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1211 option's type (see \ref{optparse-option-types}: Option types). If
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1212 \var{type} for this option is None (no argument expected), then
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1213 \var{value} will be None. If \samp{nargs > 1}, \var{value} will
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1214 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	1215
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1216 \term{parser}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1217 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	1218 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	1219 as instance attributes:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1220
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1221 \begin{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1222 \term{parser.rargs}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1223 the current remaining argument list, ie. with \var{opt} (and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1224 \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	1225 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	1226 e.g. by consuming more arguments.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1227
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1228 \term{parser.largs}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1229 the current set of leftover arguments, ie. arguments that have been
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1230 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	1231 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	1232 more arguments to it.
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.values}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1235 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	1236 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	1237 \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	1238 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	1239 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	1240 \end{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1241
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1242 \term{args}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1243 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	1244 \var{callback}_args option attribute.
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{kwargs}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1247 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	1248 \var{callback_kwargs}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1249 \end{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1250
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1251 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	1252 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	1253 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	1254
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1255 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1256 def my_callback (option, opt, value, parser):
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1257 pass
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1258 \end{verbatim}
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 \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	1261
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1262 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	1263 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	1264 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	1265 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	1266 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	1267 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	1268 did wrong.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1269
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1270 \subsubsection{Examples\label{optparse-callback-examples}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1271
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1272 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	1273 simply records that the option was seen:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1274
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1275 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1276 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	1277 parser.saw_foo = 1
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1278
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1279 parser.add_option("--foo", action="callback", callback=record_foo_seen)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1280 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1281
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1282 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	1283 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	1284 \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	1285 in the command-line.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1286
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1287 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1288 def check_order (option, opt, value, parser):
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1289 if parser.values.b:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1290 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	1291 parser.values.a = 1
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 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	1294 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	1295 \end{verbatim}
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 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	1298 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	1299 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	1300 generalized.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1301
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1302 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1303 def check_order (option, opt, value, parser):
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1304 if parser.values.b:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1305 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	1306 setattr(parser.values, option.dest, 1)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1307 [...]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1308 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	1309 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	1310 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	1311 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1312
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1313 Of course, you could put any condition in there -- you're not limited
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1314 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	1315 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	1316 you have to do is this:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1317
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1318 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1319 def check_moon (option, opt, value, parser):
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1320 if is_full_moon():
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1321 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	1322 setattr(parser.values, option.dest, 1)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1323 [...]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1324 parser.add_option("--foo",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1325 action="callback", callback=check_moon, dest="foo")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1326 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1327
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1328 (The definition of is_full_moon() is left as an exercise for the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1329 reader.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1330
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1331 \strong{Fixed arguments}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1332
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1333 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	1334 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	1335 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	1336 ``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	1337 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	1338 \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	1339
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1340 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	1341
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1342 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1343 def store_value (option, opt, value, parser):
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1344 setattr(parser.values, option.dest, value)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1345 [...]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1346 parser.add_option("--foo",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1347 action="callback", callback=store_value,
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1348 type="int", nargs=3, dest="foo")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1349 \end{verbatim}
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 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	1352 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	1353 (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	1354 Use your imagination!)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1355
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1356 \strong{Variable 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 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	1359 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	1360 \module{optparse} doesn't provide any built-in capabilities for it.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1361 You have to deal with the full-blown syntax for conventional Unix
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1362 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	1363 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	1364 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	1365 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	1366 convention is:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1367
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1368 \begin{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1369 \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	1370 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	1371 itself is lost.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1372
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1373 \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	1374 halt, but the \programopt{-} itself is kept.
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 \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	1377 arguments.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1378 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1379
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1380 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	1381 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	1382 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	1383 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	1384 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	1385
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1386 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	1387 arguments:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1388
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1389 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1390 def varargs (option, opt, value, parser):
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1391 assert value is None
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1392 done = 0
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1393 value = []
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1394 rargs = parser.rargs
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1395 while rargs:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1396 arg = rargs[0]
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 # 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	1399 # 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	1400 # 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	1401 # this.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1402 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	1403 (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	1404 break
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1405 else:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1406 value.append(arg)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1407 del rargs[0]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1408
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1409 setattr(parser.values, option.dest, value)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1410
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1411 [...]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1412 parser.add_option("-c", "--callback",
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1413 action="callback", callback=varargs)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1414 \end{verbatim}
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 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	1417 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	1418 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	1419 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	1420
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1421 \subsection{Extending \module{optparse}\label{optparse-extending}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1422
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1423 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	1424 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	1425 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	1426 and new types.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1427
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1428 Also, the examples section includes several demonstrations of
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1429 extending \module{optparse} in different ways: eg. a case-insensitive
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1430 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	1431 ``required options''.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1432
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1433 \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	1434
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1435 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	1436 \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	1437 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	1438 \member{TYPE_CHECKER}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1439
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1440 \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	1441 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	1442
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1443 \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	1444 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	1445 signature:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1446
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1447 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1448 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	1449 -> foo
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1450 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1451
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1452 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	1453 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	1454 the \class{OptionValues} instance returned by
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1455 \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	1456 \var{value} parameter.
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 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	1459 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	1460 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	1461 \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	1462 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	1463 stderr before terminating the process.
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 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	1466 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	1467 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	1468 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	1469 never mind.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1470
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1471 First, the necessary imports:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1472
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1473 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1474 from copy import copy
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1475 from optparse import Option, OptionValueError
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1476 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1477
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1478 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	1479 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	1480 \class{Option} subclass):
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1481
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1482 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1483 def check_complex (option, opt, value):
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1484 try:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1485 return complex(value)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1486 except ValueError:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1487 raise OptionValueError(
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1488 "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	1489 \end{verbatim}
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 Finally, the \class{Option} subclass:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1492
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1493 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1494 class MyOption (Option):
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1495 TYPES = Option.TYPES + ("complex",)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1496 TYPE_CHECKER = copy(Option.TYPE_CHECKER)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1497 TYPE_CHECKER["complex"] = check_complex
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1498 \end{verbatim}
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 (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	1501 \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	1502 \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	1503 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	1504 manners and common sense.)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1505
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1506 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	1507 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	1508 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	1509 \class{Option}:
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 parser = OptionParser(option_class=MyOption)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1513 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	1514 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1515
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1516 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	1517 \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	1518 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	1519 class to use:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1520
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1521 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1522 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	1523 parser = OptionParser(option_list=option_list)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1524 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1525
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1526 \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	1527
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1528 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	1529 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	1530
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1531 \begin{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1532 \term{"store" actions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1533 actions that result in \module{optparse} storing a value to an attribute
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1534 of the OptionValues instance; these options require a 'dest'
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1535 attribute to be supplied to the Option constructor
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1536 \term{"typed" actions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1537 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	1538 of a certain type; or rather, a string that can be converted to a
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1539 certain type. These options require a 'type' attribute to the
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1540 Option constructor.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1541 \end{definitions}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1542
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1543 Some default ``store'' actions are ``store'', ``store_const'',
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1544 ``append'', and ``count''. The default ``typed'' actions are
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1545 ``store'', ``append'', and ``callback''.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1546
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1547 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	1548 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	1549 \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	1550
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1551 \begin{memberdesc}{ACTIONS}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1552 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	1553 \end{memberdesc}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1554 \begin{memberdesc}{STORE_ACTIONS}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1555 "store" actions are additionally listed here.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1556 \end{memberdesc}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1557 \begin{memberdesc}{TYPED_ACTIONS}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1558 "typed" actions are additionally listed here.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1559 \end{memberdesc}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1560
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1561 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	1562 \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	1563 recognizes your action.
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 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	1566 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	1567 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	1568 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	1569 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	1570 ``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	1571
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1572 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1573 --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	1574 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1575
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1576 would result in a list:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1577
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1578 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1579 ["foo", "bar", "blah", "ding", "dong"]
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1580 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1581
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1582 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	1583
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1584 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1585 class MyOption (Option):
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1586
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1587 ACTIONS = Option.ACTIONS + ("extend",)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1588 STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1589 TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1590
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1591 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	1592 if action == "extend":
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1593 lvalue = value.split(",")
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1594 values.ensure_value(dest, []).extend(lvalue)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1595 else:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1596 Option.take_action(
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1597 self, action, dest, opt, value, values, parser)
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 Features of note:
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{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1603 \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	1604 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	1605 \member{TYPED_ACTIONS}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1606
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1607 \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	1608 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	1609 the standard \module{optparse} actions.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1610
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1611 \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	1612 provides the very useful \method{ensure_value()}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1613 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	1614 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	1615
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1616 \begin{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1617 values.ensure_value(attr, value)
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1618 \end{verbatim}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1619 \end{itemize}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1620
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1621 If the \member{attr} attribute of \var{values} doesn't exist or is
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1622 None, then \method{ensure_value()} first sets it to \var{value}, and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1623 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	1624 ``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	1625 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	1626 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	1627 \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	1628 have to worry about setting a default value for the option
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1629 destinations in question; they can just leave the default as None and
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1630 \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	1631 needed.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1632
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1633 \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	1634
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1635 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	1636 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	1637 other areas to play with.
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 First, the simple one: \class{OptionParser} tries to be helpful by
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1640 calling \function{sys.exit()} when appropriate, ie. when there's an
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1641 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	1642 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	1643 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	1644 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	1645 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	1646 message.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1647
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1648 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	1649 You'll have to
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 \begin{enumerate}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1652 \item subclass OptionParser and override the error() method
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1653 \item subclass Option and override the take_action() method -- you'll
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1654 need to provide your own handling of the "help" action that
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1655 doesn't call sys.exit()
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1656 \end{enumerate}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1657
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1658 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	1659 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	1660 you'd leave the whole machinery of option actions and types alone, but
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1661 rewrite the code that processes \var{sys.argv}. You'll need to
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1662 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	1663 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	1664 \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	1665 \method{_process_short_opts()}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1666
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1667 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	1668 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	1669 \module{optparse}'s default behaviour (naturally).
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1670
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1671 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	1672
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1673 \subsubsection{Examples\label{optparse-extending-examples}}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1674
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1675 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	1676
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1677 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	1678
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1679 \verbatiminput{caseless.py}
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1680
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1681 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	1682 \module{optparse}.
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1683
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1684 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	1685 must call after parsing arguments:
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1686
a2f17f4a6a22 SF #642236, optparse LaTeX docs by Johannes Gijsbers Neal Norwitz <nnorwitz@gmail.com> parents: diff changeset	1687 \verbatiminput{required_1.py}
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 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	1690 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	1691 are present after parsing:
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 \verbatiminput{required_2.py}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/liboptparse.tex @ 28646:193b8aec00ce legacy-trunk