diff options
Diffstat (limited to 'Doc/lib/libgetopt.tex')
| -rw-r--r-- | Doc/lib/libgetopt.tex | 154 |
1 files changed, 0 insertions, 154 deletions
diff --git a/Doc/lib/libgetopt.tex b/Doc/lib/libgetopt.tex deleted file mode 100644 index 7930acd..0000000 --- a/Doc/lib/libgetopt.tex +++ /dev/null @@ -1,154 +0,0 @@ -\section{\module{getopt} --- - Parser for command line options} - -\declaremodule{standard}{getopt} -\modulesynopsis{Portable parser for command line options; support both - short and long option names.} - - -This module helps scripts to parse the command line arguments in -\code{sys.argv}. -It supports the same conventions as the \UNIX{} \cfunction{getopt()} -function (including the special meanings of arguments of the form -`\code{-}' and `\code{-}\code{-}'). -% That's to fool latex2html into leaving the two hyphens alone! -Long options similar to those supported by -GNU software may be used as well via an optional third argument. -This module provides a single function and an exception: - -\begin{funcdesc}{getopt}{args, options\optional{, long_options}} -Parses command line options and parameter list. \var{args} is the -argument list to be parsed, without the leading reference to the -running program. Typically, this means \samp{sys.argv[1:]}. -\var{options} is the string of option letters that the script wants to -recognize, with options that require an argument followed by a colon -(\character{:}; i.e., the same format that \UNIX{} -\cfunction{getopt()} uses). - -\note{Unlike GNU \cfunction{getopt()}, after a non-option -argument, all further arguments are considered also non-options. -This is similar to the way non-GNU \UNIX{} systems work.} - -\var{long_options}, if specified, must be a list of strings with the -names of the long options which should be supported. The leading -\code{'-}\code{-'} characters should not be included in the option -name. Long options which require an argument should be followed by an -equal sign (\character{=}). To accept only long options, -\var{options} should be an empty string. Long options on the command -line can be recognized so long as they provide a prefix of the option -name that matches exactly one of the accepted options. For example, -if \var{long_options} is \code{['foo', 'frob']}, the option -\longprogramopt{fo} will match as \longprogramopt{foo}, but -\longprogramopt{f} will not match uniquely, so \exception{GetoptError} -will be raised. - -The return value consists of two elements: the first is a list of -\code{(\var{option}, \var{value})} pairs; the second is the list of -program arguments left after the option list was stripped (this is a -trailing slice of \var{args}). Each option-and-value pair returned -has the option as its first element, prefixed with a hyphen for short -options (e.g., \code{'-x'}) or two hyphens for long options (e.g., -\code{'-}\code{-long-option'}), and the option argument as its second -element, or an empty string if the option has no argument. The -options occur in the list in the same order in which they were found, -thus allowing multiple occurrences. Long and short options may be -mixed. -\end{funcdesc} - -\begin{funcdesc}{gnu_getopt}{args, options\optional{, long_options}} -This function works like \function{getopt()}, except that GNU style -scanning mode is used by default. This means that option and -non-option arguments may be intermixed. The \function{getopt()} -function stops processing options as soon as a non-option argument is -encountered. - -If the first character of the option string is `+', or if the -environment variable POSIXLY_CORRECT is set, then option processing -stops as soon as a non-option argument is encountered. - -\versionadded{2.3} -\end{funcdesc} - -\begin{excdesc}{GetoptError} -This is raised when an unrecognized option is found in the argument -list or when an option requiring an argument is given none. -The argument to the exception is a string indicating the cause of the -error. For long options, an argument given to an option which does -not require one will also cause this exception to be raised. The -attributes \member{msg} and \member{opt} give the error message and -related option; if there is no specific option to which the exception -relates, \member{opt} is an empty string. - -\versionchanged[Introduced \exception{GetoptError} as a synonym for - \exception{error}]{1.6} -\end{excdesc} - -\begin{excdesc}{error} -Alias for \exception{GetoptError}; for backward compatibility. -\end{excdesc} - - -An example using only \UNIX{} style options: - -\begin{verbatim} ->>> import getopt ->>> args = '-a -b -cfoo -d bar a1 a2'.split() ->>> args -['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2'] ->>> optlist, args = getopt.getopt(args, 'abc:d:') ->>> optlist -[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')] ->>> args -['a1', 'a2'] -\end{verbatim} - -Using long option names is equally easy: - -\begin{verbatim} ->>> s = '--condition=foo --testing --output-file abc.def -x a1 a2' ->>> args = s.split() ->>> args -['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2'] ->>> optlist, args = getopt.getopt(args, 'x', [ -... 'condition=', 'output-file=', 'testing']) ->>> optlist -[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', - '')] ->>> args -['a1', 'a2'] -\end{verbatim} - -In a script, typical usage is something like this: - -\begin{verbatim} -import getopt, sys - -def main(): - try: - opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="]) - except getopt.GetoptError as err: - # print help information and exit: - print str(err) # will print something like "option -a not recognized" - usage() - sys.exit(2) - output = None - verbose = False - for o, a in opts: - if o == "-v": - verbose = True - elif o in ("-h", "--help"): - usage() - sys.exit() - elif o in ("-o", "--output"): - output = a - else: - assert False, "unhandled option" - # ... - -if __name__ == "__main__": - main() -\end{verbatim} - -\begin{seealso} - \seemodule{optparse}{More object-oriented command line option parsing.} -\end{seealso} |