cpython/Doc/lib/libgetopt.tex

81 lines
3.1 KiB
TeX
Raw Normal View History

1994-01-01 21:22:07 -04:00
\section{Standard Module \sectcode{getopt}}
\label{module-getopt}
1994-01-01 21:22:07 -04:00
\stmodindex{getopt}
1994-01-01 21:22:07 -04:00
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
1996-09-11 18:26:29 -03:00
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{'='}).
1994-01-01 21:22:07 -04:00
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 (e.g., \code{'-x'}), and the option
argument as its second element, or an empty string if the option has
no argument.
1994-01-01 21:22:07 -04:00
The options occur in the list in the same order in which they were
1996-09-11 18:26:29 -03:00
found, thus allowing multiple occurrences. Long and short options may
be mixed.
\end{funcdesc}
\begin{excdesc}{error}
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.
\end{excdesc}
1996-09-11 18:26:29 -03:00
An example using only \UNIX{} style options:
1994-01-01 21:22:07 -04:00
\begin{verbatim}
1994-01-01 21:22:07 -04:00
>>> 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}
1996-09-11 18:26:29 -03:00
Using long option names is equally easy:
\begin{verbatim}
1996-09-11 18:26:29 -03:00
>>> 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',
'')]
1996-09-11 18:26:29 -03:00
>>> args
['a1', 'a2']
>>>
\end{verbatim}