Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1 | \section{Standard Module \sectcode{getopt}} |
| 2 | |
| 3 | \stmodindex{getopt} |
| 4 | This module helps scripts to parse the command line arguments in |
| 5 | \code{sys.argv}. |
Guido van Rossum | 2f66663 | 1996-09-11 21:26:29 +0000 | [diff] [blame] | 6 | It supports the same conventions as the \UNIX{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 7 | \code{getopt()} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 8 | function (including the special meanings of arguments of the form |
Guido van Rossum | 2f66663 | 1996-09-11 21:26:29 +0000 | [diff] [blame] | 9 | \samp{-} and \samp{--}). Long options similar to those supported by |
| 10 | GNU software may be used as well via an optional third argument. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 11 | It defines the function |
Guido van Rossum | 2f66663 | 1996-09-11 21:26:29 +0000 | [diff] [blame] | 12 | \code{getopt.getopt(args, options [, long_options])} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 13 | and the exception |
| 14 | \code{getopt.error}. |
| 15 | |
| 16 | The first argument to |
| 17 | \code{getopt()} |
| 18 | is the argument list passed to the script with its first element |
| 19 | chopped off (i.e., |
| 20 | \code{sys.argv[1:]}). |
| 21 | The second argument is the string of option letters that the |
| 22 | script wants to recognize, with options that require an argument |
| 23 | followed by a colon (i.e., the same format that \UNIX{} |
| 24 | \code{getopt()} |
| 25 | uses). |
Guido van Rossum | 2f66663 | 1996-09-11 21:26:29 +0000 | [diff] [blame] | 26 | The third option, if specified, is a list of strings with the names of |
| 27 | the long options which should be supported. The leading \code{'--'} |
| 28 | characters should not be included in the option name. Options which |
| 29 | require an argument should be followed by an equal sign (\code{'='}). |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 30 | The return value consists of two elements: the first is a list of |
| 31 | option-and-value pairs; the second is the list of program arguments |
| 32 | left after the option list was stripped (this is a trailing slice of the |
| 33 | first argument). |
| 34 | Each option-and-value pair returned has the option as its first element, |
| 35 | prefixed with a hyphen (e.g., |
| 36 | \code{'-x'}), |
| 37 | and the option argument as its second element, or an empty string if the |
| 38 | option has no argument. |
| 39 | The options occur in the list in the same order in which they were |
Guido van Rossum | 2f66663 | 1996-09-11 21:26:29 +0000 | [diff] [blame] | 40 | found, thus allowing multiple occurrences. Long and short options may |
| 41 | be mixed. |
| 42 | |
| 43 | An example using only \UNIX{} style options: |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 44 | |
| 45 | \bcode\begin{verbatim} |
| 46 | >>> import getopt, string |
| 47 | >>> args = string.split('-a -b -cfoo -d bar a1 a2') |
| 48 | >>> args |
| 49 | ['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2'] |
| 50 | >>> optlist, args = getopt.getopt(args, 'abc:d:') |
| 51 | >>> optlist |
| 52 | [('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')] |
| 53 | >>> args |
| 54 | ['a1', 'a2'] |
| 55 | >>> |
| 56 | \end{verbatim}\ecode |
| 57 | |
Guido van Rossum | 2f66663 | 1996-09-11 21:26:29 +0000 | [diff] [blame] | 58 | Using long option names is equally easy: |
| 59 | |
| 60 | \bcode\begin{verbatim} |
| 61 | >>> s = '--condition=foo --testing --output-file abc.def -x a1 a2' |
| 62 | >>> args = string.split(s) |
| 63 | >>> args |
| 64 | ['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2'] |
| 65 | >>> optlist, args = getopt.getopt(args, 'x', [ |
| 66 | ... 'condition=', 'output-file=', 'testing']) |
| 67 | >>> optlist |
| 68 | [('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')] |
| 69 | >>> args |
| 70 | ['a1', 'a2'] |
| 71 | >>> |
| 72 | \end{verbatim}\ecode |
| 73 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 74 | The exception |
Guido van Rossum | 2f66663 | 1996-09-11 21:26:29 +0000 | [diff] [blame] | 75 | \code{getopt.error = 'getopt.error'} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 76 | is raised when an unrecognized option is found in the argument list or |
| 77 | when an option requiring an argument is given none. |
| 78 | The argument to the exception is a string indicating the cause of the |
Guido van Rossum | 2f66663 | 1996-09-11 21:26:29 +0000 | [diff] [blame] | 79 | error. For long options, an argument given to an option which does |
| 80 | not require one will also cause this exception to be raised. |