Mercurial > cpython-lru_cache-weakref

annotate Doc/libgetopt.tex @ 4566:6403c94de50d legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added safeguard against failure in __del__.
author Guido van Rossum <guido@python.org>
date Wed, 27 Nov 1996 19:39:58 +0000
parents e21d3e7aea87
children 6db8ade8d8a9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Standard Module \sectcode{getopt}}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
2
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \stmodindex{getopt}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 This module helps scripts to parse the command line arguments in
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
5 \code{sys.argv}.
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
6 It supports the same conventions as the \UNIX{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7 \code{getopt()}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
8 function (including the special meanings of arguments of the form
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
9 \samp{-} and \samp{--}). Long options similar to those supported by
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
10 GNU software may be used as well via an optional third argument.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 It defines the function
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
12 \code{getopt.getopt(args, options [, long_options])}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 and the exception
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 \code{getopt.error}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 The first argument to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 \code{getopt()}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 is the argument list passed to the script with its first element
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 chopped off (i.e.,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 \code{sys.argv[1:]}).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 The second argument is the string of option letters that the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 script wants to recognize, with options that require an argument
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 followed by a colon (i.e., the same format that \UNIX{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 \code{getopt()}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 uses).
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
26 The third option, if specified, is a list of strings with the names of
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
27 the long options which should be supported. The leading \code{'--'}
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
28 characters should not be included in the option name. Options which
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
29 require an argument should be followed by an equal sign (\code{'='}).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 The return value consists of two elements: the first is a list of
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 option-and-value pairs; the second is the list of program arguments
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 left after the option list was stripped (this is a trailing slice of the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 first argument).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 Each option-and-value pair returned has the option as its first element,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 prefixed with a hyphen (e.g.,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 \code{'-x'}),
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 and the option argument as its second element, or an empty string if the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 option has no argument.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 The options occur in the list in the same order in which they were
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
40 found, thus allowing multiple occurrences. Long and short options may
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
41 be mixed.
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
42
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
43 An example using only \UNIX{} style options:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 \bcode\begin{verbatim}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 >>> import getopt, string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 >>> args = string.split('-a -b -cfoo -d bar a1 a2')
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 >>> args
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 ['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 >>> optlist, args = getopt.getopt(args, 'abc:d:')
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 >>> optlist
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 [('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 >>> args
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 ['a1', 'a2']
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55 >>>
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 \end{verbatim}\ecode
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
57
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
58 Using long option names is equally easy:
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
59
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
60 \bcode\begin{verbatim}
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
61 >>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
62 >>> args = string.split(s)
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
63 >>> args
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
64 ['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
65 >>> optlist, args = getopt.getopt(args, 'x', [
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
66 ... 'condition=', 'output-file=', 'testing'])
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
67 >>> optlist
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
68 [('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')]
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
69 >>> args
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
70 ['a1', 'a2']
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
71 >>>
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
72 \end{verbatim}\ecode
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
73
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 The exception
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
75 \code{getopt.error = 'getopt.error'}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
76 is raised when an unrecognized option is found in the argument list or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 when an option requiring an argument is given none.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 The argument to the exception is a string indicating the cause of the
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
79 error. For long options, an argument given to an option which does
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
80 not require one will also cause this exception to be raised.