mirror of
https://github.com/python/cpython.git
synced 2024-11-30 18:51:15 +01:00
92 lines
3.5 KiB
TeX
92 lines
3.5 KiB
TeX
\section{\module{getopt} ---
|
|
Parser for command line options.}
|
|
\declaremodule{standard}{getopt}
|
|
|
|
\modulesynopsis{Parser for command line options.}
|
|
|
|
|
|
This module helps scripts to parse the command line arguments in
|
|
\code{sys.argv}.
|
|
It supports the same conventions as the \UNIX{} \cfunction{getopt()}
|
|
function (including the special meanings of arguments of the form
|
|
`\code{-}' and `\code{-}\code{-}').
|
|
% That's to fool latex2html into leaving the two hyphens alone!
|
|
Long options similar to those supported by
|
|
GNU software may be used as well via an optional third argument.
|
|
This module provides a single function and an exception:
|
|
|
|
\begin{funcdesc}{getopt}{args, options\optional{, long_options}}
|
|
Parses command line options and parameter list. \var{args} is the
|
|
argument list to be parsed, without the leading reference to the
|
|
running program. Typically, this means \samp{sys.argv[1:]}.
|
|
\var{options} is the string of option letters that the script wants to
|
|
recognize, with options that require an argument followed by a colon
|
|
(i.e., the same format that \UNIX{} \cfunction{getopt()} uses). If
|
|
specified, \var{long_options} is a list of strings with the names of
|
|
the long options which should be supported. The leading
|
|
\code{'-}\code{-'} characters should not be included in the option
|
|
name. Options which require an argument should be followed by an
|
|
equal sign (\code{'='}).
|
|
|
|
The return value consists of two elements: the first is a list of
|
|
\code{(\var{option}, \var{value})} pairs; the second is the list of
|
|
program arguments left after the option list was stripped (this is a
|
|
trailing slice of the first argument).
|
|
Each option-and-value pair returned has the option as its first
|
|
element, prefixed with a hyphen for short options (e.g., \code{'-x'})
|
|
or two hyphens for long options (e.g., \code{'-}\code{-long-option'}),
|
|
and the option argument as its second element, or an empty string if
|
|
the option has no argument.
|
|
The options occur in the list in the same order in which they were
|
|
found, thus allowing multiple occurrences. Long and short options may
|
|
be mixed.
|
|
\end{funcdesc}
|
|
|
|
\begin{excdesc}{GetoptError}
|
|
This is raised when an unrecognized option is found in the argument
|
|
list or when an option requiring an argument is given none.
|
|
The argument to the exception is a string indicating the cause of the
|
|
error. For long options, an argument given to an option which does
|
|
not require one will also cause this exception to be raised. The
|
|
attributes \member{msg} and \member{opt} give the error message and
|
|
related option; if there is no specific option to which the exception
|
|
relates, \member{opt} is an empty string.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{error}
|
|
Alias for \exception{GetoptError}; for backward compatibility.
|
|
\end{excdesc}
|
|
|
|
|
|
An example using only \UNIX{} style options:
|
|
|
|
\begin{verbatim}
|
|
>>> import getopt, string
|
|
>>> args = string.split('-a -b -cfoo -d bar a1 a2')
|
|
>>> args
|
|
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
|
|
>>> optlist, args = getopt.getopt(args, 'abc:d:')
|
|
>>> optlist
|
|
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
|
|
>>> args
|
|
['a1', 'a2']
|
|
>>>
|
|
\end{verbatim}
|
|
|
|
Using long option names is equally easy:
|
|
|
|
\begin{verbatim}
|
|
>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
|
|
>>> args = string.split(s)
|
|
>>> args
|
|
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
|
|
>>> optlist, args = getopt.getopt(args, 'x', [
|
|
... 'condition=', 'output-file=', 'testing'])
|
|
>>> optlist
|
|
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x',
|
|
'')]
|
|
>>> args
|
|
['a1', 'a2']
|
|
>>>
|
|
\end{verbatim}
|