Mercurial > cpython-lru_cache-weakref

annotate Doc/libgetopt.tex @ 5817:48b94de85bf3 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Extensive changes by AMK.
author Guido van Rossum <guido@python.org>
date Thu, 17 Jul 1997 16:29:42 +0000
parents 6db8ade8d8a9
children 3468ea8645ca
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
5247
6db8ade8d8a9 Horrible hack to split up code '--' to prevent
Guido van Rossum <guido@python.org>
parents: 4284
diff changeset
9 `\code{-}' and `\code{-}\code{-}').
6db8ade8d8a9 Horrible hack to split up code '--' to prevent
Guido van Rossum <guido@python.org>
parents: 4284
diff changeset
10 % That's to fool latex2html into leaving the two hyphens alone!
6db8ade8d8a9 Horrible hack to split up code '--' to prevent
Guido van Rossum <guido@python.org>
parents: 4284
diff changeset
11 Long options similar to those supported by
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
12 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
13 It defines the function
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
14 \code{getopt.getopt(args, options [, long_options])}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 and the exception
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 \code{getopt.error}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 The first argument to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 \code{getopt()}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 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
21 chopped off (i.e.,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 \code{sys.argv[1:]}).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 The second argument is the string of option letters that the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 script wants to recognize, with options that require an argument
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 followed by a colon (i.e., the same format that \UNIX{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 \code{getopt()}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 uses).
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
28 The third option, if specified, is a list of strings with the names of
5247
6db8ade8d8a9 Horrible hack to split up code '--' to prevent
Guido van Rossum <guido@python.org>
parents: 4284
diff changeset
29 the long options which should be supported. The leading \code{'-}\code{-'}
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
30 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
31 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
32 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
33 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
34 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
35 first argument).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 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
37 prefixed with a hyphen (e.g.,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 \code{'-x'}),
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 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
40 option has no argument.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 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
42 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
43 be mixed.
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
44
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
45 An example using only \UNIX{} style options:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 \bcode\begin{verbatim}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 >>> import getopt, string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 >>> args = string.split('-a -b -cfoo -d bar a1 a2')
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 >>> args
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 ['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 >>> optlist, args = getopt.getopt(args, 'abc:d:')
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 >>> optlist
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 [('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55 >>> args
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 ['a1', 'a2']
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 >>>
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 \end{verbatim}\ecode
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
60 Using long option names is equally easy:
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
61
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
62 \bcode\begin{verbatim}
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
63 >>> 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
64 >>> args = string.split(s)
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
65 >>> args
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
66 ['--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
67 >>> optlist, args = getopt.getopt(args, 'x', [
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
68 ... 'condition=', 'output-file=', 'testing'])
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
69 >>> optlist
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
70 [('--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
71 >>> args
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
72 ['a1', 'a2']
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
73 >>>
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
74 \end{verbatim}\ecode
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
75
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
76 The exception
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
77 \code{getopt.error = 'getopt.error'}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 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
79 when an option requiring an argument is given none.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 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
81 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
82 not require one will also cause this exception to be raised.