blob: be00fefa640088479b15c77e00035d0869b606df [file] [log] [blame]
Fred Drake3a0351c1998-04-04 07:23:21 +00001\section{Standard Module \module{getopt}}
Guido van Rossume47da0a1997-07-17 16:34:52 +00002\label{module-getopt}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +00003\stmodindex{getopt}
Fred Drakea44d7401998-03-10 03:36:00 +00004
Guido van Rossum5fdeeea1994-01-02 01:22:07 +00005This module helps scripts to parse the command line arguments in
6\code{sys.argv}.
Fred Drakea44d7401998-03-10 03:36:00 +00007It supports the same conventions as the \UNIX{} \cfunction{getopt()}
Guido van Rossum470be141995-03-17 16:07:09 +00008function (including the special meanings of arguments of the form
Guido van Rossume8d94a81997-04-02 06:05:07 +00009`\code{-}' and `\code{-}\code{-}').
10% That's to fool latex2html into leaving the two hyphens alone!
11Long options similar to those supported by
Guido van Rossum2f666631996-09-11 21:26:29 +000012GNU software may be used as well via an optional third argument.
Fred Drakea44d7401998-03-10 03:36:00 +000013This module provides a single function and an exception:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000014
Fred Drakea44d7401998-03-10 03:36:00 +000015\begin{funcdesc}{getopt}{args, options\optional{, long_options}}
16Parses command line options and parameter list. \var{args} is the
17argument list to be parsed, without the leading reference to the
18running program. Typically, this means \samp{sys.argv[1:]}.
19\var{options} is the string of option letters that the script wants to
20recognize, with options that require an argument followed by a colon
21(i.e., the same format that \UNIX{} \cfunction{getopt()} uses). If
22specified, \var{long_options} is a list of strings with the names of
23the long options which should be supported. The leading
24\code{'-}\code{-'} characters should not be included in the option
25name. Options which require an argument should be followed by an
26equal sign (\code{'='}).
27
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000028The return value consists of two elements: the first is a list of
Fred Drakea44d7401998-03-10 03:36:00 +000029\code{(\var{option}, \var{value})} pairs; the second is the list of
30program arguments left after the option list was stripped (this is a
31trailing slice of the first argument).
32Each option-and-value pair returned has the option as its first
33element, prefixed with a hyphen (e.g., \code{'-x'}), and the option
34argument as its second element, or an empty string if the option has
35no argument.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000036The options occur in the list in the same order in which they were
Guido van Rossum2f666631996-09-11 21:26:29 +000037found, thus allowing multiple occurrences. Long and short options may
38be mixed.
Fred Drakea44d7401998-03-10 03:36:00 +000039\end{funcdesc}
40
41\begin{excdesc}{error}
42This is raised when an unrecognized option is found in the argument
43list or when an option requiring an argument is given none.
44The argument to the exception is a string indicating the cause of the
45error. For long options, an argument given to an option which does
46not require one will also cause this exception to be raised.
47\end{excdesc}
48
Guido van Rossum2f666631996-09-11 21:26:29 +000049
50An example using only \UNIX{} style options:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000051
Fred Drake19479911998-02-13 06:58:54 +000052\begin{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000053>>> import getopt, string
54>>> args = string.split('-a -b -cfoo -d bar a1 a2')
55>>> args
56['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
57>>> optlist, args = getopt.getopt(args, 'abc:d:')
58>>> optlist
59[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
60>>> args
61['a1', 'a2']
62>>>
Fred Drake19479911998-02-13 06:58:54 +000063\end{verbatim}
Fred Drakea44d7401998-03-10 03:36:00 +000064
Guido van Rossum2f666631996-09-11 21:26:29 +000065Using long option names is equally easy:
66
Fred Drake19479911998-02-13 06:58:54 +000067\begin{verbatim}
Guido van Rossum2f666631996-09-11 21:26:29 +000068>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
69>>> args = string.split(s)
70>>> args
71['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
72>>> optlist, args = getopt.getopt(args, 'x', [
73... 'condition=', 'output-file=', 'testing'])
74>>> optlist
Fred Drakea44d7401998-03-10 03:36:00 +000075[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x',
76 '')]
Guido van Rossum2f666631996-09-11 21:26:29 +000077>>> args
78['a1', 'a2']
79>>>
Fred Drake19479911998-02-13 06:58:54 +000080\end{verbatim}