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