add hg and python

1 files changed, 1888 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/liboptparse.tex b/sys/src/cmd/python/Doc/lib/liboptparse.tex
new file mode 100644
index 000000000..df96dd4ae
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/liboptparse.tex
@@ -0,0 +1,1888 @@
+% THIS FILE IS AUTO-GENERATED!  DO NOT EDIT!
+% (Your changes will be lost the next time it is generated.)
+\section{\module{optparse} --- More powerful command line option parser}
+\declaremodule{standard}{optparse}
+\moduleauthor{Greg Ward}{gward@python.net}
+\modulesynopsis{More convenient, flexible, and powerful command-line parsing library.}
+\versionadded{2.3}
+\sectionauthor{Greg Ward}{gward@python.net}
+% An intro blurb used only when generating LaTeX docs for the Python
+% manual (based on README.txt). 
+
+\code{optparse} is a more convenient, flexible, and powerful library for
+parsing command-line options than \code{getopt}.  \code{optparse} uses a more
+declarative style of command-line parsing: you create an instance of
+\class{OptionParser}, populate it with options, and parse the command line.
+\code{optparse} allows users to specify options in the conventional GNU/POSIX
+syntax, and additionally generates usage and help messages for you.
+
+Here's an example of using \code{optparse} in a simple script:
+\begin{verbatim}
+from optparse import OptionParser
+[...]
+parser = OptionParser()
+parser.add_option("-f", "--file", dest="filename",
+                  help="write report to FILE", metavar="FILE")
+parser.add_option("-q", "--quiet",
+                  action="store_false", dest="verbose", default=True,
+                  help="don't print status messages to stdout")
+
+(options, args) = parser.parse_args()
+\end{verbatim}
+
+With these few lines of code, users of your script can now do the
+``usual thing'' on the command-line, for example:
+\begin{verbatim}
+<yourscript> --file=outfile -q
+\end{verbatim}
+
+As it parses the command line, \code{optparse} sets attributes of the
+\code{options} object returned by \method{parse{\_}args()} based on user-supplied
+command-line values.  When \method{parse{\_}args()} returns from parsing this
+command line, \code{options.filename} will be \code{"outfile"} and
+\code{options.verbose} will be \code{False}.  \code{optparse} supports both long
+and short options, allows short options to be merged together, and
+allows options to be associated with their arguments in a variety of
+ways.  Thus, the following command lines are all equivalent to the above
+example:
+\begin{verbatim}
+<yourscript> -f outfile --quiet
+<yourscript> --quiet --file outfile
+<yourscript> -q -foutfile
+<yourscript> -qfoutfile
+\end{verbatim}
+
+Additionally, users can run one of
+\begin{verbatim}
+<yourscript> -h
+<yourscript> --help
+\end{verbatim}
+
+and \code{optparse} will print out a brief summary of your script's
+options:
+\begin{verbatim}
+usage: <yourscript> [options]
+
+options:
+  -h, --help            show this help message and exit
+  -f FILE, --file=FILE  write report to FILE
+  -q, --quiet           don't print status messages to stdout
+\end{verbatim}
+
+where the value of \emph{yourscript} is determined at runtime (normally
+from \code{sys.argv{[}0]}).
+% $Id: intro.txt 413 2004-09-28 00:59:13Z greg $ 
+
+
+\subsection{Background\label{optparse-background}}
+
+\module{optparse} was explicitly designed to encourage the creation of programs with
+straightforward, conventional command-line interfaces.  To that end, it
+supports only the most common command-line syntax and semantics
+conventionally used under \UNIX{}.  If you are unfamiliar with these
+conventions, read this section to acquaint yourself with them.
+
+
+\subsubsection{Terminology\label{optparse-terminology}}
+\begin{description}
+\item[argument]
+a string entered on the command-line, and passed by the shell to
+\code{execl()} or \code{execv()}.  In Python, arguments are elements of
+\code{sys.argv{[}1:]} (\code{sys.argv{[}0]} is the name of the program being
+executed).  \UNIX{} shells also use the term ``word''.
+
+It is occasionally desirable to substitute an argument list other
+than \code{sys.argv{[}1:]}, so you should read ``argument'' as ``an element of
+\code{sys.argv{[}1:]}, or of some other list provided as a substitute for
+\code{sys.argv{[}1:]}''.
+\item[option   ]
+an argument used to supply extra information to guide or customize the
+execution of a program.  There are many different syntaxes for
+options; the traditional \UNIX{} syntax is a hyphen (``-'') followed by a
+single letter, e.g. \code{"-x"} or \code{"-F"}.  Also, traditional \UNIX{}
+syntax allows multiple options to be merged into a single argument,
+e.g.  \code{"-x -F"} is equivalent to \code{"-xF"}.  The GNU project
+introduced \code{"-{}-"} followed by a series of hyphen-separated words,
+e.g. \code{"-{}-file"} or \code{"-{}-dry-run"}.  These are the only two option
+syntaxes provided by \module{optparse}.
+
+Some other option syntaxes that the world has seen include:
+\begin{itemize}
+\item {} 
+a hyphen followed by a few letters, e.g. \code{"-pf"} (this is
+\emph{not} the same as multiple options merged into a single argument)
+
+\item {} 
+a hyphen followed by a whole word, e.g. \code{"-file"} (this is
+technically equivalent to the previous syntax, but they aren't
+usually seen in the same program)
+
+\item {} 
+a plus sign followed by a single letter, or a few letters,
+or a word, e.g. \code{"+f"}, \code{"+rgb"}
+
+\item {} 
+a slash followed by a letter, or a few letters, or a word, e.g.
+\code{"/f"}, \code{"/file"}
+
+\end{itemize}
+
+These option syntaxes are not supported by \module{optparse}, and they never will
+be.  This is deliberate: the first three are non-standard on any
+environment, and the last only makes sense if you're exclusively
+targeting VMS, MS-DOS, and/or Windows.
+\item[option argument]
+an argument that follows an option, is closely associated with that
+option, and is consumed from the argument list when that option is.
+With \module{optparse}, option arguments may either be in a separate argument
+from their option:
+\begin{verbatim}
+-f foo
+--file foo
+\end{verbatim}
+
+or included in the same argument:
+\begin{verbatim}
+-ffoo
+--file=foo
+\end{verbatim}
+
+Typically, a given option either takes an argument or it doesn't.
+Lots of people want an ``optional option arguments'' feature, meaning
+that some options will take an argument if they see it, and won't if
+they don't.  This is somewhat controversial, because it makes parsing
+ambiguous: if \code{"-a"} takes an optional argument and \code{"-b"} is
+another option entirely, how do we interpret \code{"-ab"}?  Because of
+this ambiguity, \module{optparse} does not support this feature.
+\item[positional argument]
+something leftover in the argument list after options have been
+parsed, i.e. after options and their arguments have been parsed and
+removed from the argument list.
+\item[required option]
+an option that must be supplied on the command-line; note that the
+phrase ``required option'' is self-contradictory in English.  \module{optparse}
+doesn't prevent you from implementing required options, but doesn't
+give you much help at it either.  See \code{examples/required{\_}1.py} and
+\code{examples/required{\_}2.py} in the \module{optparse} source distribution for two
+ways to implement required options with \module{optparse}.
+\end{description}
+
+For example, consider this hypothetical command-line:
+\begin{verbatim}
+prog -v --report /tmp/report.txt foo bar
+\end{verbatim}
+
+\code{"-v"} and \code{"-{}-report"} are both options.  Assuming that
+\longprogramopt{report} takes one argument, \code{"/tmp/report.txt"} is an option
+argument.  \code{"foo"} and \code{"bar"} are positional arguments.
+
+
+\subsubsection{What are options for?\label{optparse-what-options-for}}
+
+Options are used to provide extra information to tune or customize the
+execution of a program.  In case it wasn't clear, options are usually
+\emph{optional}.  A program should be able to run just fine with no options
+whatsoever.  (Pick a random program from the \UNIX{} or GNU toolsets.  Can
+it run without any options at all and still make sense?  The main
+exceptions are \code{find}, \code{tar}, and \code{dd}{---}all of which are mutant
+oddballs that have been rightly criticized for their non-standard syntax
+and confusing interfaces.)
+
+Lots of people want their programs to have ``required options''.  Think
+about it.  If it's required, then it's \emph{not optional}!  If there is a
+piece of information that your program absolutely requires in order to
+run successfully, that's what positional arguments are for.
+
+As an example of good command-line interface design, consider the humble
+\code{cp} utility, for copying files.  It doesn't make much sense to try to
+copy files without supplying a destination and at least one source.
+Hence, \code{cp} fails if you run it with no arguments.  However, it has a
+flexible, useful syntax that does not require any options at all:
+\begin{verbatim}
+cp SOURCE DEST
+cp SOURCE ... DEST-DIR
+\end{verbatim}
+
+You can get pretty far with just that.  Most \code{cp} implementations
+provide a bunch of options to tweak exactly how the files are copied:
+you can preserve mode and modification time, avoid following symlinks,
+ask before clobbering existing files, etc.  But none of this distracts
+from the core mission of \code{cp}, which is to copy either one file to
+another, or several files to another directory.
+
+
+\subsubsection{What are positional arguments for?\label{optparse-what-positional-arguments-for}}
+
+Positional arguments are for those pieces of information that your
+program absolutely, positively requires to run.
+
+A good user interface should have as few absolute requirements as
+possible.  If your program requires 17 distinct pieces of information in
+order to run successfully, it doesn't much matter \emph{how} you get that
+information from the user{---}most people will give up and walk away
+before they successfully run the program.  This applies whether the user
+interface is a command-line, a configuration file, or a GUI: if you make
+that many demands on your users, most of them will simply give up.
+
+In short, try to minimize the amount of information that users are
+absolutely required to supply{---}use sensible defaults whenever
+possible.  Of course, you also want to make your programs reasonably
+flexible.  That's what options are for.  Again, it doesn't matter if
+they are entries in a config file, widgets in the ``Preferences'' dialog
+of a GUI, or command-line options{---}the more options you implement, the
+more flexible your program is, and the more complicated its
+implementation becomes.  Too much flexibility has drawbacks as well, of
+course; too many options can overwhelm users and make your code much
+harder to maintain.
+% $Id: tao.txt 413 2004-09-28 00:59:13Z greg $ 
+
+
+\subsection{Tutorial\label{optparse-tutorial}}
+
+While \module{optparse} is quite flexible and powerful, it's also straightforward to
+use in most cases.  This section covers the code patterns that are
+common to any \module{optparse}-based program.
+
+First, you need to import the OptionParser class; then, early in the
+main program, create an OptionParser instance:
+\begin{verbatim}
+from optparse import OptionParser
+[...]
+parser = OptionParser()
+\end{verbatim}
+
+Then you can start defining options.  The basic syntax is:
+\begin{verbatim}
+parser.add_option(opt_str, ...,
+                  attr=value, ...)
+\end{verbatim}
+
+Each option has one or more option strings, such as \code{"-f"} or
+\code{"-{}-file"}, and several option attributes that tell \module{optparse} what to
+expect and what to do when it encounters that option on the command
+line.
+
+Typically, each option will have one short option string and one long
+option string, e.g.:
+\begin{verbatim}
+parser.add_option("-f", "--file", ...)
+\end{verbatim}
+
+You're free to define as many short option strings and as many long
+option strings as you like (including zero), as long as there is at
+least one option string overall.
+
+The option strings passed to \method{add{\_}option()} are effectively labels for
+the option defined by that call.  For brevity, we will frequently refer
+to \emph{encountering an option} on the command line; in reality, \module{optparse}
+encounters \emph{option strings} and looks up options from them.
+
+Once all of your options are defined, instruct \module{optparse} to parse your
+program's command line:
+\begin{verbatim}
+(options, args) = parser.parse_args()
+\end{verbatim}
+
+(If you like, you can pass a custom argument list to \method{parse{\_}args()},
+but that's rarely necessary: by default it uses \code{sys.argv{[}1:]}.)
+
+\method{parse{\_}args()} returns two values:
+\begin{itemize}
+\item {} 
+\code{options}, an object containing values for all of your options{---}e.g. if \code{"-{}-file"} takes a single string argument, then
+\code{options.file} will be the filename supplied by the user, or
+\code{None} if the user did not supply that option
+
+\item {} 
+\code{args}, the list of positional arguments leftover after parsing
+options
+
+\end{itemize}
+
+This tutorial section only covers the four most important option
+attributes: \member{action}, \member{type}, \member{dest} (destination), and \member{help}.
+Of these, \member{action} is the most fundamental.
+
+
+\subsubsection{Understanding option actions\label{optparse-understanding-option-actions}}
+
+Actions tell \module{optparse} what to do when it encounters an option on the
+command line.  There is a fixed set of actions hard-coded into \module{optparse};
+adding new actions is an advanced topic covered in section~\ref{optparse-extending-optparse}, Extending \module{optparse}.
+Most actions tell \module{optparse} to store a value in some variable{---}for
+example, take a string from the command line and store it in an
+attribute of \code{options}.
+
+If you don't specify an option action, \module{optparse} defaults to \code{store}.
+
+
+\subsubsection{The store action\label{optparse-store-action}}
+
+The most common option action is \code{store}, which tells \module{optparse} to take
+the next argument (or the remainder of the current argument), ensure
+that it is of the correct type, and store it to your chosen destination.
+
+For example:
+\begin{verbatim}
+parser.add_option("-f", "--file",
+                  action="store", type="string", dest="filename")
+\end{verbatim}
+
+Now let's make up a fake command line and ask \module{optparse} to parse it:
+\begin{verbatim}
+args = ["-f", "foo.txt"]
+(options, args) = parser.parse_args(args)
+\end{verbatim}
+
+When \module{optparse} sees the option string \code{"-f"}, it consumes the next
+argument, \code{"foo.txt"}, and stores it in \code{options.filename}.  So,
+after this call to \method{parse{\_}args()}, \code{options.filename} is
+\code{"foo.txt"}.
+
+Some other option types supported by \module{optparse} are \code{int} and \code{float}.
+Here's an option that expects an integer argument:
+\begin{verbatim}
+parser.add_option("-n", type="int", dest="num")
+\end{verbatim}
+
+Note that this option has no long option string, which is perfectly
+acceptable.  Also, there's no explicit action, since the default is
+\code{store}.
+
+Let's parse another fake command-line.  This time, we'll jam the option
+argument right up against the option: since \code{"-n42"} (one argument) is
+equivalent to \code{"-n 42"} (two arguments), the code
+\begin{verbatim}
+(options, args) = parser.parse_args(["-n42"])
+print options.num
+\end{verbatim}
+
+will print \code{"42"}.
+
+If you don't specify a type, \module{optparse} assumes \code{string}.  Combined with the
+fact that the default action is \code{store}, that means our first example
+can be a lot shorter:
+\begin{verbatim}
+parser.add_option("-f", "--file", dest="filename")
+\end{verbatim}
+
+If you don't supply a destination, \module{optparse} figures out a sensible default
+from the option strings: if the first long option string is
+\code{"-{}-foo-bar"}, then the default destination is \code{foo{\_}bar}.  If there
+are no long option strings, \module{optparse} looks at the first short option
+string: the default destination for \code{"-f"} is \code{f}.
+
+\module{optparse} also includes built-in \code{long} and \code{complex} types.  Adding
+types is covered in section~\ref{optparse-extending-optparse}, Extending \module{optparse}.
+
+
+\subsubsection{Handling boolean (flag) options\label{optparse-handling-boolean-options}}
+
+Flag options{---}set a variable to true or false when a particular option
+is seen{---}are quite common.  \module{optparse} supports them with two separate
+actions, \code{store{\_}true} and \code{store{\_}false}.  For example, you might have a
+\code{verbose} flag that is turned on with \code{"-v"} and off with \code{"-q"}:
+\begin{verbatim}
+parser.add_option("-v", action="store_true", dest="verbose")
+parser.add_option("-q", action="store_false", dest="verbose")
+\end{verbatim}
+
+Here we have two different options with the same destination, which is
+perfectly OK.  (It just means you have to be a bit careful when setting
+default values{---}see below.)
+
+When \module{optparse} encounters \code{"-v"} on the command line, it sets
+\code{options.verbose} to \code{True}; when it encounters \code{"-q"},
+\code{options.verbose} is set to \code{False}.
+
+
+\subsubsection{Other actions\label{optparse-other-actions}}
+
+Some other actions supported by \module{optparse} are:
+\begin{description}
+\item[\code{store{\_}const}]
+store a constant value
+\item[\code{append}]
+append this option's argument to a list
+\item[\code{count}]
+increment a counter by one
+\item[\code{callback}]
+call a specified function
+\end{description}
+
+These are covered in section~\ref{optparse-reference-guide}, Reference Guide and section~\ref{optparse-option-callbacks}, Option Callbacks.
+
+
+\subsubsection{Default values\label{optparse-default-values}}
+
+All of the above examples involve setting some variable (the
+``destination'') when certain command-line options are seen.  What happens
+if those options are never seen?  Since we didn't supply any defaults,
+they are all set to \code{None}.  This is usually fine, but sometimes you
+want more control.  \module{optparse} lets you supply a default value for each
+destination, which is assigned before the command line is parsed.
+
+First, consider the verbose/quiet example.  If we want \module{optparse} to set
+\code{verbose} to \code{True} unless \code{"-q"} is seen, then we can do this:
+\begin{verbatim}
+parser.add_option("-v", action="store_true", dest="verbose", default=True)
+parser.add_option("-q", action="store_false", dest="verbose")
+\end{verbatim}
+
+Since default values apply to the \emph{destination} rather than to any
+particular option, and these two options happen to have the same
+destination, this is exactly equivalent:
+\begin{verbatim}
+parser.add_option("-v", action="store_true", dest="verbose")
+parser.add_option("-q", action="store_false", dest="verbose", default=True)
+\end{verbatim}
+
+Consider this:
+\begin{verbatim}
+parser.add_option("-v", action="store_true", dest="verbose", default=False)
+parser.add_option("-q", action="store_false", dest="verbose", default=True)
+\end{verbatim}
+
+Again, the default value for \code{verbose} will be \code{True}: the last
+default value supplied for any particular destination is the one that
+counts.
+
+A clearer way to specify default values is the \method{set{\_}defaults()}
+method of OptionParser, which you can call at any time before calling
+\method{parse{\_}args()}:
+\begin{verbatim}
+parser.set_defaults(verbose=True)
+parser.add_option(...)
+(options, args) = parser.parse_args()
+\end{verbatim}
+
+As before, the last value specified for a given option destination is
+the one that counts.  For clarity, try to use one method or the other of
+setting default values, not both.
+
+
+\subsubsection{Generating help\label{optparse-generating-help}}
+
+\module{optparse}'s ability to generate help and usage text automatically is useful
+for creating user-friendly command-line interfaces.  All you have to do
+is supply a \member{help} value for each option, and optionally a short usage
+message for your whole program.  Here's an OptionParser populated with
+user-friendly (documented) options:
+\begin{verbatim}
+usage = "usage: %prog [options] arg1 arg2"
+parser = OptionParser(usage=usage)
+parser.add_option("-v", "--verbose",
+                  action="store_true", dest="verbose", default=True,
+                  help="make lots of noise [default]")
+parser.add_option("-q", "--quiet",
+                  action="store_false", dest="verbose", 
+                  help="be vewwy quiet (I'm hunting wabbits)")
+parser.add_option("-f", "--filename",
+                  metavar="FILE", help="write output to FILE"),
+parser.add_option("-m", "--mode",
+                  default="intermediate",
+                  help="interaction mode: novice, intermediate, "
+                       "or expert [default: %default]")
+\end{verbatim}
+
+If \module{optparse} encounters either \code{"-h"} or \code{"-{}-help"} on the command-line,
+or if you just call \method{parser.print{\_}help()}, it prints the following to
+standard output:
+\begin{verbatim}
+usage: <yourscript> [options] arg1 arg2
+
+options:
+  -h, --help            show this help message and exit
+  -v, --verbose         make lots of noise [default]
+  -q, --quiet           be vewwy quiet (I'm hunting wabbits)
+  -f FILE, --filename=FILE
+                        write output to FILE
+  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or
+                        expert [default: intermediate]
+\end{verbatim}
+
+(If the help output is triggered by a help option, \module{optparse} exits after
+printing the help text.)
+
+There's a lot going on here to help \module{optparse} generate the best possible
+help message:
+\begin{itemize}
+\item {} 
+the script defines its own usage message:
+\begin{verbatim}
+usage = "usage: %prog [options] arg1 arg2"
+\end{verbatim}
+
+\module{optparse} expands \code{"{\%}prog"} in the usage string to the name of the current
+program, i.e. \code{os.path.basename(sys.argv{[}0])}.  The expanded string
+is then printed before the detailed option help.
+
+If you don't supply a usage string, \module{optparse} uses a bland but sensible
+default: ``\code{usage: {\%}prog {[}options]"}, which is fine if your script
+doesn't take any positional arguments.
+
+\item {} 
+every option defines a help string, and doesn't worry about line-
+wrapping{---}\module{optparse} takes care of wrapping lines and making the
+help output look good.
+
+\item {} 
+options that take a value indicate this fact in their
+automatically-generated help message, e.g. for the ``mode'' option:
+\begin{verbatim}
+-m MODE, --mode=MODE
+\end{verbatim}
+
+Here, ``MODE'' is called the meta-variable: it stands for the argument
+that the user is expected to supply to \programopt{-m}/\longprogramopt{mode}.  By default,
+\module{optparse} converts the destination variable name to uppercase and uses
+that for the meta-variable.  Sometimes, that's not what you want{---}for example, the \longprogramopt{filename} option explicitly sets
+\code{metavar="FILE"}, resulting in this automatically-generated option
+description:
+\begin{verbatim}
+-f FILE, --filename=FILE
+\end{verbatim}
+
+This is important for more than just saving space, though: the
+manually written help text uses the meta-variable ``FILE'' to clue the
+user in that there's a connection between the semi-formal syntax ``-f
+FILE'' and the informal semantic description ``write output to FILE''.
+This is a simple but effective way to make your help text a lot
+clearer and more useful for end users.
+
+\item {} 
+options that have a default value can include \code{{\%}default} in
+the help string{---}\module{optparse} will replace it with \function{str()} of the
+option's default value.  If an option has no default value (or the
+default value is \code{None}), \code{{\%}default} expands to \code{none}.
+
+\end{itemize}
+
+
+\subsubsection{Printing a version string\label{optparse-printing-version-string}}
+
+Similar to the brief usage string, \module{optparse} can also print a version string
+for your program.  You have to supply the string as the \code{version}
+argument to OptionParser:
+\begin{verbatim}
+parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
+\end{verbatim}
+
+\code{"{\%}prog"} is expanded just like it is in \code{usage}.  Apart
+from that, \code{version} can contain anything you like.  When you supply
+it, \module{optparse} automatically adds a \code{"-{}-version"} option to your parser.
+If it encounters this option on the command line, it expands your
+\code{version} string (by replacing \code{"{\%}prog"}), prints it to stdout, and
+exits.
+
+For example, if your script is called \code{/usr/bin/foo}:
+\begin{verbatim}
+$ /usr/bin/foo --version
+foo 1.0
+\end{verbatim}
+
+
+\subsubsection{How \module{optparse} handles errors\label{optparse-how-optparse-handles-errors}}
+
+There are two broad classes of errors that \module{optparse} has to worry about:
+programmer errors and user errors.  Programmer errors are usually
+erroneous calls to \code{parser.add{\_}option()}, e.g. invalid option strings,
+unknown option attributes, missing option attributes, etc.  These are
+dealt with in the usual way: raise an exception (either
+\code{optparse.OptionError} or \code{TypeError}) and let the program crash.
+
+Handling user errors is much more important, since they are guaranteed
+to happen no matter how stable your code is.  \module{optparse} can automatically
+detect some user errors, such as bad option arguments (passing \code{"-n
+4x"} where \programopt{-n} takes an integer argument), missing arguments
+(\code{"-n"} at the end of the command line, where \programopt{-n} takes an argument
+of any type).  Also, you can call \code{parser.error()} to signal an
+application-defined error condition:
+\begin{verbatim}
+(options, args) = parser.parse_args()
+[...]
+if options.a and options.b:
+    parser.error("options -a and -b are mutually exclusive")
+\end{verbatim}
+
+In either case, \module{optparse} handles the error the same way: it prints the
+program's usage message and an error message to standard error and
+exits with error status 2.
+
+Consider the first example above, where the user passes \code{"4x"} to an
+option that takes an integer:
+\begin{verbatim}
+$ /usr/bin/foo -n 4x
+usage: foo [options]
+
+foo: error: option -n: invalid integer value: '4x'
+\end{verbatim}
+
+Or, where the user fails to pass a value at all:
+\begin{verbatim}
+$ /usr/bin/foo -n
+usage: foo [options]
+
+foo: error: -n option requires an argument
+\end{verbatim}
+
+\module{optparse}-generated error messages take care always to mention the option
+involved in the error; be sure to do the same when calling
+\code{parser.error()} from your application code.
+
+If \module{optparse}'s default error-handling behaviour does not suite your needs,
+you'll need to subclass OptionParser and override \code{exit()} and/or
+\method{error()}.
+
+
+\subsubsection{Putting it all together\label{optparse-putting-it-all-together}}
+
+Here's what \module{optparse}-based scripts usually look like:
+\begin{verbatim}
+from optparse import OptionParser
+[...]
+def main():
+    usage = "usage: %prog [options] arg"
+    parser = OptionParser(usage)
+    parser.add_option("-f", "--file", dest="filename",
+                      help="read data from FILENAME")
+    parser.add_option("-v", "--verbose",
+                      action="store_true", dest="verbose")
+    parser.add_option("-q", "--quiet",
+                      action="store_false", dest="verbose")
+    [...]
+    (options, args) = parser.parse_args()
+    if len(args) != 1:
+        parser.error("incorrect number of arguments")
+    if options.verbose:
+        print "reading %s..." % options.filename
+    [...]
+
+if __name__ == "__main__":
+    main()
+\end{verbatim}
+% $Id: tutorial.txt 515 2006-06-10 15:37:45Z gward $ 
+
+
+\subsection{Reference Guide\label{optparse-reference-guide}}
+
+
+\subsubsection{Creating the parser\label{optparse-creating-parser}}
+
+The first step in using \module{optparse} is to create an OptionParser instance:
+\begin{verbatim}
+parser = OptionParser(...)
+\end{verbatim}
+
+The OptionParser constructor has no required arguments, but a number of
+optional keyword arguments.  You should always pass them as keyword
+arguments, i.e. do not rely on the order in which the arguments are
+declared.
+\begin{quote}
+\begin{description}
+\item[\code{usage} (default: \code{"{\%}prog {[}options]"})]
+The usage summary to print when your program is run incorrectly or
+with a help option.  When \module{optparse} prints the usage string, it expands
+\code{{\%}prog} to \code{os.path.basename(sys.argv{[}0])} (or to \code{prog} if
+you passed that keyword argument).  To suppress a usage message,
+pass the special value \code{optparse.SUPPRESS{\_}USAGE}.
+\item[\code{option{\_}list} (default: \code{{[}]})]
+A list of Option objects to populate the parser with.  The options
+in \code{option{\_}list} are added after any options in
+\code{standard{\_}option{\_}list} (a class attribute that may be set by
+OptionParser subclasses), but before any version or help options.
+Deprecated; use \method{add{\_}option()} after creating the parser instead.
+\item[\code{option{\_}class} (default: optparse.Option)]
+Class to use when adding options to the parser in \method{add{\_}option()}.
+\item[\code{version} (default: \code{None})]
+A version string to print when the user supplies a version option.
+If you supply a true value for \code{version}, \module{optparse} automatically adds
+a version option with the single option string \code{"-{}-version"}.  The
+substring \code{"{\%}prog"} is expanded the same as for \code{usage}.
+\item[\code{conflict{\_}handler} (default: \code{"error"})]
+Specifies what to do when options with conflicting option strings
+are added to the parser; see section~\ref{optparse-conflicts-between-options}, Conflicts between options.
+\item[\code{description} (default: \code{None})]
+A paragraph of text giving a brief overview of your program.  \module{optparse}
+reformats this paragraph to fit the current terminal width and
+prints it when the user requests help (after \code{usage}, but before
+the list of options).
+\item[\code{formatter} (default: a new IndentedHelpFormatter)]
+An instance of optparse.HelpFormatter that will be used for
+printing help text.  \module{optparse} provides two concrete classes for this
+purpose: IndentedHelpFormatter and TitledHelpFormatter.
+\item[\code{add{\_}help{\_}option} (default: \code{True})]
+If true, \module{optparse} will add a help option (with option strings \code{"-h"}
+and \code{"-{}-help"}) to the parser.
+\item[\code{prog}]
+The string to use when expanding \code{"{\%}prog"} in \code{usage} and
+\code{version} instead of \code{os.path.basename(sys.argv{[}0])}.
+\end{description}
+\end{quote}
+
+
+\subsubsection{Populating the parser\label{optparse-populating-parser}}
+
+There are several ways to populate the parser with options.  The
+preferred way is by using \code{OptionParser.add{\_}option()}, as shown in
+section~\ref{optparse-tutorial}, the tutorial.  \method{add{\_}option()} can be called in one of two
+ways:
+\begin{itemize}
+\item {} 
+pass it an Option instance (as returned by \function{make{\_}option()})
+
+\item {} 
+pass it any combination of positional and keyword arguments that are
+acceptable to \function{make{\_}option()} (i.e., to the Option constructor),
+and it will create the Option instance for you
+
+\end{itemize}
+
+The other alternative is to pass a list of pre-constructed Option
+instances to the OptionParser constructor, as in:
+\begin{verbatim}
+option_list = [
+    make_option("-f", "--filename",
+                action="store", type="string", dest="filename"),
+    make_option("-q", "--quiet",
+                action="store_false", dest="verbose"),
+    ]
+parser = OptionParser(option_list=option_list)
+\end{verbatim}
+
+(\function{make{\_}option()} is a factory function for creating Option instances;
+currently it is an alias for the Option constructor.  A future version
+of \module{optparse} may split Option into several classes, and \function{make{\_}option()}
+will pick the right class to instantiate.  Do not instantiate Option
+directly.)
+
+
+\subsubsection{Defining options\label{optparse-defining-options}}
+
+Each Option instance represents a set of synonymous command-line option
+strings, e.g. \programopt{-f} and \longprogramopt{file}.  You can
+specify any number of short or long option strings, but you must specify
+at least one overall option string.
+
+The canonical way to create an Option instance is with the
+\method{add{\_}option()} method of \class{OptionParser}:
+\begin{verbatim}
+parser.add_option(opt_str[, ...], attr=value, ...)
+\end{verbatim}
+
+To define an option with only a short option string:
+\begin{verbatim}
+parser.add_option("-f", attr=value, ...)
+\end{verbatim}
+
+And to define an option with only a long option string:
+\begin{verbatim}
+parser.add_option("--foo", attr=value, ...)
+\end{verbatim}
+
+The keyword arguments define attributes of the new Option object.  The
+most important option attribute is \member{action}, and it largely determines
+which other attributes are relevant or required.  If you pass irrelevant
+option attributes, or fail to pass required ones, \module{optparse} raises an
+OptionError exception explaining your mistake.
+
+An options's \emph{action} determines what \module{optparse} does when it encounters this
+option on the command-line.  The standard option actions hard-coded into
+\module{optparse} are:
+\begin{description}
+\item[\code{store}]
+store this option's argument (default)
+\item[\code{store{\_}const}]
+store a constant value
+\item[\code{store{\_}true}]
+store a true value
+\item[\code{store{\_}false}]
+store a false value
+\item[\code{append}]
+append this option's argument to a list
+\item[\code{append{\_}const}]
+append a constant value to a list
+\item[\code{count}]
+increment a counter by one
+\item[\code{callback}]
+call a specified function
+\item[\member{help}]
+print a usage message including all options and the
+documentation for them
+\end{description}
+
+(If you don't supply an action, the default is \code{store}.  For this
+action, you may also supply \member{type} and \member{dest} option attributes; see
+below.)
+
+As you can see, most actions involve storing or updating a value
+somewhere.  \module{optparse} always creates a special object for this,
+conventionally called \code{options} (it happens to be an instance of
+\code{optparse.Values}).  Option arguments (and various other values) are
+stored as attributes of this object, according to the \member{dest}
+(destination) option attribute.
+
+For example, when you call
+\begin{verbatim}
+parser.parse_args()
+\end{verbatim}
+
+one of the first things \module{optparse} does is create the \code{options} object:
+\begin{verbatim}
+options = Values()
+\end{verbatim}
+
+If one of the options in this parser is defined with
+\begin{verbatim}
+parser.add_option("-f", "--file", action="store", type="string", dest="filename")
+\end{verbatim}
+
+and the command-line being parsed includes any of the following:
+\begin{verbatim}
+-ffoo
+-f foo
+--file=foo
+--file foo
+\end{verbatim}
+
+then \module{optparse}, on seeing this option, will do the equivalent of
+\begin{verbatim}
+options.filename = "foo"
+\end{verbatim}
+
+The \member{type} and \member{dest} option attributes are almost as important as
+\member{action}, but \member{action} is the only one that makes sense for \emph{all}
+options.
+
+
+\subsubsection{Standard option actions\label{optparse-standard-option-actions}}
+
+The various option actions all have slightly different requirements and
+effects.  Most actions have several relevant option attributes which you
+may specify to guide \module{optparse}'s behaviour; a few have required attributes,
+which you must specify for any option using that action.
+\begin{itemize}
+\item {} 
+\code{store} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]
+
+The option must be followed by an argument, which is
+converted to a value according to \member{type} and stored in
+\member{dest}.  If \code{nargs} {\textgreater} 1, multiple arguments will be consumed
+from the command line; all will be converted according to
+\member{type} and stored to \member{dest} as a tuple.  See the ``Option
+types'' section below.
+
+If \code{choices} is supplied (a list or tuple of strings), the type
+defaults to \code{choice}.
+
+If \member{type} is not supplied, it defaults to \code{string}.
+
+If \member{dest} is not supplied, \module{optparse} derives a destination from the
+first long option string (e.g., \code{"-{}-foo-bar"} implies \code{foo{\_}bar}).
+If there are no long option strings, \module{optparse} derives a destination from
+the first short option string (e.g., \code{"-f"} implies \code{f}).
+
+Example:
+\begin{verbatim}
+parser.add_option("-f")
+parser.add_option("-p", type="float", nargs=3, dest="point")
+\end{verbatim}
+
+As it parses the command line
+\begin{verbatim}
+-f foo.txt -p 1 -3.5 4 -fbar.txt
+\end{verbatim}
+
+\module{optparse} will set
+\begin{verbatim}
+options.f = "foo.txt"
+options.point = (1.0, -3.5, 4.0)
+options.f = "bar.txt"
+\end{verbatim}
+
+\item {} 
+\code{store{\_}const} {[}required: \code{const}; relevant: \member{dest}]
+
+The value \code{const} is stored in \member{dest}.
+
+Example:
+\begin{verbatim}
+parser.add_option("-q", "--quiet",
+                  action="store_const", const=0, dest="verbose")
+parser.add_option("-v", "--verbose",
+                  action="store_const", const=1, dest="verbose")
+parser.add_option("--noisy",
+                  action="store_const", const=2, dest="verbose")
+\end{verbatim}
+
+If \code{"-{}-noisy"} is seen, \module{optparse} will set
+\begin{verbatim}
+options.verbose = 2
+\end{verbatim}
+
+\item {} 
+\code{store{\_}true} {[}relevant: \member{dest}]
+
+A special case of \code{store{\_}const} that stores a true value
+to \member{dest}.
+
+\item {} 
+\code{store{\_}false} {[}relevant: \member{dest}]
+
+Like \code{store{\_}true}, but stores a false value.
+
+Example:
+\begin{verbatim}
+parser.add_option("--clobber", action="store_true", dest="clobber")
+parser.add_option("--no-clobber", action="store_false", dest="clobber")
+\end{verbatim}
+
+\item {} 
+\code{append} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]
+
+The option must be followed by an argument, which is appended to the
+list in \member{dest}.  If no default value for \member{dest} is supplied, an
+empty list is automatically created when \module{optparse} first encounters this
+option on the command-line.  If \code{nargs} {\textgreater} 1, multiple arguments are
+consumed, and a tuple of length \code{nargs} is appended to \member{dest}.
+
+The defaults for \member{type} and \member{dest} are the same as for the
+\code{store} action.
+
+Example:
+\begin{verbatim}
+parser.add_option("-t", "--tracks", action="append", type="int")
+\end{verbatim}
+
+If \code{"-t3"} is seen on the command-line, \module{optparse} does the equivalent of:
+\begin{verbatim}
+options.tracks = []
+options.tracks.append(int("3"))
+\end{verbatim}
+
+If, a little later on, \code{"-{}-tracks=4"} is seen, it does:
+\begin{verbatim}
+options.tracks.append(int("4"))
+\end{verbatim}
+
+\item {} 
+\code{append{\_}const} {[}required: \code{const}; relevant: \member{dest}]
+
+Like \code{store{\_}const}, but the value \code{const} is appended to \member{dest};
+as with \code{append}, \member{dest} defaults to \code{None}, and an an empty list is
+automatically created the first time the option is encountered.
+
+\item {} 
+\code{count} {[}relevant: \member{dest}]
+
+Increment the integer stored at \member{dest}.  If no default value is
+supplied, \member{dest} is set to zero before being incremented the first
+time.
+
+Example:
+\begin{verbatim}
+parser.add_option("-v", action="count", dest="verbosity")
+\end{verbatim}
+
+The first time \code{"-v"} is seen on the command line, \module{optparse} does the
+equivalent of:
+\begin{verbatim}
+options.verbosity = 0
+options.verbosity += 1
+\end{verbatim}
+
+Every subsequent occurrence of \code{"-v"} results in
+\begin{verbatim}
+options.verbosity += 1
+\end{verbatim}
+
+\item {} 
+\code{callback} {[}required: \code{callback};
+relevant: \member{type}, \code{nargs}, \code{callback{\_}args}, \code{callback{\_}kwargs}]
+
+Call the function specified by \code{callback}, which is called as
+\begin{verbatim}
+func(option, opt_str, value, parser, *args, **kwargs)
+\end{verbatim}
+
+See section~\ref{optparse-option-callbacks}, Option Callbacks for more detail.
+
+\item {} 
+\member{help}
+
+Prints a complete help message for all the options in the
+current option parser.  The help message is constructed from
+the \code{usage} string passed to OptionParser's constructor and
+the \member{help} string passed to every option.
+
+If no \member{help} string is supplied for an option, it will still be
+listed in the help message.  To omit an option entirely, use
+the special value \code{optparse.SUPPRESS{\_}HELP}.
+
+\module{optparse} automatically adds a \member{help} option to all OptionParsers, so
+you do not normally need to create one.
+
+Example:
+\begin{verbatim}
+from optparse import OptionParser, SUPPRESS_HELP
+
+parser = OptionParser()
+parser.add_option("-h", "--help", action="help"),
+parser.add_option("-v", action="store_true", dest="verbose",
+                  help="Be moderately verbose")
+parser.add_option("--file", dest="filename",
+                  help="Input file to read data from"),
+parser.add_option("--secret", help=SUPPRESS_HELP)
+\end{verbatim}
+
+If \module{optparse} sees either \code{"-h"} or \code{"-{}-help"} on the command line, it
+will print something like the following help message to stdout
+(assuming \code{sys.argv{[}0]} is \code{"foo.py"}):
+\begin{verbatim}
+usage: foo.py [options]
+
+options:
+  -h, --help        Show this help message and exit
+  -v                Be moderately verbose
+  --file=FILENAME   Input file to read data from
+\end{verbatim}
+
+After printing the help message, \module{optparse} terminates your process
+with \code{sys.exit(0)}.
+
+\item {} 
+\code{version}
+
+Prints the version number supplied to the OptionParser to stdout and
+exits.  The version number is actually formatted and printed by the
+\code{print{\_}version()} method of OptionParser.  Generally only relevant
+if the \code{version} argument is supplied to the OptionParser
+constructor.  As with \member{help} options, you will rarely create
+\code{version} options, since \module{optparse} automatically adds them when needed.
+
+\end{itemize}
+
+
+\subsubsection{Option attributes\label{optparse-option-attributes}}
+
+The following option attributes may be passed as keyword arguments
+to \code{parser.add{\_}option()}.  If you pass an option attribute
+that is not relevant to a particular option, or fail to pass a required
+option attribute, \module{optparse} raises OptionError.
+\begin{itemize}
+\item {} 
+\member{action} (default: \code{"store"})
+
+Determines \module{optparse}'s behaviour when this option is seen on the command
+line; the available options are documented above.
+
+\item {} 
+\member{type} (default: \code{"string"})
+
+The argument type expected by this option (e.g., \code{"string"} or
+\code{"int"}); the available option types are documented below.
+
+\item {} 
+\member{dest} (default: derived from option strings)
+
+If the option's action implies writing or modifying a value somewhere,
+this tells \module{optparse} where to write it: \member{dest} names an attribute of the
+\code{options} object that \module{optparse} builds as it parses the command line.
+
+\item {} 
+\code{default} (deprecated)
+
+The value to use for this option's destination if the option is not
+seen on the command line.  Deprecated; use \code{parser.set{\_}defaults()}
+instead.
+
+\item {} 
+\code{nargs} (default: 1)
+
+How many arguments of type \member{type} should be consumed when this
+option is seen.  If {\textgreater} 1, \module{optparse} will store a tuple of values to
+\member{dest}.
+
+\item {} 
+\code{const}
+
+For actions that store a constant value, the constant value to store.
+
+\item {} 
+\code{choices}
+
+For options of type \code{"choice"}, the list of strings the user
+may choose from.
+
+\item {} 
+\code{callback}
+
+For options with action \code{"callback"}, the callable to call when this
+option is seen.  See section~\ref{optparse-option-callbacks}, Option Callbacks for detail on the arguments
+passed to \code{callable}.
+
+\item {} 
+\code{callback{\_}args}, \code{callback{\_}kwargs}
+
+Additional positional and keyword arguments to pass to \code{callback}
+after the four standard callback arguments.
+
+\item {} 
+\member{help}
+
+Help text to print for this option when listing all available options
+after the user supplies a \member{help} option (such as \code{"-{}-help"}).
+If no help text is supplied, the option will be listed without help
+text.  To hide this option, use the special value \code{SUPPRESS{\_}HELP}.
+
+\item {} 
+\code{metavar} (default: derived from option strings)
+
+Stand-in for the option argument(s) to use when printing help text.
+See section~\ref{optparse-tutorial}, the tutorial for an example.
+
+\end{itemize}
+
+
+\subsubsection{Standard option types\label{optparse-standard-option-types}}
+
+\module{optparse} has six built-in option types: \code{string}, \code{int}, \code{long},
+\code{choice}, \code{float} and \code{complex}.  If you need to add new option
+types, see section~\ref{optparse-extending-optparse}, Extending \module{optparse}.
+
+Arguments to string options are not checked or converted in any way: the
+text on the command line is stored in the destination (or passed to the
+callback) as-is.
+
+Integer arguments (type \code{int} or \code{long}) are parsed as follows:
+\begin{quote}
+\begin{itemize}
+\item {} 
+if the number starts with \code{0x}, it is parsed as a hexadecimal number
+
+\item {} 
+if the number starts with \code{0}, it is parsed as an octal number
+
+\item {} 
+if the number starts with \code{0b}, is is parsed as a binary number
+
+\item {} 
+otherwise, the number is parsed as a decimal number
+
+\end{itemize}
+\end{quote}
+
+The conversion is done by calling either \code{int()} or \code{long()} with
+the appropriate base (2, 8, 10, or 16).  If this fails, so will \module{optparse},
+although with a more useful error message.
+
+\code{float} and \code{complex} option arguments are converted directly with
+\code{float()} and \code{complex()}, with similar error-handling.
+
+\code{choice} options are a subtype of \code{string} options.  The \code{choices}
+option attribute (a sequence of strings) defines the set of allowed
+option arguments.  \code{optparse.check{\_}choice()} compares
+user-supplied option arguments against this master list and raises
+OptionValueError if an invalid string is given.
+
+
+\subsubsection{Parsing arguments\label{optparse-parsing-arguments}}
+
+The whole point of creating and populating an OptionParser is to call
+its \method{parse{\_}args()} method:
+\begin{verbatim}
+(options, args) = parser.parse_args(args=None, options=None)
+\end{verbatim}
+
+where the input parameters are
+\begin{description}
+\item[\code{args}]
+the list of arguments to process (default: \code{sys.argv{[}1:]})
+\item[\code{options}]
+object to store option arguments in (default: a new instance of
+optparse.Values)
+\end{description}
+
+and the return values are
+\begin{description}
+\item[\code{options}]
+the same object that was passed in as \code{options}, or the
+optparse.Values instance created by \module{optparse}
+\item[\code{args}]
+the leftover positional arguments after all options have been
+processed
+\end{description}
+
+The most common usage is to supply neither keyword argument.  If you
+supply \code{options}, it will be modified with repeated \code{setattr()}
+calls (roughly one for every option argument stored to an option
+destination) and returned by \method{parse{\_}args()}.
+
+If \method{parse{\_}args()} encounters any errors in the argument list, it calls
+the OptionParser's \method{error()} method with an appropriate end-user error
+message.  This ultimately terminates your process with an exit status of
+2 (the traditional \UNIX{} exit status for command-line errors).
+
+
+\subsubsection{Querying and manipulating your option parser\label{optparse-querying-manipulating-option-parser}}
+
+Sometimes, it's useful to poke around your option parser and see what's
+there.  OptionParser provides a couple of methods to help you out:
+\begin{description}
+\item[\code{has{\_}option(opt{\_}str)}]
+Return true if the OptionParser has an option with 
+option string \code{opt{\_}str} (e.g., \code{"-q"} or \code{"-{}-verbose"}).
+\item[\code{get{\_}option(opt{\_}str)}]
+Returns the Option instance with the option string \code{opt{\_}str}, or
+\code{None} if no options have that option string.
+\item[\code{remove{\_}option(opt{\_}str)}]
+If the OptionParser has an option corresponding to \code{opt{\_}str},
+that option is removed.  If that option provided any other
+option strings, all of those option strings become invalid.
+If \code{opt{\_}str} does not occur in any option belonging to this
+OptionParser, raises ValueError.
+\end{description}
+
+
+\subsubsection{Conflicts between options\label{optparse-conflicts-between-options}}
+
+If you're not careful, it's easy to define options with conflicting
+option strings:
+\begin{verbatim}
+parser.add_option("-n", "--dry-run", ...)
+[...]
+parser.add_option("-n", "--noisy", ...)
+\end{verbatim}
+
+(This is particularly true if you've defined your own OptionParser
+subclass with some standard options.)
+
+Every time you add an option, \module{optparse} checks for conflicts with existing
+options.  If it finds any, it invokes the current conflict-handling
+mechanism.  You can set the conflict-handling mechanism either in the
+constructor:
+\begin{verbatim}
+parser = OptionParser(..., conflict_handler=handler)
+\end{verbatim}
+
+or with a separate call:
+\begin{verbatim}
+parser.set_conflict_handler(handler)
+\end{verbatim}
+
+The available conflict handlers are:
+\begin{quote}
+\begin{description}
+\item[\code{error} (default)]
+assume option conflicts are a programming error and raise 
+OptionConflictError
+\item[\code{resolve}]
+resolve option conflicts intelligently (see below)
+\end{description}
+\end{quote}
+
+As an example, let's define an OptionParser that resolves conflicts
+intelligently and add conflicting options to it:
+\begin{verbatim}
+parser = OptionParser(conflict_handler="resolve")
+parser.add_option("-n", "--dry-run", ..., help="do no harm")
+parser.add_option("-n", "--noisy", ..., help="be noisy")
+\end{verbatim}
+
+At this point, \module{optparse} detects that a previously-added option is already
+using the \code{"-n"} option string.  Since \code{conflict{\_}handler} is
+\code{"resolve"}, it resolves the situation by removing \code{"-n"} from the
+earlier option's list of option strings.  Now \code{"-{}-dry-run"} is the
+only way for the user to activate that option.  If the user asks for
+help, the help message will reflect that:
+\begin{verbatim}
+options:
+  --dry-run     do no harm
+  [...]
+  -n, --noisy   be noisy
+\end{verbatim}
+
+It's possible to whittle away the option strings for a previously-added
+option until there are none left, and the user has no way of invoking
+that option from the command-line.  In that case, \module{optparse} removes that
+option completely, so it doesn't show up in help text or anywhere else.
+Carrying on with our existing OptionParser:
+\begin{verbatim}
+parser.add_option("--dry-run", ..., help="new dry-run option")
+\end{verbatim}
+
+At this point, the original \programopt{-n/-{}-dry-run} option is no longer
+accessible, so \module{optparse} removes it, leaving this help text:
+\begin{verbatim}
+options:
+  [...]
+  -n, --noisy   be noisy
+  --dry-run     new dry-run option
+\end{verbatim}
+
+
+\subsubsection{Cleanup\label{optparse-cleanup}}
+
+OptionParser instances have several cyclic references.  This should not
+be a problem for Python's garbage collector, but you may wish to break
+the cyclic references explicitly by calling \code{destroy()} on your
+OptionParser once you are done with it.  This is particularly useful in
+long-running applications where large object graphs are reachable from
+your OptionParser.
+
+
+\subsubsection{Other methods\label{optparse-other-methods}}
+
+OptionParser supports several other public methods:
+\begin{itemize}
+\item {} 
+\code{set{\_}usage(usage)}
+
+Set the usage string according to the rules described above for the
+\code{usage} constructor keyword argument.  Passing \code{None} sets the
+default usage string; use \code{SUPPRESS{\_}USAGE} to suppress a usage
+message.
+
+\item {} 
+\code{enable{\_}interspersed{\_}args()}, \code{disable{\_}interspersed{\_}args()}
+
+Enable/disable positional arguments interspersed with options, similar
+to GNU getopt (enabled by default).  For example, if \code{"-a"} and
+\code{"-b"} are both simple options that take no arguments, \module{optparse}
+normally accepts this syntax:
+\begin{verbatim}
+prog -a arg1 -b arg2
+\end{verbatim}
+
+and treats it as equivalent to
+\begin{verbatim}
+prog -a -b arg1 arg2
+\end{verbatim}
+
+To disable this feature, call \code{disable{\_}interspersed{\_}args()}.  This
+restores traditional \UNIX{} syntax, where option parsing stops with the
+first non-option argument.
+
+\item {} 
+\code{set{\_}defaults(dest=value, ...)}
+
+Set default values for several option destinations at once.  Using
+\method{set{\_}defaults()} is the preferred way to set default values for
+options, since multiple options can share the same destination.  For
+example, if several ``mode'' options all set the same destination, any
+one of them can set the default, and the last one wins:
+\begin{verbatim}
+parser.add_option("--advanced", action="store_const",
+                  dest="mode", const="advanced",
+                  default="novice")    # overridden below
+parser.add_option("--novice", action="store_const",
+                  dest="mode", const="novice",
+                  default="advanced")  # overrides above setting
+\end{verbatim}
+
+To avoid this confusion, use \method{set{\_}defaults()}:
+\begin{verbatim}
+parser.set_defaults(mode="advanced")
+parser.add_option("--advanced", action="store_const",
+                  dest="mode", const="advanced")
+parser.add_option("--novice", action="store_const",
+                  dest="mode", const="novice")
+\end{verbatim}
+
+\end{itemize}
+% $Id: reference.txt 519 2006-06-11 14:39:11Z gward $ 
+
+
+\subsection{Option Callbacks\label{optparse-option-callbacks}}
+
+When \module{optparse}'s built-in actions and types aren't quite enough for your
+needs, you have two choices: extend \module{optparse} or define a callback option.
+Extending \module{optparse} is more general, but overkill for a lot of simple
+cases.  Quite often a simple callback is all you need.
+
+There are two steps to defining a callback option:
+\begin{itemize}
+\item {} 
+define the option itself using the \code{callback} action
+
+\item {} 
+write the callback; this is a function (or method) that
+takes at least four arguments, as described below
+
+\end{itemize}
+
+
+\subsubsection{Defining a callback option\label{optparse-defining-callback-option}}
+
+As always, the easiest way to define a callback option is by using the
+\code{parser.add{\_}option()} method.  Apart from \member{action}, the only option
+attribute you must specify is \code{callback}, the function to call:
+\begin{verbatim}
+parser.add_option("-c", action="callback", callback=my_callback)
+\end{verbatim}
+
+\code{callback} is a function (or other callable object), so you must have
+already defined \code{my{\_}callback()} when you create this callback option.
+In this simple case, \module{optparse} doesn't even know if \programopt{-c} takes any
+arguments, which usually means that the option takes no arguments{---}the
+mere presence of \programopt{-c} on the command-line is all it needs to know.  In
+some circumstances, though, you might want your callback to consume an
+arbitrary number of command-line arguments.  This is where writing
+callbacks gets tricky; it's covered later in this section.
+
+\module{optparse} always passes four particular arguments to your callback, and it
+will only pass additional arguments if you specify them via
+\code{callback{\_}args} and \code{callback{\_}kwargs}.  Thus, the minimal callback
+function signature is:
+\begin{verbatim}
+def my_callback(option, opt, value, parser):
+\end{verbatim}
+
+The four arguments to a callback are described below.
+
+There are several other option attributes that you can supply when you
+define a callback option:
+\begin{description}
+\item[\member{type}]
+has its usual meaning: as with the \code{store} or \code{append} actions,
+it instructs \module{optparse} to consume one argument and convert it to
+\member{type}.  Rather than storing the converted value(s) anywhere,
+though, \module{optparse} passes it to your callback function.
+\item[\code{nargs}]
+also has its usual meaning: if it is supplied and {\textgreater} 1, \module{optparse} will
+consume \code{nargs} arguments, each of which must be convertible to
+\member{type}.  It then passes a tuple of converted values to your
+callback.
+\item[\code{callback{\_}args}]
+a tuple of extra positional arguments to pass to the callback
+\item[\code{callback{\_}kwargs}]
+a dictionary of extra keyword arguments to pass to the callback
+\end{description}
+
+
+\subsubsection{How callbacks are called\label{optparse-how-callbacks-called}}
+
+All callbacks are called as follows:
+\begin{verbatim}
+func(option, opt_str, value, parser, *args, **kwargs)
+\end{verbatim}
+
+where
+\begin{description}
+\item[\code{option}]
+is the Option instance that's calling the callback
+\item[\code{opt{\_}str}]
+is the option string seen on the command-line that's triggering the
+callback.  (If an abbreviated long option was used, \code{opt{\_}str} will
+be the full, canonical option string{---}e.g. if the user puts
+\code{"-{}-foo"} on the command-line as an abbreviation for
+\code{"-{}-foobar"}, then \code{opt{\_}str} will be \code{"-{}-foobar"}.)
+\item[\code{value}]
+is the argument to this option seen on the command-line.  \module{optparse} will
+only expect an argument if \member{type} is set; the type of \code{value}
+will be the type implied by the option's type.  If \member{type} for this
+option is \code{None} (no argument expected), then \code{value} will be
+\code{None}.  If \code{nargs} {\textgreater} 1, \code{value} will be a tuple of values of
+the appropriate type.
+\item[\code{parser}]
+is the OptionParser instance driving the whole thing, mainly
+useful because you can access some other interesting data through
+its instance attributes:
+\begin{description}
+\item[\code{parser.largs}]
+the current list of leftover arguments, ie. arguments that have
+been consumed but are neither options nor option arguments.
+Feel free to modify \code{parser.largs}, e.g. by adding more
+arguments to it.  (This list will become \code{args}, the second
+return value of \method{parse{\_}args()}.)
+\item[\code{parser.rargs}]
+the current list of remaining arguments, ie. with \code{opt{\_}str} and
+\code{value} (if applicable) removed, and only the arguments
+following them still there.  Feel free to modify
+\code{parser.rargs}, e.g. by consuming more arguments.
+\item[\code{parser.values}]
+the object where option values are by default stored (an
+instance of optparse.OptionValues).  This lets callbacks use the
+same mechanism as the rest of \module{optparse} for storing option values;
+you don't need to mess around with globals or closures.  You can
+also access or modify the value(s) of any options already
+encountered on the command-line.
+\end{description}
+\item[\code{args}]
+is a tuple of arbitrary positional arguments supplied via the
+\code{callback{\_}args} option attribute.
+\item[\code{kwargs}]
+is a dictionary of arbitrary keyword arguments supplied via
+\code{callback{\_}kwargs}.
+\end{description}
+
+
+\subsubsection{Raising errors in a callback\label{optparse-raising-errors-in-callback}}
+
+The callback function should raise OptionValueError if there are any
+problems with the option or its argument(s).  \module{optparse} catches this and
+terminates the program, printing the error message you supply to
+stderr.  Your message should be clear, concise, accurate, and mention
+the option at fault.  Otherwise, the user will have a hard time
+figuring out what he did wrong.
+
+
+\subsubsection{Callback example 1: trivial callback\label{optparse-callback-example-1}}
+
+Here's an example of a callback option that takes no arguments, and
+simply records that the option was seen:
+\begin{verbatim}
+def record_foo_seen(option, opt_str, value, parser):
+    parser.saw_foo = True
+
+parser.add_option("--foo", action="callback", callback=record_foo_seen)
+\end{verbatim}
+
+Of course, you could do that with the \code{store{\_}true} action.
+
+
+\subsubsection{Callback example 2: check option order\label{optparse-callback-example-2}}
+
+Here's a slightly more interesting example: record the fact that
+\code{"-a"} is seen, but blow up if it comes after \code{"-b"} in the
+command-line.
+\begin{verbatim}
+def check_order(option, opt_str, value, parser):
+    if parser.values.b:
+        raise OptionValueError("can't use -a after -b")
+    parser.values.a = 1
+[...]
+parser.add_option("-a", action="callback", callback=check_order)
+parser.add_option("-b", action="store_true", dest="b")
+\end{verbatim}
+
+
+\subsubsection{Callback example 3: check option order (generalized)\label{optparse-callback-example-3}}
+
+If you want to re-use this callback for several similar options (set a
+flag, but blow up if \code{"-b"} has already been seen), it needs a bit of
+work: the error message and the flag that it sets must be
+generalized.
+\begin{verbatim}
+def check_order(option, opt_str, value, parser):
+    if parser.values.b:
+        raise OptionValueError("can't use %s after -b" % opt_str)
+    setattr(parser.values, option.dest, 1)
+[...]
+parser.add_option("-a", action="callback", callback=check_order, dest='a')
+parser.add_option("-b", action="store_true", dest="b")
+parser.add_option("-c", action="callback", callback=check_order, dest='c')
+\end{verbatim}
+
+
+\subsubsection{Callback example 4: check arbitrary condition\label{optparse-callback-example-4}}
+
+Of course, you could put any condition in there{---}you're not limited
+to checking the values of already-defined options.  For example, if
+you have options that should not be called when the moon is full, all
+you have to do is this:
+\begin{verbatim}
+def check_moon(option, opt_str, value, parser):
+    if is_moon_full():
+        raise OptionValueError("%s option invalid when moon is full"
+                               % opt_str)
+    setattr(parser.values, option.dest, 1)
+[...]
+parser.add_option("--foo",
+                  action="callback", callback=check_moon, dest="foo")
+\end{verbatim}
+
+(The definition of \code{is{\_}moon{\_}full()} is left as an exercise for the
+reader.)
+
+
+\subsubsection{Callback example 5: fixed arguments\label{optparse-callback-example-5}}
+
+Things get slightly more interesting when you define callback options
+that take a fixed number of arguments.  Specifying that a callback
+option takes arguments is similar to defining a \code{store} or \code{append}
+option: if you define \member{type}, then the option takes one argument that
+must be convertible to that type; if you further define \code{nargs}, then
+the option takes \code{nargs} arguments.
+
+Here's an example that just emulates the standard \code{store} action:
+\begin{verbatim}
+def store_value(option, opt_str, value, parser):
+    setattr(parser.values, option.dest, value)
+[...]
+parser.add_option("--foo",
+                  action="callback", callback=store_value,
+                  type="int", nargs=3, dest="foo")
+\end{verbatim}
+
+Note that \module{optparse} takes care of consuming 3 arguments and converting them
+to integers for you; all you have to do is store them.  (Or whatever;
+obviously you don't need a callback for this example.)
+
+
+\subsubsection{Callback example 6: variable arguments\label{optparse-callback-example-6}}
+
+Things get hairy when you want an option to take a variable number of
+arguments.  For this case, you must write a callback, as \module{optparse} doesn't
+provide any built-in capabilities for it.  And you have to deal with
+certain intricacies of conventional \UNIX{} command-line parsing that \module{optparse}
+normally handles for you.  In particular, callbacks should implement
+the conventional rules for bare \code{"-{}-"} and \code{"-"} arguments:
+\begin{itemize}
+\item {} 
+either \code{"-{}-"} or \code{"-"} can be option arguments
+
+\item {} 
+bare \code{"-{}-"} (if not the argument to some option): halt command-line
+processing and discard the \code{"-{}-"}
+
+\item {} 
+bare \code{"-"} (if not the argument to some option): halt command-line
+processing but keep the \code{"-"} (append it to \code{parser.largs})
+
+\end{itemize}
+
+If you want an option that takes a variable number of arguments, there
+are several subtle, tricky issues to worry about.  The exact
+implementation you choose will be based on which trade-offs you're
+willing to make for your application (which is why \module{optparse} doesn't support
+this sort of thing directly).
+
+Nevertheless, here's a stab at a callback for an option with variable
+arguments:
+\begin{verbatim}
+def vararg_callback(option, opt_str, value, parser):
+    assert value is None
+    done = 0
+    value = []
+    rargs = parser.rargs
+    while rargs:
+        arg = rargs[0]
+
+        # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f",
+        # etc.  Note that this also stops on "-3" or "-3.0", so if
+        # your option takes numeric values, you will need to handle
+        # this.
+        if ((arg[:2] == "--" and len(arg) > 2) or
+            (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")):
+            break
+        else:
+            value.append(arg)
+            del rargs[0]
+
+     setattr(parser.values, option.dest, value)
+
+[...]
+parser.add_option("-c", "--callback",
+                  action="callback", callback=varargs)
+\end{verbatim}
+
+The main weakness with this particular implementation is that negative
+numbers in the arguments following \code{"-c"} will be interpreted as
+further options (probably causing an error), rather than as arguments to
+\code{"-c"}.  Fixing this is left as an exercise for the reader.
+% $Id: callbacks.txt 415 2004-09-30 02:26:17Z greg $ 
+
+
+\subsection{Extending \module{optparse}\label{optparse-extending-optparse}}
+
+Since the two major controlling factors in how \module{optparse} interprets
+command-line options are the action and type of each option, the most
+likely direction of extension is to add new actions and new types.
+
+
+\subsubsection{Adding new types\label{optparse-adding-new-types}}
+
+To add new types, you need to define your own subclass of \module{optparse}'s Option
+class.  This class has a couple of attributes that define \module{optparse}'s types:
+\member{TYPES} and \member{TYPE{\_}CHECKER}.
+
+\member{TYPES} is a tuple of type names; in your subclass, simply define a new
+tuple \member{TYPES} that builds on the standard one.
+
+\member{TYPE{\_}CHECKER} is a dictionary mapping type names to type-checking
+functions.  A type-checking function has the following signature:
+\begin{verbatim}
+def check_mytype(option, opt, value)
+\end{verbatim}
+
+where \code{option} is an \class{Option} instance, \code{opt} is an option string
+(e.g., \code{"-f"}), and \code{value} is the string from the command line that
+must be checked and converted to your desired type.  \code{check{\_}mytype()}
+should return an object of the hypothetical type \code{mytype}.  The value
+returned by a type-checking function will wind up in the OptionValues
+instance returned by \method{OptionParser.parse{\_}args()}, or be passed to a
+callback as the \code{value} parameter.
+
+Your type-checking function should raise OptionValueError if it
+encounters any problems.  OptionValueError takes a single string
+argument, which is passed as-is to OptionParser's \method{error()} method,
+which in turn prepends the program name and the string \code{"error:"} and
+prints everything to stderr before terminating the process.
+
+Here's a silly example that demonstrates adding a \code{complex} option
+type to parse Python-style complex numbers on the command line.  (This
+is even sillier than it used to be, because \module{optparse} 1.3 added built-in
+support for complex numbers, but never mind.)
+
+First, the necessary imports:
+\begin{verbatim}
+from copy import copy
+from optparse import Option, OptionValueError
+\end{verbatim}
+
+You need to define your type-checker first, since it's referred to later
+(in the \member{TYPE{\_}CHECKER} class attribute of your Option subclass):
+\begin{verbatim}
+def check_complex(option, opt, value):
+    try:
+        return complex(value)
+    except ValueError:
+        raise OptionValueError(
+            "option %s: invalid complex value: %r" % (opt, value))
+\end{verbatim}
+
+Finally, the Option subclass:
+\begin{verbatim}
+class MyOption (Option):
+    TYPES = Option.TYPES + ("complex",)
+    TYPE_CHECKER = copy(Option.TYPE_CHECKER)
+    TYPE_CHECKER["complex"] = check_complex
+\end{verbatim}
+
+(If we didn't make a \function{copy()} of \member{Option.TYPE{\_}CHECKER}, we would end
+up modifying the \member{TYPE{\_}CHECKER} attribute of \module{optparse}'s Option class.
+This being Python, nothing stops you from doing that except good manners
+and common sense.)
+
+That's it!  Now you can write a script that uses the new option type
+just like any other \module{optparse}-based script, except you have to instruct your
+OptionParser to use MyOption instead of Option:
+\begin{verbatim}
+parser = OptionParser(option_class=MyOption)
+parser.add_option("-c", type="complex")
+\end{verbatim}
+
+Alternately, you can build your own option list and pass it to
+OptionParser; if you don't use \method{add{\_}option()} in the above way, you
+don't need to tell OptionParser which option class to use:
+\begin{verbatim}
+option_list = [MyOption("-c", action="store", type="complex", dest="c")]
+parser = OptionParser(option_list=option_list)
+\end{verbatim}
+
+
+\subsubsection{Adding new actions\label{optparse-adding-new-actions}}
+
+Adding new actions is a bit trickier, because you have to understand
+that \module{optparse} has a couple of classifications for actions:
+\begin{description}
+\item[``store'' actions]
+actions that result in \module{optparse} storing a value to an attribute of the
+current OptionValues instance; these options require a \member{dest}
+attribute to be supplied to the Option constructor
+\item[``typed'' actions]
+actions that take a value from the command line and expect it to be
+of a certain type; or rather, a string that can be converted to a
+certain type.  These options require a \member{type} attribute to the
+Option constructor.
+\end{description}
+
+These are overlapping sets: some default ``store'' actions are \code{store},
+\code{store{\_}const}, \code{append}, and \code{count}, while the default ``typed''
+actions are \code{store}, \code{append}, and \code{callback}.
+
+When you add an action, you need to categorize it by listing it in at
+least one of the following class attributes of Option (all are lists of
+strings):
+\begin{description}
+\item[\member{ACTIONS}]
+all actions must be listed in ACTIONS
+\item[\member{STORE{\_}ACTIONS}]
+``store'' actions are additionally listed here
+\item[\member{TYPED{\_}ACTIONS}]
+``typed'' actions are additionally listed here
+\item[\code{ALWAYS{\_}TYPED{\_}ACTIONS}]
+actions that always take a type (i.e. whose options always take a
+value) are additionally listed here.  The only effect of this is
+that \module{optparse} assigns the default type, \code{string}, to options with no
+explicit type whose action is listed in \code{ALWAYS{\_}TYPED{\_}ACTIONS}.
+\end{description}
+
+In order to actually implement your new action, you must override
+Option's \method{take{\_}action()} method and add a case that recognizes your
+action.
+
+For example, let's add an \code{extend} action.  This is similar to the
+standard \code{append} action, but instead of taking a single value from
+the command-line and appending it to an existing list, \code{extend} will
+take multiple values in a single comma-delimited string, and extend an
+existing list with them.  That is, if \code{"-{}-names"} is an \code{extend}
+option of type \code{string}, the command line
+\begin{verbatim}
+--names=foo,bar --names blah --names ding,dong
+\end{verbatim}
+
+would result in a list
+\begin{verbatim}
+["foo", "bar", "blah", "ding", "dong"]
+\end{verbatim}
+
+Again we define a subclass of Option:
+\begin{verbatim}
+class MyOption (Option):
+
+    ACTIONS = Option.ACTIONS + ("extend",)
+    STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
+    TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
+    ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)
+
+    def take_action(self, action, dest, opt, value, values, parser):
+        if action == "extend":
+            lvalue = value.split(",")
+            values.ensure_value(dest, []).extend(lvalue)
+        else:
+            Option.take_action(
+                self, action, dest, opt, value, values, parser)
+\end{verbatim}
+
+Features of note:
+\begin{itemize}
+\item {} 
+\code{extend} both expects a value on the command-line and stores that
+value somewhere, so it goes in both \member{STORE{\_}ACTIONS} and
+\member{TYPED{\_}ACTIONS}
+
+\item {} 
+to ensure that \module{optparse} assigns the default type of \code{string} to
+\code{extend} actions, we put the \code{extend} action in
+\code{ALWAYS{\_}TYPED{\_}ACTIONS} as well
+
+\item {} 
+\method{MyOption.take{\_}action()} implements just this one new action, and
+passes control back to \method{Option.take{\_}action()} for the standard
+\module{optparse} actions
+
+\item {} 
+\code{values} is an instance of the optparse{\_}parser.Values class,
+which provides the very useful \method{ensure{\_}value()} method.
+\method{ensure{\_}value()} is essentially \function{getattr()} with a safety valve;
+it is called as
+\begin{verbatim}
+values.ensure_value(attr, value)
+\end{verbatim}
+
+If the \code{attr} attribute of \code{values} doesn't exist or is None, then
+ensure{\_}value() first sets it to \code{value}, and then returns 'value.
+This is very handy for actions like \code{extend}, \code{append}, and
+\code{count}, all of which accumulate data in a variable and expect that
+variable to be of a certain type (a list for the first two, an integer
+for the latter).  Using \method{ensure{\_}value()} means that scripts using
+your action don't have to worry about setting a default value for the
+option destinations in question; they can just leave the default as
+None and \method{ensure{\_}value()} will take care of getting it right when
+it's needed.
+
+\end{itemize}
+% $Id: extending.txt 517 2006-06-10 16:18:11Z gward $ 
+