Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libgetopt.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents 376ee174ecd0
children 85f0e60954ca 18ddc02ce36f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{getopt} ---
15142
563dee598d3a Fixed lots of small nits caught by Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 13925
diff changeset
2 Parser for command line options}
563dee598d3a Fixed lots of small nits caught by Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 13925
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4 \declaremodule{standard}{getopt}
15142
563dee598d3a Fixed lots of small nits caught by Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 13925
diff changeset
5 \modulesynopsis{Portable parser for command line options; support both
563dee598d3a Fixed lots of small nits caught by Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 13925
diff changeset
6 short and long option names.}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
7
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
8
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 This module helps scripts to parse the command line arguments in
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 \code{sys.argv}.
7627
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
11 It supports the same conventions as the \UNIX{} \cfunction{getopt()}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
12 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
13 `\code{-}' and `\code{-}\code{-}').
6db8ade8d8a9 Horrible hack to split up code '--' to prevent
Guido van Rossum <guido@python.org>
parents: 4284
diff changeset
14 % 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
15 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
16 GNU software may be used as well via an optional third argument.
7627
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
17 This module provides a single function and an exception:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18
7627
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
19 \begin{funcdesc}{getopt}{args, options\optional{, long_options}}
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
20 Parses command line options and parameter list. \var{args} is the
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
21 argument list to be parsed, without the leading reference to the
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
22 running program. Typically, this means \samp{sys.argv[1:]}.
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
23 \var{options} is the string of option letters that the script wants to
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
24 recognize, with options that require an argument followed by a colon
13925
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
25 (\character{:}; i.e., the same format that \UNIX{}
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
26 \cfunction{getopt()} uses).
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
27
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 17562
diff changeset
28 \note{Unlike GNU \cfunction{getopt()}, after a non-option
17402
3b905f28f225 Fixing bug 405999 -- clarifying differences between Python's
Moshe Zadka <moshez@math.huji.ac.il>
parents: 15764
diff changeset
29 argument, all further arguments are considered also non-options.
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 17562
diff changeset
30 This is similar to the way non-GNU \UNIX{} systems work.}
17402
3b905f28f225 Fixing bug 405999 -- clarifying differences between Python's
Moshe Zadka <moshez@math.huji.ac.il>
parents: 15764
diff changeset
31
13925
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
32 \var{long_options}, if specified, must be a list of strings with the
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
33 names of the long options which should be supported. The leading
7627
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
34 \code{'-}\code{-'} characters should not be included in the option
13925
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
35 name. Long options which require an argument should be followed by an
15764
7b3f8e761a2d Explain that long options are matched based on a unique prefix rather than
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
36 equal sign (\character{=}). To accept only long options,
7b3f8e761a2d Explain that long options are matched based on a unique prefix rather than
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
37 \var{options} should be an empty string. Long options on the command
7b3f8e761a2d Explain that long options are matched based on a unique prefix rather than
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
38 line can be recognized so long as they provide a prefix of the option
7b3f8e761a2d Explain that long options are matched based on a unique prefix rather than
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
39 name that matches exactly one of the accepted options. For example,
7b3f8e761a2d Explain that long options are matched based on a unique prefix rather than
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
40 it \var{long_options} is \code{['foo', 'frob']}, the option
7b3f8e761a2d Explain that long options are matched based on a unique prefix rather than
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
41 \longprogramopt{fo} will match as \longprogramopt{foo}, but
7b3f8e761a2d Explain that long options are matched based on a unique prefix rather than
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
42 \longprogramopt{f} will not match uniquely, so \exception{GetoptError}
7b3f8e761a2d Explain that long options are matched based on a unique prefix rather than
Fred Drake <fdrake@acm.org>
parents: 15142
diff changeset
43 will be raised.
7627
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
44
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 The return value consists of two elements: the first is a list of
7627
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
46 \code{(\var{option}, \var{value})} pairs; the second is the list of
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
47 program arguments left after the option list was stripped (this is a
13925
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
48 trailing slice of \var{args}). Each option-and-value pair returned
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
49 has the option as its first element, prefixed with a hyphen for short
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
50 options (e.g., \code{'-x'}) or two hyphens for long options (e.g.,
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
51 \code{'-}\code{-long-option'}), and the option argument as its second
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
52 element, or an empty string if the option has no argument. The
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
53 options occur in the list in the same order in which they were found,
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
54 thus allowing multiple occurrences. Long and short options may be
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
55 mixed.
7627
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
56 \end{funcdesc}
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
57
11616
a70dc73a28de Document GetoptError and label error an alias.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
58 \begin{excdesc}{GetoptError}
7627
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
59 This is raised when an unrecognized option is found in the argument
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
60 list or when an option requiring an argument is given none.
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
61 The argument to the exception is a string indicating the cause of the
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
62 error. For long options, an argument given to an option which does
11616
a70dc73a28de Document GetoptError and label error an alias.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
63 not require one will also cause this exception to be raised. The
a70dc73a28de Document GetoptError and label error an alias.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
64 attributes \member{msg} and \member{opt} give the error message and
a70dc73a28de Document GetoptError and label error an alias.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
65 related option; if there is no specific option to which the exception
a70dc73a28de Document GetoptError and label error an alias.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
66 relates, \member{opt} is an empty string.
17562
895fc5c95763 Add note about the version in which GetoptError was added -- this can
Fred Drake <fdrake@acm.org>
parents: 17402
diff changeset
67
895fc5c95763 Add note about the version in which GetoptError was added -- this can
Fred Drake <fdrake@acm.org>
parents: 17402
diff changeset
68 \versionchanged[Introduced \exception{GetoptError} as a synonym for
895fc5c95763 Add note about the version in which GetoptError was added -- this can
Fred Drake <fdrake@acm.org>
parents: 17402
diff changeset
69 \exception{error}]{1.6}
11616
a70dc73a28de Document GetoptError and label error an alias.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
70 \end{excdesc}
a70dc73a28de Document GetoptError and label error an alias.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
71
a70dc73a28de Document GetoptError and label error an alias.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
72 \begin{excdesc}{error}
a70dc73a28de Document GetoptError and label error an alias.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
73 Alias for \exception{GetoptError}; for backward compatibility.
7627
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
74 \end{excdesc}
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
75
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
76
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
77 An example using only \UNIX{} style options:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
78
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7007
diff changeset
79 \begin{verbatim}
13925
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
80 >>> import getopt
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
81 >>> args = '-a -b -cfoo -d bar a1 a2'.split()
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
82 >>> args
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
83 ['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
84 >>> optlist, args = getopt.getopt(args, 'abc:d:')
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
85 >>> optlist
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
86 [('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
87 >>> args
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 ['a1', 'a2']
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7007
diff changeset
89 \end{verbatim}
7627
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
90
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
91 Using long option names is equally easy:
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
92
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7007
diff changeset
93 \begin{verbatim}
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
94 >>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
13925
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
95 >>> args = s.split()
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
96 >>> args
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
97 ['--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
98 >>> optlist, args = getopt.getopt(args, 'x', [
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
99 ... 'condition=', 'output-file=', 'testing'])
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
100 >>> optlist
7627
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
101 [('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x',
a0c7aa0522de Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
102 '')]
4284
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
103 >>> args
e21d3e7aea87 Added long getopt docs; by Fred
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
104 ['a1', 'a2']
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7007
diff changeset
105 \end{verbatim}
13925
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
106
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
107 In a script, typical usage is something like this:
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
108
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
109 \begin{verbatim}
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
110 import getopt, sys
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
111
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
112 def main():
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
113 try:
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
114 opts, args = getopt.getopt(sys.argv[1:], "ho:", ["help", "output="])
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
115 except getopt.GetoptError:
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
116 # print help information and exit:
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
117 usage()
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
118 sys.exit(2)
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
119 output = None
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
120 for o, a in opts:
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
121 if o in ("-h", "--help"):
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
122 usage()
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
123 sys.exit()
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
124 if o in ("-o", "--output"):
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
125 output = a
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
126 # ...
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
127
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
128 if __name__ == "__main__":
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
129 main()
2a04fbb7c07d getopt(): revise description of long_options parameter slightly so it will
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
130 \end{verbatim}