add hg and python

1 files changed, 154 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libgetopt.tex b/sys/src/cmd/python/Doc/lib/libgetopt.tex
new file mode 100644
index 000000000..b38fcd8df
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libgetopt.tex
@@ -0,0 +1,154 @@
+\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, 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}