Split into a root file (this one) and three subfile mod[123].tex.

2 files changed, 6 insertions, 4178 deletions

diff --git a/Doc/lib.tex b/Doc/lib.tex
index 8e36427..f0b649a 100644
--- a/Doc/lib.tex
+++ b/Doc/lib.tex
@@ -55,2094 +55,8 @@ gives a more formal reference to the language.
 
 \pagenumbering{arabic}
 
-\section{Introduction}
-
-The {\Python} library consists of three parts, with different levels of
-integration with the interpreter.
-Closest to the interpreter are built-in types, exceptions and functions.
-Next are built-in modules, which are written in C and linked statically
-with the interpreter.
-Finally there are standard modules that are implemented entirely in
-{\Python}, but are always available.
-For efficiency, some standard modules may become built-in modules in
-future versions of the interpreter.
-
-\section{Built-in Types, Exceptions and Functions}
-
-Names for built-in exceptions and functions are found in a separate
-read-only symbol table which cannot be modified.
-This table is searched last, so local and global user-defined names can
-override built-in names.
-Built-in types have no names but are created by syntactic constructs
-(such as constants) or built-in functions.
-They are described together here for easy reference.%
-\footnote{
-The descriptions sorely lack explanations of the exceptions that
-may be raised---this will be fixed in a future version of this
-document.
-}
-
-\subsection{Built-in Types}
-
-The following sections describe the standard types that are built into the
-interpreter.
-\subsubsection{Numeric Types}
-
-There are two numeric types: integers and floating point numbers.
-Integers are implemented using {\tt long} in C, so they have at least 32
-bits of precision.
-Floating point numbers are implemented using {\tt double} in C.
-All bets on precision are off.
-Numbers are created by numeric constants or as the result of built-in
-functions and operators.
-
-Numeric types support the following operations:
-
-\begin{center}
-\begin{tabular}{|c|l|c|}
-\hline
-Operation & Result & Notes \\
-\hline
-{\tt abs}({\em x}) & absolute value of {\em x} & \\
-{\tt int}({\em x}) & {\em x} converted to integer & (1) \\
-{\tt float}({\em x}) & {\em x} converted to floating point & \\
-{\tt -}{\em x} & {\em x} negated & \\
-{\tt +}{\em x} & {\em x} unchanged & \\
-{\em x}{\tt +}{\em y} & sum of {\em x} and {\em y} & \\
-{\em x}{\tt -}{\em y} & difference of {\em x} and {\em y} & \\
-{\em x}{\tt *}{\em y} & product of {\em x} and {\em y} & \\
-{\em x}{\tt /}{\em y} & quotient of {\em x} and {\em y} & (2) \\
-{\em x}{\tt \%}{\em y} & remainder of {\em x}{\tt /}{\em y} & (3) \\
-\hline
-\end{tabular}
-\end{center}
-
-\noindent
-Notes:
-\begin{description}
-\item[(1)]
-This may round or truncate as in C; see functions {\tt floor} and
-{\tt ceil} in module {\tt math}.
-\item[(2)]
-Integer division is defined as in C: the result is an integer; with
-positive operands, it truncates towards zero; with a negative operand,
-the result is unspecified.
-\item[(3)]
-Only defined for integers.
-\end{description}
-
-Mixed arithmetic is not supported; both operands must have the same type.
-Mixed comparisons return the wrong result (floats always compare smaller
-than integers).%
-\footnote{
-These restrictions are bugs in the language definitions and will be
-fixed in the future.
-}
-\subsubsection{Sequence Types}
-
-There are three sequence types: strings, lists and tuples.
-Strings constants are written in single quotes: {\tt 'xyzzy'}.
-Lists are constructed with square brackets: {\tt [a,~b,~c]}.
-Tuples are constructed by the comma operator or with an empty set of
-parentheses: {\tt a,~b,~c} or {\tt ()}.
-
-Sequence types support the following operations ({\em s} and {\em t} are
-sequences of the same type; {\em n}, {\em i} and {\em j} are integers):
-
-\begin{center}
-\begin{tabular}{|c|l|c|}
-\hline
-Operation & Result & Notes \\
-\hline
-{\tt len}({\em s}) & length of {\em s} & \\
-{\tt min}({\em s}) & smallest item of {\em s} & \\
-{\tt max}({\em s}) & largest item of {\em s} & \\
-{\em x} {\tt in} {\em s} &
-	true if an item of {\em s} is equal to {\em x} & \\
-{\em x} {\tt not} {\tt in} {\em s} &
-	false if an item of {\em s} is equal to {\em x} & \\
-{\em s}{\tt +}{\em t} & the concatenation of {\em s} and {\em t} & \\
-{\em s}{\tt *}{\em n}, {\em n}*{\em s} &
-	{\em n} copies of {\em s} concatenated & (1) \\
-{\em s}[{\em i}] & {\em i}'th item of {\em s} & \\
-{\em s}[{\em i}:{\em j}] &
-	slice of {\em s} from {\em i} to {\em j} & (2) \\
-\hline
-\end{tabular}
-\end{center}
-
-\noindent
-Notes:
-\begin{description}
-\item[(1)]
-Sequence repetition is only supported for strings.
-\item[(2)]
-The slice of $s$ from $i$ to $j$ is defined as the sequence
-of items with index $k$ such that $i \leq k < j$.
-Special rules apply for negative and omitted indices; see the Tutorial
-or the Reference Manual.
-\end{description}
-
-\paragraph{Mutable Sequence Types.}
-
-List objects support additional operations that allow in-place
-modification of the object.
-These operations would be supported by other mutable sequence types
-(when added to the language) as well.
-Strings and tuples are immutable sequence types and such objects cannot
-be modified once created.
-The following operations are defined on mutable sequence types (where
-{\em x} is an arbitrary object):
-
-\begin{center}
-\begin{tabular}{|c|l|}
-\hline
-Operation & Result \\
-\hline
-{\em s}[{\em i}] = {\em x} &
-	item {\em i} of {\em s} is replaced by {\em x} \\
-{\em s}[{\em i}:{\em j}] = {\em t} &
-	slice of {\em s} from {\em i} to {\em j} is replaced by {\em t} \\
-{\tt del} {\em s}[{\em i}:{\em j}] &
-	same as {\em s}[{\em i}:{\em j}] = [] \\
-{\em s}.{\tt append}({\em x}) &
-	same as {\em s}[{\tt len}({\em x}):{\tt len}({\em x})] = [{\em x}] \\
-{\em s}.{\tt insert}({\em i}, {\em x}) &
-	same as {\em s}[{\em i}:{\em i}] = [{\em x}] \\
-{\em s}.{\tt sort}() &
-	the items of {\em s} are permuted to satisfy \\
-	&
-	$s[i] \leq s[j]$ for $i < j$\\
-\hline
-\end{tabular}
-\end{center}
-
-\subsubsection{Mapping Types}
-
-A
-{\em mapping}
-object maps values of one type (the key type) to arbitrary objects.
-Mappings are mutable objects.
-There is currently only one mapping type, the
-{\em dictionary}.
-A dictionary's keys are strings.
-An empty dictionary is created by the expression \verb"{}".
-An extension of this notation is used to display dictionaries when
-written (see the example below).
-
-The following operations are defined on mappings (where {\em a} is a
-mapping, {\em k} is a key and {\em x} is an arbitrary object):
-
-\begin{center}
-\begin{tabular}{|c|l|c|}
-\hline
-Operation & Result & Notes\\
-\hline
-{\tt len}({\em a}) & the number of elements in {\em a} & \\
-{\em a}[{\em k}] & the item of {\em a} with key {\em k} & \\
-{\em a}[{\em k}] = {\em x} & set {\em a}[{\em k}] to {\em x} & \\
-{\tt del} {\em a}[{\em k}] & remove {\em a}[{\em k}] from {\em a} & \\
-{\em a}.{\tt keys}() & a copy of {\em a}'s list of keys & (1) \\
-{\em a}.{\tt has\_key}({\em k}) & true if {\em a} has a key {\em k} & \\
-\hline
-\end{tabular}
-\end{center}
-
-\noindent
-Notes:
-\begin{description}
-\item[(1)]
-Keys are listed in random order.
-\end{description}
-
-A small example using a dictionary:
-\bcode\begin{verbatim}
->>> tel = {}
->>> tel['jack'] = 4098
->>> tel['sape'] = 4139
->>> tel['guido'] = 4127
->>> tel['jack']
-4098
->>> tel
-{'sape': 4139; 'guido': 4127; 'jack': 4098}
->>> del tel['sape']
->>> tel['irv'] = 4127
->>> tel
-{'guido': 4127; 'irv': 4127; 'jack': 4098}
->>> tel.keys()
-['guido', 'irv', 'jack']
->>> tel.has_key('guido')
-1
->>> 
-\end{verbatim}\ecode
-\subsubsection{Other Built-in Types}
-
-The interpreter supports several other kinds of objects.
-Most of these support only one or two operations.
-
-\paragraph{Modules.}
-
-The only operation on a module is member acces: {\em m}{\tt .}{\em name},
-where {\em m} is a module and {\em name} accesses a name defined in
-{\em m}'s symbol table.
-Module members can be assigned to.
-
-\paragraph{Classes and Class Objects.}
-
-XXX Classes will be explained at length in a later version of this
-document.
-
-\paragraph{Functions.}
-
-Function objects are created by function definitions.
-The only operation on a function object is to call it:
-{\em func}({\em optional-arguments}).
-
-Built-in functions have a different type than user-defined functions,
-but they support the same operation.
-
-\paragraph{Methods.}
-
-Methods are functions that are called using the member acces notation.
-There are two flavors: built-in methods (such as {\tt append()} on
-lists) and class member methods.
-Built-in methods are described with the types that support them.
-XXX Class member methods will be described in a later version of this
-document.
-
-\paragraph{Type Objects.}
-
-Type objects represent the various object types.
-An object's type is accessed by the built-in function
-{\tt type()}.
-There are no operations on type objects.
-
-\paragraph{The Null Object.}
-
-This object is returned by functions that don't explicitly return a
-value.
-It supports no operations.
-There is exactly one null object, named {\tt None}
-(a built-in name).
-
-\paragraph{File Objects.}
-
-File objects are implemented using C's
-{\em stdio}
-package and can be created with the built-in function
-{\tt open()}.
-They have the following methods:
-\begin{description}
-\funcitem{close}{}
-Closes the file.
-A closed file cannot be read or written anymore.
-\funcitem{read}{size}
-Reads at most
-{\tt size}
-bytes from the file (less if the read hits EOF).
-The bytes are returned as a string object.
-An empty string is returned when EOF is hit immediately.
-(For certain files, like ttys, it makes sense to continue reading after
-an EOF is hit.)
-\funcitem{readline}{size}
-Reads a line of at most
-{\tt size}
-bytes from the file.
-A trailing newline character, if present, is kept in the string.
-The size is optional and defaults to a large number (but not infinity).
-EOF is reported as by
-{\tt read().}
-\funcitem{write}{str}
-Writes a string to the file.
-Returns no value.
-\end{description}
-
-\subsection{Built-in Exceptions}
-
-The following exceptions can be generated by the interpreter or
-built-in functions.
-Except where mentioned, they have a string argument (also known as the
-`associated value' of an exception) indicating the detailed cause of the
-error.
-The strings listed with the exception names are their values when used
-in an expression or printed.
-\begin{description}
-\excitem{EOFError}{end-of-file read}
-(No argument.)
-Raised when a built-in function ({\tt input()} or {\tt raw\_input()})
-hits an end-of-file condition (EOF) without reading any data.
-(N.B.: the {\tt read()} and {\tt readline()} methods of file objects
-return an empty string when they hit EOF.)
-\excitem{KeyboardInterrupt}{end-of-file read}
-(No argument.)
-Raised when the user hits the interrupt key (normally Control-C or DEL).
-During execution, a check for interrupts is made regularly.
-Interrupts typed when a built-in function ({\tt input()} or
-{\tt raw\_input()}) is waiting for input also raise this exception.
-\excitem{MemoryError}{out of memory}
-%.br
-Raised when an operation runs out of memory but the situation
-may still be rescued (by deleting some objects).
-\excitem{NameError}{undefined name}
-%.br
-Raised when a name is not found.
-This applies to unqualified names, module names (on {\tt import}),
-module members and object methods.
-The string argument is the name that could not be found.
-\excitem{RuntimeError}{run-time error}
-%.br
-Raised for a variety of reasons, e.g., division by zero or index out of
-range.
-\excitem{SystemError}{system error}
-%.br
-Raised when the interpreter finds an internal error, but the situation
-does not look so serious to cause it to abandon all hope.
-\excitem{TypeError}{type error}
-%.br
-Raised when an operation or built-in function is applied to an object of
-inappropriate type.
-\end{description}
-
-\subsection{Built-in Functions}
-
-The {\Python} interpreter has a small number of functions built into it that
-are always available.
-They are listed here in alphabetical order.
-\begin{description}
-\funcitem{abs}{x}
-Returns the absolute value of a number.
-The argument may be an integer or floating point number.
-\funcitem{chr}{i}
-Returns a string of one character
-whose ASCII code is the integer {\tt i},
-e.g., {\tt chr(97)} returns the string {\tt 'a'}.
-This is the inverse of {\tt ord()}.
-\funcitem{dir}{}
-Without arguments, this function returns the list of names in the
-current local symbol table, sorted alphabetically.
-With a module object as argument, it returns the sorted list of names in
-that module's global symbol table.
-For example:
-\bcode\begin{verbatim}
->>> import sys
->>> dir()
-['sys']
->>> dir(sys)
-['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout']
->>> 
-\end{verbatim}\ecode
-\funcitem{divmod}{a, b}
-%.br
-Takes two integers as arguments and returns a pair of integers
-consisting of their quotient and remainder.
-For
-\bcode\begin{verbatim}
-q, r = divmod(a, b)
-\end{verbatim}\ecode
-the invariants are:
-\bcode\begin{verbatim}
-a = q*b + r
-abs(r) < abs(b)
-r has the same sign as b
-\end{verbatim}\ecode
-For example:
-\bcode\begin{verbatim}
->>> divmod(100, 7)
-(14, 2)
->>> divmod(-100, 7)
-(-15, 5)
->>> divmod(100, -7)
-(-15, -5)
->>> divmod(-100, -7)
-(14, -2)
->>> 
-\end{verbatim}\ecode
-\funcitem{eval}{s}
-Takes a string as argument and parses and evaluates it as a {\Python}
-expression.
-The expression is executed using the current local and global symbol
-tables.
-Syntax errors are reported as exceptions.
-For example:
-\bcode\begin{verbatim}
->>> x = 1
->>> eval('x+1')
-2
->>> 
-\end{verbatim}\ecode
-\funcitem{exec}{s}
-Takes a string as argument and parses and evaluates it as a sequence of
-{\Python} statements.
-The string should end with a newline (\verb"'\n'").
-The statement is executed using the current local and global symbol
-tables.
-Syntax errors are reported as exceptions.
-For example:
-\bcode\begin{verbatim}
->>> x = 1
->>> exec('x = x+1\n')
->>> x
-2
->>> 
-\end{verbatim}\ecode
-\funcitem{float}{x}
-Converts a number to floating point.
-The argument may be an integer or floating point number.
-\funcitem{input}{s}
-Equivalent to
-{\tt eval(raw\_input(s))}.
-As for
-{\tt raw\_input()},
-the argument is optional.
-\funcitem{int}{x}
-Converts a number to integer.
-The argument may be an integer or floating point number.
-\funcitem{len}{s}
-Returns the length (the number of items) of an object.
-The argument may be a sequence (string, tuple or list) or a mapping
-(dictionary).
-\funcitem{max}{s}
-Returns the largest item of a non-empty sequence (string, tuple or list).
-\funcitem{min}{s}
-Returns the smallest item of a non-empty sequence (string, tuple or list).
-\funcitem{open}{name, mode}
-%.br
-Returns a file object (described earlier under Built-in Types).
-The string arguments are the same as for stdio's
-{\tt fopen()}:
-{\tt 'r'}
-opens the file for reading,
-{\tt 'w'}
-opens it for writing (truncating an existing file),
-{\tt 'a'}
-opens it for appending.%
-\footnote{
-This function should go into a built-in module
-{\tt io}.
-}
-\funcitem{ord}{c}
-Takes a string of one character and returns its
-ASCII value, e.g., {\tt ord('a')} returns the integer {\tt 97}.
-This is the inverse of {\tt chr()}.
-\funcitem{range}{}
-This is a versatile function to create lists containing arithmetic
-progressions of integers.
-With two integer arguments, it returns the ascending sequence of
-integers starting at the first and ending one before the second
-argument.
-A single argument is used as the end point of the sequence, with 0 used
-as the starting point.
-A third argument specifies the step size; negative steps are allowed and
-work as expected, but don't specify a zero step.
-The resulting list may be empty.
-For example:
-\bcode\begin{verbatim}
->>> range(10)
-[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
->>> range(1, 1+10)
-[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
->>> range(0, 30, 5)
-[0, 5, 10, 15, 20, 25]
->>> range(0, 10, 3)
-[0, 3, 6, 9]
->>> range(0, -10, -1)
-[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
->>> range(0)
-[]
->>> range(1, 0)
-[]
->>> 
-\end{verbatim}\ecode
-\funcitem{raw\_input}{s}
-%.br
-The argument is optional; if present, it is written to standard output
-without a trailing newline.
-The function then reads a line from input, converts it to a string
-(stripping a trailing newline), and returns that.
-EOF is reported as an exception.
-For example:
-\bcode\begin{verbatim}
->>> raw_input('Type anything: ')
-Type anything: Mutant Teenage Ninja Turtles
-'Mutant Teenage Ninja Turtles'
->>> 
-\end{verbatim}\ecode
-\funcitem{reload}{module}
-Causes an already imported module to be re-parsed and re-initialized.
-This is useful if you have edited the module source file and want to
-try out the new version without leaving {\Python}.
-\funcitem{type}{x}
-Returns the type of an object.
-Types are objects themselves:
-the type of a type object is its own type.
-\end{description}
-
-\section{Built-in Modules}
-
-The modules described in this section are built into the interpreter.
-They must be imported using
-{\tt import}.
-Some modules are not always available; it is a configuration option to
-provide them.
-Details are listed with the descriptions, but the best way to see if
-a module exists in a particular implementation is to attempt to import
-it.
-
-\subsection{Built-in Module {\tt sys}}
-
-This module provides access to some variables used or maintained by the
-interpreter and to functions that interact strongly with the interpreter.
-It is always available.
-\begin{description}
-\funcitem{argv}
-The list of command line arguments passed to a {\Python} script.
-{\tt sys.argv[0]}
-is the script name.
-If no script name was passed to the {\Python} interpreter,
-{\tt sys.argv}
-is empty.
-\funcitem{exit}{n}
-Exits from {\Python} with numeric exit status
-{\tt n}.
-This closes all open files and performs other cleanup-actions required by
-the interpreter (but
-{\em finally clauses}
-of
-{\tt try}
-statements are not executed!).
-\funcitem{modules}
-Gives the list of modules that have already been loaded.
-This can be manipulated to force reloading of modules and other tricks.
-\funcitem{path}
-A list of strings that specifies the search path for modules.
-Initialized from the environment variable {\tt PYTHONPATH}, or an
-installation-dependent default.
-\funcitem{ps1,~ps2}
-Strings specifying the primary and secondary prompt of the interpreter.
-These are only defined if the interpreter is in interactive mode.
-Their initial values in this case are
-{\tt '>>> '}
-and
-{\tt '... '}.
-\funcitem{stdin, stdout, stderr}
-%.br
-File objects corresponding to the interpreter's standard input, output
-and error streams.
-{\tt sys.stdin}
-is used for all interpreter input except for scripts but including calls
-to
-{\tt input()}
-and
-{\tt raw\_input()}.
-{\tt sys.stdout}
-is used for the output of
-{\tt print} and expression statements
-and for the prompts of
-{\tt input()}
-and
-{\tt raw\_input()}.
-The interpreter's own prompts and its error messages are written to
-stderr.
-Assigning to
-{\tt sys.stderr}
-has no effect on the interpreter; it can be used to write error messages
-to stderr using
-{\tt print}.
-\end{description}
-
-\subsection{Built-in Module {\tt math}}
-
-This module is always available.
-It provides access to the mathematical functions defined by the C
-standard.
-They are:
-{\tt acos(x)},
-{\tt asin(x)},
-{\tt atan(x)},
-{\tt atan2(x,y)},
-{\tt ceil(x)},
-{\tt cos(x)},
-{\tt cosh(x)},
-{\tt exp(x)},
-{\tt fabs(x)},
-{\tt floor(x)},
-%{\tt fmod(...)}  XXX not yet
-%{\tt frexp(...)} XXX not yet
-%{\tt ldexp(...)} XXX not yet
-{\tt log(x)},
-{\tt log10(x)},
-%{\tt modf(...)}  XXX not yet
-{\tt pow(x,y)},
-{\tt sin(x)},
-{\tt sinh(x)},
-{\tt sqrt(x)},
-{\tt tan(x)},
-{\tt tanh(x)}.
-
-It also defines two mathematical constants:
-{\tt pi}
-and
-{\tt e}.
-
-\subsection{Built-in Module {\tt time}}
-
-This module provides various time-related functions.
-It is always available.
-Functions are:
-\begin{description}
-\funcitem{sleep}{secs}
-Suspends execution for the given number of seconds.
-\funcitem{time}{}
-Returns the time in seconds since the Epoch (Thursday January 1,
-00:00:00, 1970 UCT on \UNIX\ machines).
-\end{description}
-
-\noindent
-In some versions (Amoeba, Mac) the following functions also exist:
-\begin{description}
-\funcitem{millisleep}{msecs}
-Suspends execution for the given number of milliseconds.
-\funcitem{millitimer}{}
-Returns the number of milliseconds of real time elapsed since some point
-in the past that is fixed per execution of the python interpreter (but
-may change in each following run).
-\end{description}
-
-\noindent
-The granularity of the milliseconds functions may be more than a
-millisecond (100 msecs on Amoeba, 1/60 sec on the Mac).
-
-\subsection{Built-in Module {\tt regexp}}
-
-This module provides a regular expression matching operation.
-It is always available.
-
-The module defines a function and an exception:
-
-\begin{description}
-
-\funcitem{compile}{pattern}
-
-Compile a regular expression given as a string into a regular
-expression object.
-The string must be an egrep-style regular expression;
-this means that the characters {\tt '(' ')' '*' '+' '?' '|' '^' '$'}
-are special.
-(It is implemented using Henry Spencer's regular expression matching
-functions.)
-
-excitem{error}{regexp.error}
-
-Exception raised when a string passed to {\tt compile()} is not a
-valid regular expression (e.g., unmatched parentheses) or when some other
-error occurs during compilation or matching
-(``no match found'' is not an error).
-
-\end{description}
-
-Compiled regular expression objects support a single method:
-
-\begin{description}
-
-\funcitem{exec}{str}
-
-Find the first occurrence of the compiled regular expression in the
-string {\tt str}.
-The return value is a tuple of pairs specifying where a match was
-found and where matches were found for subpatterns specified with
-{\tt '('} and {\tt ')'} in the pattern.
-If no match is found, an empty tuple is returned; otherwise the first
-item of the tuple is a pair of slice indices into the search string
-giving the match found.
-If there were any subpatterns in the pattern, the returned tuple has an
-additional item for each subpattern, giving the slice indices into the
-search string where that subpattern was found.
-
-\end{description}
-
-For example:
-\bcode\begin{verbatim}
->>> import regexp
->>> r = regexp.compile('--(.*)--')
->>> s = 'a--b--c'
->>> r.exec(s)
-((1, 6), (3, 4))
->>> s[1:6] # The entire match
-'--b--'
->>> s[3:4] # The subpattern
-'b'
->>> 
-\end{verbatim}\ecode
-
-\subsection{Built-in Module {\tt posix}}
-
-This module provides access to operating system functionality that is
-standardized by the C Standard and the POSIX standard (a thinly diguised
-{\UNIX} interface).
-It is available in all {\Python} versions except on the Macintosh.
-Errors are reported exceptions.
-It defines the following items:
-\begin{description}
-\funcitem{chdir}{path}
-Changes the current directory to
-{\tt path}.
-\funcitem{chmod}{path, mode}
-Change the mode of
-{\tt path}
-to the numeric
-{\tt mode}.
-\funcitem{environ}
-A dictionary representing the string environment at the time
-the interpreter was started.
-(Modifying this dictionary does not affect the string environment of the
-interpreter.)
-For example,
-{\tt posix.environ['HOME']}
-is the pathname of your home directory, equivalent to
-{\tt getenv("HOME")}
-in C.
-\excitem{error}{posix.error}
-%.br
-The exception raised when an POSIX function returns an error.
-The value accompanying this exception is a pair containing the numeric
-error code from
-{\tt errno}
-and the corresponding string, as would be printed by the C function
-{\tt perror()}.
-\funcitem{getcwd}{}
-Returns a string representing the current working directory.
-\funcitem{link}{src, dst}
-Creates a hard link pointing to
-{\tt src}
-named
-{\tt dst}.
-\funcitem{listdir}{path}
-Returns a list containing the names of the entries in the
-directory.
-The list is in arbitrary order.
-It includes the special entries
-{\tt '.'}
-and
-{\tt '..'}
-if they are present in the directory.
-\funcitem{mkdir}{path, mode}
-Creates a directory named
-{\tt path}
-with numeric mode
-{\tt mode}.
-\funcitem{rename}{src, dst}
-Renames the file or directory
-{\tt src}
-to
-{\tt dst}.
-\funcitem{rmdir}{path}
-Removes the directory
-{\tt path}.
-\funcitem{stat}{path}
-Performs a
-{\em stat}
-system call on the given path.
-The return value is a tuple of at least 10 integers giving the most
-important (and portable) members of the
-{\em stat}
-structure, in the order
-{\tt st\_mode},
-{\tt st\_ino},
-{\tt st\_dev},
-{\tt st\_nlink},
-{\tt st\_uid},
-{\tt st\_gid},
-{\tt st\_size},
-{\tt st\_atime},
-{\tt st\_mtime},
-{\tt st\_ctime}.
-More items may be added at the end by some implementations.
-\funcitem{system}{command}
-Executes the command (a string) in a subshell.
-This is implemented by calling the Standard C function
-{\tt system()},
-and has the same limitations.
-Changes to
-{\tt posix.environ},
-{\tt sys.stdin}
-etc. are not reflected in the environment of the executed command.
-The return value is the exit status of the process as returned by
-Standard C
-{\tt system()}.
-\funcitem{umask}{mask}
-Sets the current numeric umask and returns the previous umask.
-\funcitem{unlink}{path}
-Unlinks the file
-{\tt path}.
-\funcitem{utimes(path, }{atime, mtime)}
-%.br
-Sets the access and modified time of the file to the given values.
-(The second argument is a tuple of two items.)
-\end{description}
-
-The following functions are only available on systems that support
-symbolic links:
-\begin{description}
-\funcitem{lstat}{path}
-Like
-{\tt stat()},
-but does not follow symbolic links.
-\funcitem{readlink}{path}
-Returns a string representing the path to which the symbolic link
-points.
-\funcitem{symlink}{src, dst}
-Creates a symbolic link pointing to
-{\tt src}
-named
-{\tt dst}.
-\end{description}
-
-\subsection{Built-in Module {\tt stdwin}}
-
-This module defines several new object types and functions that
-provide access to the functionality of the Standard Window System
-Interface, STDWIN [CWI report CR-R8817].
-It is available on systems to which STDWIN has been ported (which is
-most systems).
-It is only available if the {\tt DISPLAY} environment variable is set
-or an explicit `{\tt -display \it displayname}' argument is passed to
-the interpreter.
-
-Functions have names that usually resemble their C STDWIN counterparts
-with the initial `w' dropped.
-Points are represented by pairs of integers; rectangles
-by pairs of points.
-For a complete description of STDWIN please refer to the documentation
-of STDWIN for C programmers (aforementioned CWI report).
-\subsubsection{Functions Defined in Module {\tt stdwin}}
-
-The following functions are defined in the {\tt stdwin} module:
-\begin{description}
-\funcitem{open}{title}
-%.br
-Opens a new window whose initial title is given by the string argument.
-Returns a window object; window object methods are described below.%
-\footnote{
-The {\Python} version of STDWIN does not support draw procedures; all
-drawing requests are reported as draw events.
-}
-\funcitem{getevent}{}
-%.br
-Waits for and returns the next event.
-An event is returned as a triple: the first element is the event
-type, a small integer; the second element is the window object to which
-the event applies, or
-{\tt None}
-if it applies to no window in particular;
-the third element is type-dependent.
-Names for event types and command codes are defined in the standard
-module
-{\tt stdwinevent}.
-\funcitem{setdefwinpos}{h, v}
-%.br
-Sets the default window position.
-\funcitem{setdefwinsize}{width, height}
-%.br
-Sets the default window size.
-\funcitem{menucreate}{title}
-%.br
-Creates a menu object referring to a global menu (a menu that appears in
-all windows).
-Methods of menu objects are described below.
-\funcitem{fleep}{}
-%.br
-Causes a beep or bell (or perhaps a `visual bell' or flash, hence the
-name).
-\funcitem{message}{string}
-%.br
-Displays a dialog box containing the string.
-The user must click OK before the function returns.
-\funcitem{askync}{prompt, default}
-%.br
-Displays a dialog that prompts the user to answer a question with yes or
-no.
-The function returns 0 for no, 1 for yes.
-If the user hits the Return key, the default (which must be 0 or 1) is
-returned.
-If the user cancels the dialog, the
-{\tt KeyboardInterrupt}
-exception is raised.
-\funcitem{askstr}{prompt, default}
-%.br
-Displays a dialog that prompts the user for a string.
-If the user hits the Return key, the default string is returned.
-If the user cancels the dialog, the
-{\tt KeyboardInterrupt}
-exception is raised.
-\funcitem{askfile}{prompt, default, new}
-%.br
-Asks the user to specify a filename.
-If
-{\tt new}
-is zero it must be an existing file; otherwise, it must be a new file.
-If the user cancels the dialog, the
-{\tt KeyboardInterrupt}
-exception is raised.
-\funcitem{setcutbuffer}{i, string}
-%.br
-Stores the string in the system's cut buffer number
-{\tt i},
-where it can be found (for pasting) by other applications.
-On X11, there are 8 cut buffers (numbered 0..7).
-Cut buffer number 0 is the `clipboard' on the Macintosh.
-\funcitem{getcutbuffer}{i}
-%.br
-Returns the contents of the system's cut buffer number
-{\tt i}.
-\funcitem{rotatebutbuffers}{n}
-%.br
-On X11, this rotates the 8 cut buffers by
-{\tt n}.
-Ignored on the Macintosh.
-\funcitem{getselection}{i}
-%.br
-Returns X11 selection number
-{\tt i.}
-Selections are not cut buffers.
-Selection numbers are defined in module
-{\tt stdwinevents}.
-Selection {\tt WS\_PRIMARY} is the
-{\em primary}
-selection (used by
-xterm,
-for instance);
-selection {\tt WS\_SECONDARY} is the
-{\em secondary}
-selection; selection {\tt WS\_CLIPBOARD} is the
-{\em clipboard}
-selection (used by
-xclipboard).
-On the Macintosh, this always returns an empty string.
-\funcitem{resetselection}{i}
-%.br
-Resets selection number
-{\tt i},
-if this process owns it.
-(See window method
-{\tt setselection()}).
-\funcitem{baseline}{}
-%.br
-Return the baseline of the current font (defined by STDWIN as the
-vertical distance between the baseline and the top of the
-characters).%
-\footnote{
-There is no way yet to set the current font.
-This will change in a future version.
-}
-\funcitem{lineheight}{}
-%.br
-Return the total line height of the current font.
-\funcitem{textbreak}{str, width}
-%.br
-Return the number of characters of the string that fit into a space of
-{\tt width}
-bits wide when drawn in the curent font.
-\funcitem{textwidth}{str}
-%.br
-Return the width in bits of the string when drawn in the current font.
-\end{description}
-
-\subsubsection{Window Object Methods}
-
-Window objects are created by
-{\tt stdwin.open()}.
-There is no explicit function to close a window; windows are closed when
-they are garbage-collected.
-Window objects have the following methods:
-\begin{description}
-\funcitem{begindrawing}{}
-Returns a drawing object, whose methods (described below) allow drawing
-in the window.
-\funcitem{change}{rect}
-Invalidates the given rectangle; this may cause a draw event.
-\funcitem{gettitle}{}
-Returns the window's title string.
-\funcitem{getdocsize}{}
-\begin{sloppypar}
-Returns a pair of integers giving the size of the document as set by
-{\tt setdocsize()}.
-\end{sloppypar}
-\funcitem{getorigin}{}
-Returns a pair of integers giving the origin of the window with respect
-to the document.
-\funcitem{getwinsize}{}
-Returns a pair of integers giving the size of the window.
-\funcitem{menucreate}{title}
-Creates a menu object referring to a local menu (a menu that appears
-only in this window).
-Methods menu objects are described below.
-\funcitem{scroll}{rect,~point}
-Scrolls the given rectangle by the vector given by the point.
-\funcitem{setwincursor}{name}
-\begin{sloppypar}
-Sets the window cursor to a cursor of the given name.
-It raises the
-{\tt Runtime\-Error}
-exception if no cursor of the given name exists.
-Suitable names are
-{\tt 'ibeam'},
-{\tt 'arrow'},
-{\tt 'cross'},
-{\tt 'watch'}
-and
-{\tt 'plus'}.
-On X11, there are many more (see
-{\tt <X11/cursorfont.h>}).
-\end{sloppypar}
-\funcitem{setdocsize}{point}
-Sets the size of the drawing document.
-\funcitem{setorigin}{point}
-Moves the origin of the window to the given point in the document.
-\funcitem{setselection}{i, str}
-Attempts to set X11 selection number
-{\tt i}
-to the string
-{\tt str}.
-(See stdwin method
-{\tt getselection()}
-for the meaning of
-{\tt i}.)
-Returns true if it succeeds.
-If it succeeds, the window ``owns'' the selection until
-(a) another applications takes ownership of the selection; or
-(b) the window is deleted; or
-(c) the application clears ownership by calling
-{\tt stdwin.resetselection(i)}.
-When another application takes ownership of the selection, a
-{\tt WE\_LOST\_SEL}
-event is received for no particular window and with the selection number
-as detail.
-Ignored on the Macintosh.
-\funcitem{settitle}{title}
-Sets the window's title string.
-\funcitem{settimer}{dsecs}
-Schedules a timer event for the window in
-{\tt dsecs/10}
-seconds.
-\funcitem{show}{rect}
-Tries to ensure that the given rectangle of the document is visible in
-the window.
-\funcitem{textcreate}{rect}
-Creates a text-edit object in the document at the given rectangle.
-Methods of text-edit objects are described below.
-\end{description}
-
-\subsubsection{Drawing Object Methods}
-
-Drawing objects are created exclusively by the window method
-{\tt begindrawing()}.
-Only one drawing object can exist at any given time; the drawing object
-must be deleted to finish drawing.
-No drawing object may exist when
-{\tt stdwin.getevent()}
-is called.
-Drawing objects have the following methods:
-\begin{description}
-\funcitem{box}{rect}
-Draws a box around a rectangle.
-\funcitem{circle}{center, radius}
-%.br
-Draws a circle with given center point and radius.
-\funcitem{elarc(center, (rh, rv), }{a1, a2)}
-%.br
-Draws an elliptical arc with given center point.
-{\tt (rh, rv)}
-gives the half sizes of the horizontal and vertical radii.
-{\tt (a1, a2)}
-gives the angles (in degrees) of the begin and end points.
-0 degrees is at 3 o'clock, 90 degrees is at 12 o'clock.
-\funcitem{erase}{rect}
-Erases a rectangle.
-\funcitem{invert}{rect}
-Inverts a rectangle.
-\funcitem{line}{p1, p2}
-Draws a line from point
-{\tt p1}
-to
-{\tt p2}.
-\funcitem{paint}{rect}
-Fills a rectangle.
-\funcitem{text}{p, str}
-Draws a string starting at point p (the point specifies the
-top left coordinate of the string).
-\funcitem{shade}{rect, percent}
-%.br
-Fills a rectangle with a shading pattern that is about
-{\tt percent}
-percent filled.
-\funcitem{xorline}{p1, p2}
-Draws a line in XOR mode.
-\funcitem{baseline(), lineheight(), textbreak(), textwidth}{}
-%.br
-These functions are similar to the corresponding functions described
-above for the
-{\tt stdwin}
-module, but use the current font of the window instead of the (global)
-default font.
-\end{description}
-
-\subsubsection{Menu Object Methods}
-
-A menu object represents a menu.
-The menu is destroyed when the menu object is deleted.
-The following methods are defined:
-\begin{description}
-\funcitem{additem}{text, shortcut}
-%.br
-Adds a menu item with given text.
-The shortcut must be a string of length 1, or omitted (to specify no
-shortcut).
-\funcitem{setitem}{i, text}
-Sets the text of item number
-{\tt i}.
-\funcitem{enable}{i, flag}
-Enables or disables item
-{\tt i}.
-\funcitem{check}{i, flag}
-Sets or clears the
-{\em check mark}
-for item
-{\tt i}.
-\end{description}
-
-\subsubsection{Text-edit Object Methods}
-
-A text-edit object represents a text-edit block.
-For semantics, see the STDWIN documentation for C programmers.
-The following methods exist:
-\begin{description}
-\funcitem{arrow}{code}
-Passes an arrow event to the text-edit block.
-The
-{\tt code}
-must be one of
-{\tt WC\_LEFT},
-{\tt WC\_RIGHT},
-{\tt WC\_UP}
-or
-{\tt WC\_DOWN}
-(see module
-{\tt stdwinevents}).
-\funcitem{draw}{rect}
-Passes a draw event to the text-edit block.
-The rectangle specifies the redraw area.
-\funcitem{event}{type, window, detail}
-%.br
-Passes an event gotten from
-{\tt stdwin.getevent()}
-to the text-edit block.
-Returns true if the event was handled.
-\funcitem{getfocus}{}
-Returns 2 integers representing the start and end positions of the
-focus, usable as slice indices on the string returned by
-{\tt getfocustext()}.
-\funcitem{getfocustext}{}
-Returns the text in the focus.
-\funcitem{getrect}{}
-Returns a rectangle giving the actual position of the text-edit block.
-(The bottom coordinate may differ from the initial position because
-the block automatically shrinks or grows to fit.)
-\funcitem{gettext}{}
-Returns the entire text buffer.
-\funcitem{move}{rect}
-Specifies a new position for the text-edit block in the document.
-\funcitem{replace}{str}
-Replaces the focus by the given string.
-The new focus is an insert point at the end of the string.
-\funcitem{setfocus}{i,~j}
-Specifies the new focus.
-Out-of-bounds values are silently clipped.
-\end{description}
-
-\subsubsection{Example}
-
-Here is a simple example of using STDWIN in Python.
-It creates a window and draws the string ``Hello world'' in the top
-left corner of the window.
-The window will be correctly redrawn when covered and re-exposed.
-The program quits when the close icon or menu item is requested.
-\bcode\begin{verbatim}
-import stdwin
-from stdwinevents import *
-
-def main():
-    mywin = stdwin.open('Hello')
-    #
-    while 1:
-        (type, win, detail) = stdwin.getevent()
-        if type = WE_DRAW:
-            draw = win.begindrawing()
-            draw.text((0, 0), 'Hello, world')
-            del draw
-        elif type = WE_CLOSE:
-            break
-
-main()
-\end{verbatim}\ecode
-
-\subsection{Built-in Module {\tt amoeba}}
-
-This module provides some object types and operations useful for
-Amoeba applications.
-It is only available on systems that support Amoeba operations.
-RPC errors and other Amoeba errors are reported as the exception
-{\tt amoeba.error = 'amoeba.error'}.
-The module
-{\tt amoeba}
-defines the following items:
-\begin{description}
-\funcitem{name\_append}{path,~cap}
-%.br
-Stores a capability in the Amoeba directory tree.
-Arguments are the pathname (a string) and the capability (a capability
-object as returned by
-{\tt name\_lookup()}).
-\funcitem{name\_delete}{path}
-%.br
-Deletes a capability from the Amoeba directory tree.
-Argument is the pathname.
-\funcitem{name\_lookup}{path}
-%.br
-Looks up a capability.
-Argument is the pathname.
-Returns a
-{\em capability}
-object, to which various interesting operations apply, described below.
-\funcitem{name\_replace}{path,~cap}
-%.br
-Replaces a capability in the Amoeba directory tree.
-Arguments are the pathname and the new capability.
-(This differs from
-{\tt name\_append()}
-in the behavior when the pathname already exists:
-{\tt name\_append()}
-finds this an error while
-{\tt name\_replace()}
-allows it, as its name suggests.)
-\funcitem{capv}
-A table representing the capability environment at the time the
-interpreter was started.
-(Alas, modifying this table does not affect the capability environment
-of the interpreter.)
-For example,
-{\tt amoeba.capv['ROOT']}
-is the capability of your root directory, similar to
-{\tt getcap("ROOT")}
-in C.
-\excitem{error}{amoeba.error}
-%.br
-The exception raised when an Amoeba function returns an error.
-The value accompanying this exception is a pair containing the numeric
-error code and the corresponding string, as returned by the C function
-{\tt err\_why()}.
-\funcitem{timeout}{msecs}
-%.br
-Sets the transaction timeout, in milliseconds.
-Returns the previous timeout.
-Initially, the timeout is set to 2 seconds by the {\Python} interpreter.
-\end{description}
-
-\subsubsection{Capability Operations}
-
-Capabilities are written in a convenient ASCII format, also used by the
-Amoeba utilities
-{\em c2a}(U)
-and
-{\em a2c}(U).
-For example:
-\bcode\begin{verbatim}
->>> amoeba.name_lookup('/profile/cap')
-aa:1c:95:52:6a:fa/14(ff)/8e:ba:5b:8:11:1a
->>> 
-\end{verbatim}\ecode
-The following methods are defined for capability objects.
-\begin{description}
-\funcitem{dir\_list}{}
-Returns a list of the names of the entries in an Amoeba directory.
-\funcitem{b\_read}{offset, maxsize}
-%.br
-Reads (at most)
-{\tt maxsize}
-bytes from a bullet file at offset
-{\tt offset.}
-The data is returned as a string.
-EOF is reported as an empty string.
-\funcitem{b\_size}{}
-Returns the size of a bullet file.
-\funcitem{dir\_append(), dir\_delete(), dir\_lookup(), dir\_replace}{}
-%.br
-\itembreak
-Like the corresponding
-{\tt name\_*}
-functions, but with a path relative to the capability.
-(For paths beginning with a slash the capability is ignored, since this
-is the defined semantics for Amoeba.)
-\funcitem{std\_info}{}
-Returns the standard info string of the object.
-\funcitem{tod\_gettime}{}
-Returns the time (in seconds since the Epoch, in UCT, as for POSIX) from
-a time server.
-\funcitem{tod\_settime}{t}
-Sets the time kept by a time server.
-\end{description}
-
-\subsection{Built-in Module {\tt audio}}
-
-This module provides rudimentary access to the audio I/O device
-{\tt /dev/audio}
-on the Silicon Graphics Personal IRIS; see audio(7).
-It supports the following operations:
-\begin{description}
-\funcitem{setoutgain}{n}
-Sets the output gain (0-255).
-\funcitem{getoutgain}{}
-Returns the output gain.
-\funcitem{setrate}{n}
-Sets the sampling rate: 1=32K/sec, 2=16K/sec, 3=8K/sec.
-\funcitem{setduration}{n}
-Sets the `sound duration' in units of 1/100 seconds.
-\funcitem{read}{n}
-Reads a chunk of
-{\tt n}
-sampled bytes from the audio input (line in or microphone).
-The chunk is returned as a string of length n.
-Each byte encodes one sample as a signed 8-bit quantity using linear
-encoding.
-This string can be converted to numbers using {\tt chr2num()} described
-below.
-\funcitem{write}{buf}
-Writes a chunk of samples to the audio output (speaker).
-\end{description}
-
-These operations support asynchronous audio I/O:
-\begin{description}
-\funcitem{start\_recording}{n}
-%.br
-Starts a second thread (a process with shared memory) that begins reading
-{\tt n}
-bytes from the audio device.
-The main thread immediately continues.
-\funcitem{wait\_recording}{}
-%.br
-Waits for the second thread to finish and returns the data read.
-\funcitem{stop\_recording}{}
-%.br
-Makes the second thread stop reading as soon as possible.
-Returns the data read so far.
-\funcitem{poll\_recording}{}
-%.br
-Returns true if the second thread has finished reading (so
-{\tt wait\_recording()} would return the data without delay).
-\item[{\tt start\_playing(chunk)}, {\tt wait\_playing()},
-{\tt stop\_playing()}, {\tt poll\_playing()}]
-%.br
-\begin{sloppypar}
-Similar but for output.
-{\tt stop\_playing()}
-returns a lower bound for the number of bytes actually played (not very
-accurate).
-\end{sloppypar}
-\end{description}
-
-The following operations do not affect the audio device but are
-implemented in C for efficiency:
-\begin{description}
-\funcitem{amplify}{buf, f1, f2}
-%.br
-Amplifies a chunk of samples by a variable factor changing from
-{\tt f1}/256 to {\tt f2}/256.
-Negative factors are allowed.
-Resulting values that are to large to fit in a byte are clipped.         
-\funcitem{reverse}{buf}
-%.br
-Returns a chunk of samples backwards.
-\funcitem{add}{buf1, buf2}
-%.br
-Bytewise adds two chunks of samples.
-Bytes that exceed the range are clipped.
-If one buffer shorter, it is assumed to be padded with zeros.
-\funcitem{chr2num}{buf}
-%.br
-Converts a string of sampled bytes as returned by {\tt read()} into
-a list containing the numeric values of the samples.
-\funcitem{num2chr}{list}
-%.br
-\begin{sloppypar}
-Converts a list as returned by
-{\tt chr2num()}
-back to a buffer acceptable by
-{\tt write()}.
-\end{sloppypar}
-\end{description}
-
-\subsection{Built-in Module {\tt gl}}
-
-This module provides access to the Silicon Graphics
-{\em Graphics Library}.
-It is available only on Silicon Graphics machines.
-
-{\bf Warning:}
-Some illegal calls to the GL library cause the {\Python} interpreter to dump
-core.
-In particular, the use of most GL calls is unsafe before the first
-window is opened.
-
-The module is too large to document here in its entirety, but the
-following should help you to get started.
-The parameter conventions for the C functions are translated to {\Python} as
-follows:
-
-\begin{itemize}
-\item
-All (short, long, unsigned) int values are represented by {\Python}
-integers.
-\item
-All float and double values are represented by {\Python} floating point
-numbers.
-In most cases, {\Python} integers are also allowed.
-\item
-All arrays are represented by one-dimensional {\Python} lists.
-In most cases, tuples are also allowed.
-\item
-\begin{sloppypar}
-All string and character arguments are represented by {\Python} strings,
-for instance,
-{\tt winopen('Hi~There!')}
-and
-{\tt rotate(900,~'z')}.
-\end{sloppypar}
-\item
-All (short, long, unsigned) integer arguments or return values that are
-only used to specify the length of an array argument are omitted.
-For example, the C call
-\bcode\begin{verbatim}
-lmdef(deftype, index, np, props)
-\end{verbatim}\ecode
-is translated to {\Python} as
-\bcode\begin{verbatim}
-lmdef(deftype, index, props)
-\end{verbatim}\ecode
-\item
-Output arguments are omitted from the argument list; they are
-transmitted as function return values instead.
-If more than one value must be returned, the return value is a tuple.
-If the C function has both a regular return value (that is not omitted
-because of the previous rule) and an output argument, the return value
-comes first in the tuple.
-Examples: the C call
-\bcode\begin{verbatim}
-getmcolor(i, &red, &green, &blue)
-\end{verbatim}\ecode
-is translated to {\Python} as
-\bcode\begin{verbatim}
-red, green, blue = getmcolor(i)
-\end{verbatim}\ecode
-\end{itemize}
-
-The following functions are non-standard or have special argument
-conventions:
-\begin{description}
-\funcitem{varray}{}
-Equivalent to but faster than a number of
-{\tt v3d()}
-calls.
-The argument is a list (or tuple) of points.
-Each point must be a tuple of coordinates (x, y, z) or (x, y).
-The points may be 2- or 3-dimensional but must all have the
-same dimension.
-Float and int values may be mixed however.
-The points are always converted to 3D double precision points
-by assuming z=0.0 if necessary (as indicated in the man page),
-and for each point
-{\tt v3d()}
-is called.
-\funcitem{nvarray}{}
-Equivalent to but faster than a number of
-{\tt n3f}
-and
-{\tt v3f}
-calls.
-The argument is an array (list or tuple) of pairs of normals and points.
-Each pair is a tuple of a point and a normal for that point.
-Each point or normal must be a tuple of coordinates (x, y, z).
-Three coordinates must be given.
-Float and int values may be mixed.
-For each pair,
-{\tt n3f()}
-is called for the normal, and then
-{\tt v3f()}
-is called for the point.
-\funcitem{vnarray}{}
-Similar to 
-{\tt nvarray()}
-but the pairs have the point first and the normal second.
-\funcitem{nurbssurface}{s\_k[], t\_k[], ctl[][], s\_ord, t\_ord, type}
-%.br
-\itembreak
-Defines a nurbs surface.
-The dimensions of
-{\tt ctl[][]}
-are computed as follows:
-{\tt [len(s\_k)~-~s\_ord]},
-{\tt [len(t\_k)~-~t\_ord]}.
-\funcitem{nurbscurve}{knots, ctlpoints, order, type}
-%.br
-Defines a nurbs curve.
-The length of ctlpoints is
-{\tt len(knots)~-~order}.
-\funcitem{pwlcurve}{points, type}
-%.br
-Defines a piecewise-linear curve.
-{\tt points}
-is a list of points.
-{\tt type}
-must be
-{\tt N\_ST}.
-\funcitem{pick(n), select}{n}
-%.br
-The only argument to these functions specifies the desired size of the
-pick or select buffer.
-\funcitem{endpick(), endselect}{}
-%.br
-These functions have no arguments.
-They return a list of integers representing the used part of the
-pick/select buffer.
-No method is provided to detect buffer overrun.
-\end{description}
-
-Here is a tiny but complete example GL program in {\Python}:
-\bcode\begin{verbatim}
-import gl, GL, time
-
-def main():
-    gl.foreground()
-    gl.prefposition(500, 900, 500, 900)
-    w = gl.winopen('CrissCross')
-    gl.ortho2(0.0, 400.0, 0.0, 400.0)
-    gl.color(GL.WHITE)
-    gl.clear()
-    gl.color(GL.RED)
-    gl.bgnline()
-    gl.v2f(0.0, 0.0)
-    gl.v2f(400.0, 400.0)
-    gl.endline()
-    gl.bgnline()
-    gl.v2f(400.0, 0.0)
-    gl.v2f(0.0, 400.0)
-    gl.endline()
-    time.sleep(5)
-
-main()
-\end{verbatim}\ecode
-
-\subsection{Built-in Module {\tt pnl}}
-
-This module provides access to the
-{\em Panel Library}
-built by NASA Ames (to get it, send e-mail to
-{\tt panel-request@nas.nasa.gov}).
-All access to it should be done through the standard module
-{\tt panel},
-which transparantly exports most functions from
-{\tt pnl}
-but redefines
-{\tt pnl.dopanel()}.
-
-{\bf Warning:}
-the {\Python} interpreter will dump core if you don't create a GL window
-before calling
-{\tt pnl.mkpanel()}.
-
-The module is too large to document here in its entirety.
-
-\section{Standard Modules}
-
-The following standard modules are defined.
-They are available in one of the directories in the default module
-search path (try printing
-{\tt sys.path}
-to find out the default search path.)
-
-\subsection{Standard Module {\tt string}}
-
-This module defines some constants useful for checking character
-classes, some exceptions, and some useful string functions.
-The constants are:
-\begin{description}
-\funcitem{digits}
-The string
-{\tt '0123456789'}.
-\funcitem{hexdigits}
-The string
-{\tt '0123456789abcdefABCDEF'}.
-\funcitem{letters}
-The concatenation of the strings
-{\tt lowercase}
-and
-{\tt uppercase}
-described below.
-\funcitem{lowercase}
-The string
-{\tt 'abcdefghijklmnopqrstuvwxyz'}.
-\funcitem{octdigits}
-The string
-{\tt '01234567'}.
-\funcitem{uppercase}
-The string
-{\tt 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.
-\funcitem{whitespace}
-A string containing all characters that are considered whitespace,
-i.e.,
-space, tab and newline.
-This definition is used by
-{\tt split()}
-and
-{\tt strip()}.
-\end{description}
-
-The exceptions are:
-\begin{description}
-\excitem{atoi\_error}{non-numeric argument to string.atoi}
-%.br
-Exception raised by
-{\tt atoi}
-when a non-numeric string argument is detected.
-The exception argument is the offending string.
-\excitem{index\_error}{substring not found in string.index}
-%.br
-Exception raised by
-{\tt index}
-when
-{\tt sub}
-is not found.
-The argument are the offending arguments to index: {\tt (s, sub)}.
-\end{description}
-
-The functions are:
-\begin{description}
-\funcitem{atoi}{s}
-Converts a string to a number.
-The string must consist of one or more digits, optionally preceded by a
-sign ({\tt '+'} or {\tt '-'}).
-\funcitem{index}{s, sub}
-Returns the lowest index in
-{\tt s}
-where the substring
-{\tt sub}
-is found.
-\funcitem{lower}{s}
-Convert letters to lower case.
-\funcitem{split}{s}
-Returns a list of the whitespace-delimited words of the string
-{\tt s}.
-\funcitem{splitfields}{s, sep}
-%.br
-Returns a list containing the fields of the string
-{\tt s},
-using the string
-{\tt sep}
-as a separator.
-The list will have one more items than the number of non-overlapping
-occurrences of the separator in the string.
-Thus,
-{\tt string.splitfields(s, ' ')}
-is not the same as
-{\tt string.split(s)},
-as the latter only returns non-empty words.
-\funcitem{strip}{s}
-Removes leading and trailing whitespace from the string
-{\tt s}.
-\funcitem{swapcase}{s}
-Converts lower case letters to upper case and vice versa.
-\funcitem{upper}{s}
-Convert letters to upper case.
-\funcitem{ljust(s, width), rjust(s, width),  center}{s, width}
-%.br
-These functions respectively left-justify, right-justify and center a
-string in a field of given width.
-They return a string that is at least
-{\tt width}
-characters wide, created by padding the string
-{\tt s}
-with spaces until the given width on the right, left or both sides.
-The string is never truncated.
-\end{description}
-
-\subsection{Standard Module {\tt path}}
-
-This module implements some useful functions on POSIX pathnames.
-\begin{description}
-\funcitem{basename}{p}
-Returns the base name of pathname
-{\tt p}.
-This is the second half of the pair returned by
-{\tt path.split(p)}.
-\funcitem{cat}{p, q}
-Performs intelligent pathname concatenation on paths
-{\tt p}
-and
-{\tt q}:
-If
-{\tt q}
-is an absolute path, the return value is
-{\tt q}.
-Otherwise, the concatenation of
-{\tt p}
-and
-{\tt q}
-is returned, with a slash ({\tt '/'}) inserted unless
-{\tt p}
-is empty or ends in a slash.
-\funcitem{commonprefix}{list}
-%.br
-Returns the longest string that is a prefix of all strings in
-{\tt list}.
-If
-{\tt list}
-is empty, the empty string ({\tt ''}) is returned.
-\funcitem{exists}{p}
-Returns true if
-{\tt p}
-refers to an existing path.
-\funcitem{isdir}{p}
-Returns true if
-{\tt p}
-refers to an existing directory.
-\funcitem{islink}{p}
-Returns true if
-{\tt p}
-refers to a directory entry that is a symbolic link.
-Always false if symbolic links are not supported.
-\funcitem{ismount}{p}
-Returns true if
-{\tt p}
-is an absolute path that occurs in the mount table as output by the
-{\tt /etc/mount}
-utility.
-This output is read once when the function is used for the first
-time.%
-\footnote{
-Is there a better way to check for mount points?
-}
-\funcitem{split}{p}
-Returns a pair
-{\tt (head,~tail)}
-such that
-{\tt tail}
-contains no slashes and
-{\tt path.cat(head, tail)}
-is equal to
-{\tt p}.
-\funcitem{walk}{p, visit, arg}
-%.br
-Calls the function
-{\tt visit}
-with arguments
-{\tt (arg, dirname, names)}
-for each directory in the directory tree rooted at
-{\tt p}
-(including
-{\tt p}
-itself, if it is a directory).
-The argument
-{\tt dirname}
-specifies the visited directory, the argument
-{\tt names}
-lists the files in the directory (gotten from
-{\tt posix.listdir(dirname)}).
-The
-{\tt visit}
-function may modify
-{\tt names}
-to influence the set of directories visited below
-{\tt dirname},
-e.g.,
-to avoid visiting certain parts of the tree.
-(The object referred to by
-{\tt names}
-must be modified in place, using
-{\tt del}
-or slice assignment.)
-\end{description}
-
-\subsection{Standard Module {\tt getopt}}
-
-This module helps scripts to parse the command line arguments in
-{\tt sys.argv}.
-It uses the same conventions as the {\UNIX}
-{\tt getopt()}
-function.
-It defines the function
-{\tt getopt.getopt(args, options)}
-and the exception
-{\tt getopt.error}.
-
-The first argument to
-{\tt getopt()}
-is the argument list passed to the script with its first element
-chopped off (i.e.,
-{\tt sys.argv[1:]}).
-The second argument is the string of option letters that the
-script wants to recognize, with options that require an argument
-followed by a colon (i.e., the same format that {\UNIX}
-{\tt getopt()}
-uses).
-The return value consists of two elements: the first is a list of
-option-and-value pairs; the second is the list of program arguments
-left after the option list was stripped (this is a trailing slice of the
-first argument).
-Each option-and-value pair returned has the option as its first element,
-prefixed with a hyphen (e.g.,
-{\tt '-x'}),
-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.
-Example:
-\bcode\begin{verbatim}
->>> import getopt, string
->>> args = string.split('-a -b -cfoo -d bar a1 a2')
->>> 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}\ecode
-The exception
-{\tt getopt.error = 'getopt error'}
-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.
-
-\subsection{Standard Module {\tt rand}}
-
-This module implements a pseudo-random number generator similar to
-{\tt rand()}
-in C.
-It defines the following functions:
-\begin{description}
-\funcitem{rand}{}
-Returns an integer random number in the range [0 ... 32768).
-\funcitem{choice}{s}
-Returns a random element from the sequence (string, tuple or list)
-{\tt s.}
-\funcitem{srand}{seed}
-Initializes the random number generator with the given integral seed.
-When the module is first imported, the random number is initialized with
-the current time.
-\end{description}
-
-\subsection{Standard Module {\tt whrandom}}
-
-This module implements a Wichmann-Hill pseudo-random number generator.
-It defines the following functions:
-\begin{description}
-\funcitem{random}{}
-Returns the next random floating point number in the range [0.0 ... 1.0).
-\funcitem{seed}{x, y, z}
-Initializes the random number generator from the integers
-{\tt x},
-{\tt y}
-and
-{\tt z}.
-When the module is first imported, the random number is initialized
-using values derived from the current time.
-\end{description}
-
-\subsection{Standard Module {\tt stdwinevents}}
-
-This module defines constants used by STDWIN for event types
-({\tt WE\_ACTIVATE} etc.), command codes ({\tt WC\_LEFT} etc.)
-and selection types ({\tt WS\_PRIMARY} etc.).
-Read the file for details.
-Suggested usage is
-\bcode\begin{verbatim}
->>> from stdwinevents import *
->>> 
-\end{verbatim}\ecode
-
-\subsection{Standard Module {\tt rect}}
-
-This module contains useful operations on rectangles.
-A rectangle is defined as in module
-{\tt stdwin}:
-a pair of points, where a point is a pair of integers.
-For example, the rectangle
-\bcode\begin{verbatim}
-(10, 20), (90, 80)
-\end{verbatim}\ecode
-is a rectangle whose left, top, right and bottom edges are 10, 20, 90
-and 80, respectively.
-Note that the positive vertical axis points down (as in
-{\tt stdwin}).
-
-The module defines the following objects:
-\begin{description}
-\excitem{error}{rect.error}
-%.br
-The exception raised by functions in this module when they detect an
-error.
-The exception argument is a string describing the problem in more
-detail.
-\funcitem{empty}
-%.br
-The rectangle returned when some operations return an empty result.
-This makes it possible to quickly check whether a result is empty:
-\bcode\begin{verbatim}
->>> import rect
->>> r1 = (10, 20), (90, 80)
->>> r2 = (0, 0), (10, 20)
->>> r3 = rect.intersect(r1, r2)
->>> if r3 is rect.empty: print 'Empty intersection'
-Empty intersection
->>> 
-\end{verbatim}\ecode
-\funcitem{is\_empty}{r}
-%.br
-Returns true if the given rectangle is empty.
-A rectangle
-{\em (left,~top), (right,~bottom)}
-is empty if
-{\em left~$\geq$~right}
-or
-{\em top~$\leq$~bottom}.
-\funcitem{intersect}{list}
-%.br
-Returns the intersection of all rectangles in the list argument.
-It may also be called with a tuple argument or with two or more
-rectangles as arguments.
-Raises
-{\tt rect.error}
-if the list is empty.
-Returns
-{\tt rect.empty}
-if the intersection of the rectangles is empty.
-\funcitem{union}{list}
-%.br
-Returns the smallest rectangle that contains all non-empty rectangles in
-the list argument.
-It may also be called with a tuple argument or with two or more
-rectangles as arguments.
-Returns
-{\tt rect.empty}
-if the list is empty or all its rectangles are empty.
-\funcitem{pointinrect}{point, rect}
-%.br
-Returns true if the point is inside the rectangle.
-By definition, a point
-{\em (h,~v)}
-is inside a rectangle
-{\em (left,~top),}
-{\em (right,~bottom)}
-if
-{\em left~$\leq$~h~$<$~right}
-and
-{\em top~$\leq$~v~$<$~bottom}.
-\funcitem{inset(rect, }{dh, dv)}
-%.br
-Returns a rectangle that lies inside the
-{\tt rect}
-argument by
-{\tt dh}
-pixels horizontally
-and
-{\tt dv}
-pixels
-vertically.
-If
-{\tt dh}
-or
-{\tt dv}
-is negative, the result lies outside
-{\tt rect}.
-\funcitem{rect2geom}{rect}
-%.br
-Converts a rectangle to geometry representation:
-{\em (left,~top),}
-{\em (width,~height)}.
-\funcitem{geom2rect}{geom}
-%.br
-Converts a rectangle given in geometry representation back to the
-standard rectangle representation
-{\em (left,~top),}
-{\em (right,~bottom)}.
-\end{description}
-
-\subsection{Standard Modules {\tt GL} and {\tt DEVICE}}
-
-These modules define the constants used by the Silicon Graphics
-{\em Graphics Library}
-that C programmers find in the header files
-{\tt <gl/gl.h>}
-and
-{\tt <gl/device.h>}.
-Read the module files for details.
-
-\subsection{Standard Module {\tt panel}}
-
-This module should be used instead of the built-in module
-{\tt pnl}
-to interface with the
-{\em Panel Library}.
-
-The module is too large to document here in its entirety.
-One interesting function:
-\begin{description}
-\funcitem{defpanellist}{filename}
-%.br
-Parses a panel description file containing S-expressions written by the
-{\em Panel Editor}
-that accompanies the Panel Library and creates the described panels.
-It returns a list of panel objects.
-\end{description}
-
-{\bf Warning:}
-the {\Python} interpreter will dump core if you don't create a GL window
-before calling
-{\tt panel.mkpanel()}
-or
-{\tt panel.defpanellist()}.
-
-\subsection{Standard Module {\tt panelparser}}
-
-This module defines a self-contained parser for S-expressions as output
-by the Panel Editor (which is written in Scheme so it can't help writing
-S-expressions).
-The relevant function is
-{\tt panelparser.parse\_file(file)}
-which has a file object (not a filename!) as argument and returns a list
-of parsed S-expressions.
-Each S-expression is converted into a {\Python} list, with atoms converted
-to {\Python} strings and sub-expressions (recursively) to {\Python} lists.
-For more details, read the module file.
-
-\section{P.M.}
-
-\begin{verse}
-
-commands
-
-cmp?
-
-*cache?
-
-localtime?
-
-calendar?
-
-\_\_dict?
-
-mac?
-
-\end{verse}
+\input{mod1.tex}
+\input{mod2.tex}
+\input{mod3.tex}
 
 \end{document}
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 8e36427..f0b649a 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -55,2094 +55,8 @@ gives a more formal reference to the language.
 
 \pagenumbering{arabic}
 
-\section{Introduction}
-
-The {\Python} library consists of three parts, with different levels of
-integration with the interpreter.
-Closest to the interpreter are built-in types, exceptions and functions.
-Next are built-in modules, which are written in C and linked statically
-with the interpreter.
-Finally there are standard modules that are implemented entirely in
-{\Python}, but are always available.
-For efficiency, some standard modules may become built-in modules in
-future versions of the interpreter.
-
-\section{Built-in Types, Exceptions and Functions}
-
-Names for built-in exceptions and functions are found in a separate
-read-only symbol table which cannot be modified.
-This table is searched last, so local and global user-defined names can
-override built-in names.
-Built-in types have no names but are created by syntactic constructs
-(such as constants) or built-in functions.
-They are described together here for easy reference.%
-\footnote{
-The descriptions sorely lack explanations of the exceptions that
-may be raised---this will be fixed in a future version of this
-document.
-}
-
-\subsection{Built-in Types}
-
-The following sections describe the standard types that are built into the
-interpreter.
-\subsubsection{Numeric Types}
-
-There are two numeric types: integers and floating point numbers.
-Integers are implemented using {\tt long} in C, so they have at least 32
-bits of precision.
-Floating point numbers are implemented using {\tt double} in C.
-All bets on precision are off.
-Numbers are created by numeric constants or as the result of built-in
-functions and operators.
-
-Numeric types support the following operations:
-
-\begin{center}
-\begin{tabular}{|c|l|c|}
-\hline
-Operation & Result & Notes \\
-\hline
-{\tt abs}({\em x}) & absolute value of {\em x} & \\
-{\tt int}({\em x}) & {\em x} converted to integer & (1) \\
-{\tt float}({\em x}) & {\em x} converted to floating point & \\
-{\tt -}{\em x} & {\em x} negated & \\
-{\tt +}{\em x} & {\em x} unchanged & \\
-{\em x}{\tt +}{\em y} & sum of {\em x} and {\em y} & \\
-{\em x}{\tt -}{\em y} & difference of {\em x} and {\em y} & \\
-{\em x}{\tt *}{\em y} & product of {\em x} and {\em y} & \\
-{\em x}{\tt /}{\em y} & quotient of {\em x} and {\em y} & (2) \\
-{\em x}{\tt \%}{\em y} & remainder of {\em x}{\tt /}{\em y} & (3) \\
-\hline
-\end{tabular}
-\end{center}
-
-\noindent
-Notes:
-\begin{description}
-\item[(1)]
-This may round or truncate as in C; see functions {\tt floor} and
-{\tt ceil} in module {\tt math}.
-\item[(2)]
-Integer division is defined as in C: the result is an integer; with
-positive operands, it truncates towards zero; with a negative operand,
-the result is unspecified.
-\item[(3)]
-Only defined for integers.
-\end{description}
-
-Mixed arithmetic is not supported; both operands must have the same type.
-Mixed comparisons return the wrong result (floats always compare smaller
-than integers).%
-\footnote{
-These restrictions are bugs in the language definitions and will be
-fixed in the future.
-}
-\subsubsection{Sequence Types}
-
-There are three sequence types: strings, lists and tuples.
-Strings constants are written in single quotes: {\tt 'xyzzy'}.
-Lists are constructed with square brackets: {\tt [a,~b,~c]}.
-Tuples are constructed by the comma operator or with an empty set of
-parentheses: {\tt a,~b,~c} or {\tt ()}.
-
-Sequence types support the following operations ({\em s} and {\em t} are
-sequences of the same type; {\em n}, {\em i} and {\em j} are integers):
-
-\begin{center}
-\begin{tabular}{|c|l|c|}
-\hline
-Operation & Result & Notes \\
-\hline
-{\tt len}({\em s}) & length of {\em s} & \\
-{\tt min}({\em s}) & smallest item of {\em s} & \\
-{\tt max}({\em s}) & largest item of {\em s} & \\
-{\em x} {\tt in} {\em s} &
-	true if an item of {\em s} is equal to {\em x} & \\
-{\em x} {\tt not} {\tt in} {\em s} &
-	false if an item of {\em s} is equal to {\em x} & \\
-{\em s}{\tt +}{\em t} & the concatenation of {\em s} and {\em t} & \\
-{\em s}{\tt *}{\em n}, {\em n}*{\em s} &
-	{\em n} copies of {\em s} concatenated & (1) \\
-{\em s}[{\em i}] & {\em i}'th item of {\em s} & \\
-{\em s}[{\em i}:{\em j}] &
-	slice of {\em s} from {\em i} to {\em j} & (2) \\
-\hline
-\end{tabular}
-\end{center}
-
-\noindent
-Notes:
-\begin{description}
-\item[(1)]
-Sequence repetition is only supported for strings.
-\item[(2)]
-The slice of $s$ from $i$ to $j$ is defined as the sequence
-of items with index $k$ such that $i \leq k < j$.
-Special rules apply for negative and omitted indices; see the Tutorial
-or the Reference Manual.
-\end{description}
-
-\paragraph{Mutable Sequence Types.}
-
-List objects support additional operations that allow in-place
-modification of the object.
-These operations would be supported by other mutable sequence types
-(when added to the language) as well.
-Strings and tuples are immutable sequence types and such objects cannot
-be modified once created.
-The following operations are defined on mutable sequence types (where
-{\em x} is an arbitrary object):
-
-\begin{center}
-\begin{tabular}{|c|l|}
-\hline
-Operation & Result \\
-\hline
-{\em s}[{\em i}] = {\em x} &
-	item {\em i} of {\em s} is replaced by {\em x} \\
-{\em s}[{\em i}:{\em j}] = {\em t} &
-	slice of {\em s} from {\em i} to {\em j} is replaced by {\em t} \\
-{\tt del} {\em s}[{\em i}:{\em j}] &
-	same as {\em s}[{\em i}:{\em j}] = [] \\
-{\em s}.{\tt append}({\em x}) &
-	same as {\em s}[{\tt len}({\em x}):{\tt len}({\em x})] = [{\em x}] \\
-{\em s}.{\tt insert}({\em i}, {\em x}) &
-	same as {\em s}[{\em i}:{\em i}] = [{\em x}] \\
-{\em s}.{\tt sort}() &
-	the items of {\em s} are permuted to satisfy \\
-	&
-	$s[i] \leq s[j]$ for $i < j$\\
-\hline
-\end{tabular}
-\end{center}
-
-\subsubsection{Mapping Types}
-
-A
-{\em mapping}
-object maps values of one type (the key type) to arbitrary objects.
-Mappings are mutable objects.
-There is currently only one mapping type, the
-{\em dictionary}.
-A dictionary's keys are strings.
-An empty dictionary is created by the expression \verb"{}".
-An extension of this notation is used to display dictionaries when
-written (see the example below).
-
-The following operations are defined on mappings (where {\em a} is a
-mapping, {\em k} is a key and {\em x} is an arbitrary object):
-
-\begin{center}
-\begin{tabular}{|c|l|c|}
-\hline
-Operation & Result & Notes\\
-\hline
-{\tt len}({\em a}) & the number of elements in {\em a} & \\
-{\em a}[{\em k}] & the item of {\em a} with key {\em k} & \\
-{\em a}[{\em k}] = {\em x} & set {\em a}[{\em k}] to {\em x} & \\
-{\tt del} {\em a}[{\em k}] & remove {\em a}[{\em k}] from {\em a} & \\
-{\em a}.{\tt keys}() & a copy of {\em a}'s list of keys & (1) \\
-{\em a}.{\tt has\_key}({\em k}) & true if {\em a} has a key {\em k} & \\
-\hline
-\end{tabular}
-\end{center}
-
-\noindent
-Notes:
-\begin{description}
-\item[(1)]
-Keys are listed in random order.
-\end{description}
-
-A small example using a dictionary:
-\bcode\begin{verbatim}
->>> tel = {}
->>> tel['jack'] = 4098
->>> tel['sape'] = 4139
->>> tel['guido'] = 4127
->>> tel['jack']
-4098
->>> tel
-{'sape': 4139; 'guido': 4127; 'jack': 4098}
->>> del tel['sape']
->>> tel['irv'] = 4127
->>> tel
-{'guido': 4127; 'irv': 4127; 'jack': 4098}
->>> tel.keys()
-['guido', 'irv', 'jack']
->>> tel.has_key('guido')
-1
->>> 
-\end{verbatim}\ecode
-\subsubsection{Other Built-in Types}
-
-The interpreter supports several other kinds of objects.
-Most of these support only one or two operations.
-
-\paragraph{Modules.}
-
-The only operation on a module is member acces: {\em m}{\tt .}{\em name},
-where {\em m} is a module and {\em name} accesses a name defined in
-{\em m}'s symbol table.
-Module members can be assigned to.
-
-\paragraph{Classes and Class Objects.}
-
-XXX Classes will be explained at length in a later version of this
-document.
-
-\paragraph{Functions.}
-
-Function objects are created by function definitions.
-The only operation on a function object is to call it:
-{\em func}({\em optional-arguments}).
-
-Built-in functions have a different type than user-defined functions,
-but they support the same operation.
-
-\paragraph{Methods.}
-
-Methods are functions that are called using the member acces notation.
-There are two flavors: built-in methods (such as {\tt append()} on
-lists) and class member methods.
-Built-in methods are described with the types that support them.
-XXX Class member methods will be described in a later version of this
-document.
-
-\paragraph{Type Objects.}
-
-Type objects represent the various object types.
-An object's type is accessed by the built-in function
-{\tt type()}.
-There are no operations on type objects.
-
-\paragraph{The Null Object.}
-
-This object is returned by functions that don't explicitly return a
-value.
-It supports no operations.
-There is exactly one null object, named {\tt None}
-(a built-in name).
-
-\paragraph{File Objects.}
-
-File objects are implemented using C's
-{\em stdio}
-package and can be created with the built-in function
-{\tt open()}.
-They have the following methods:
-\begin{description}
-\funcitem{close}{}
-Closes the file.
-A closed file cannot be read or written anymore.
-\funcitem{read}{size}
-Reads at most
-{\tt size}
-bytes from the file (less if the read hits EOF).
-The bytes are returned as a string object.
-An empty string is returned when EOF is hit immediately.
-(For certain files, like ttys, it makes sense to continue reading after
-an EOF is hit.)
-\funcitem{readline}{size}
-Reads a line of at most
-{\tt size}
-bytes from the file.
-A trailing newline character, if present, is kept in the string.
-The size is optional and defaults to a large number (but not infinity).
-EOF is reported as by
-{\tt read().}
-\funcitem{write}{str}
-Writes a string to the file.
-Returns no value.
-\end{description}
-
-\subsection{Built-in Exceptions}
-
-The following exceptions can be generated by the interpreter or
-built-in functions.
-Except where mentioned, they have a string argument (also known as the
-`associated value' of an exception) indicating the detailed cause of the
-error.
-The strings listed with the exception names are their values when used
-in an expression or printed.
-\begin{description}
-\excitem{EOFError}{end-of-file read}
-(No argument.)
-Raised when a built-in function ({\tt input()} or {\tt raw\_input()})
-hits an end-of-file condition (EOF) without reading any data.
-(N.B.: the {\tt read()} and {\tt readline()} methods of file objects
-return an empty string when they hit EOF.)
-\excitem{KeyboardInterrupt}{end-of-file read}
-(No argument.)
-Raised when the user hits the interrupt key (normally Control-C or DEL).
-During execution, a check for interrupts is made regularly.
-Interrupts typed when a built-in function ({\tt input()} or
-{\tt raw\_input()}) is waiting for input also raise this exception.
-\excitem{MemoryError}{out of memory}
-%.br
-Raised when an operation runs out of memory but the situation
-may still be rescued (by deleting some objects).
-\excitem{NameError}{undefined name}
-%.br
-Raised when a name is not found.
-This applies to unqualified names, module names (on {\tt import}),
-module members and object methods.
-The string argument is the name that could not be found.
-\excitem{RuntimeError}{run-time error}
-%.br
-Raised for a variety of reasons, e.g., division by zero or index out of
-range.
-\excitem{SystemError}{system error}
-%.br
-Raised when the interpreter finds an internal error, but the situation
-does not look so serious to cause it to abandon all hope.
-\excitem{TypeError}{type error}
-%.br
-Raised when an operation or built-in function is applied to an object of
-inappropriate type.
-\end{description}
-
-\subsection{Built-in Functions}
-
-The {\Python} interpreter has a small number of functions built into it that
-are always available.
-They are listed here in alphabetical order.
-\begin{description}
-\funcitem{abs}{x}
-Returns the absolute value of a number.
-The argument may be an integer or floating point number.
-\funcitem{chr}{i}
-Returns a string of one character
-whose ASCII code is the integer {\tt i},
-e.g., {\tt chr(97)} returns the string {\tt 'a'}.
-This is the inverse of {\tt ord()}.
-\funcitem{dir}{}
-Without arguments, this function returns the list of names in the
-current local symbol table, sorted alphabetically.
-With a module object as argument, it returns the sorted list of names in
-that module's global symbol table.
-For example:
-\bcode\begin{verbatim}
->>> import sys
->>> dir()
-['sys']
->>> dir(sys)
-['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout']
->>> 
-\end{verbatim}\ecode
-\funcitem{divmod}{a, b}
-%.br
-Takes two integers as arguments and returns a pair of integers
-consisting of their quotient and remainder.
-For
-\bcode\begin{verbatim}
-q, r = divmod(a, b)
-\end{verbatim}\ecode
-the invariants are:
-\bcode\begin{verbatim}
-a = q*b + r
-abs(r) < abs(b)
-r has the same sign as b
-\end{verbatim}\ecode
-For example:
-\bcode\begin{verbatim}
->>> divmod(100, 7)
-(14, 2)
->>> divmod(-100, 7)
-(-15, 5)
->>> divmod(100, -7)
-(-15, -5)
->>> divmod(-100, -7)
-(14, -2)
->>> 
-\end{verbatim}\ecode
-\funcitem{eval}{s}
-Takes a string as argument and parses and evaluates it as a {\Python}
-expression.
-The expression is executed using the current local and global symbol
-tables.
-Syntax errors are reported as exceptions.
-For example:
-\bcode\begin{verbatim}
->>> x = 1
->>> eval('x+1')
-2
->>> 
-\end{verbatim}\ecode
-\funcitem{exec}{s}
-Takes a string as argument and parses and evaluates it as a sequence of
-{\Python} statements.
-The string should end with a newline (\verb"'\n'").
-The statement is executed using the current local and global symbol
-tables.
-Syntax errors are reported as exceptions.
-For example:
-\bcode\begin{verbatim}
->>> x = 1
->>> exec('x = x+1\n')
->>> x
-2
->>> 
-\end{verbatim}\ecode
-\funcitem{float}{x}
-Converts a number to floating point.
-The argument may be an integer or floating point number.
-\funcitem{input}{s}
-Equivalent to
-{\tt eval(raw\_input(s))}.
-As for
-{\tt raw\_input()},
-the argument is optional.
-\funcitem{int}{x}
-Converts a number to integer.
-The argument may be an integer or floating point number.
-\funcitem{len}{s}
-Returns the length (the number of items) of an object.
-The argument may be a sequence (string, tuple or list) or a mapping
-(dictionary).
-\funcitem{max}{s}
-Returns the largest item of a non-empty sequence (string, tuple or list).
-\funcitem{min}{s}
-Returns the smallest item of a non-empty sequence (string, tuple or list).
-\funcitem{open}{name, mode}
-%.br
-Returns a file object (described earlier under Built-in Types).
-The string arguments are the same as for stdio's
-{\tt fopen()}:
-{\tt 'r'}
-opens the file for reading,
-{\tt 'w'}
-opens it for writing (truncating an existing file),
-{\tt 'a'}
-opens it for appending.%
-\footnote{
-This function should go into a built-in module
-{\tt io}.
-}
-\funcitem{ord}{c}
-Takes a string of one character and returns its
-ASCII value, e.g., {\tt ord('a')} returns the integer {\tt 97}.
-This is the inverse of {\tt chr()}.
-\funcitem{range}{}
-This is a versatile function to create lists containing arithmetic
-progressions of integers.
-With two integer arguments, it returns the ascending sequence of
-integers starting at the first and ending one before the second
-argument.
-A single argument is used as the end point of the sequence, with 0 used
-as the starting point.
-A third argument specifies the step size; negative steps are allowed and
-work as expected, but don't specify a zero step.
-The resulting list may be empty.
-For example:
-\bcode\begin{verbatim}
->>> range(10)
-[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
->>> range(1, 1+10)
-[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
->>> range(0, 30, 5)
-[0, 5, 10, 15, 20, 25]
->>> range(0, 10, 3)
-[0, 3, 6, 9]
->>> range(0, -10, -1)
-[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
->>> range(0)
-[]
->>> range(1, 0)
-[]
->>> 
-\end{verbatim}\ecode
-\funcitem{raw\_input}{s}
-%.br
-The argument is optional; if present, it is written to standard output
-without a trailing newline.
-The function then reads a line from input, converts it to a string
-(stripping a trailing newline), and returns that.
-EOF is reported as an exception.
-For example:
-\bcode\begin{verbatim}
->>> raw_input('Type anything: ')
-Type anything: Mutant Teenage Ninja Turtles
-'Mutant Teenage Ninja Turtles'
->>> 
-\end{verbatim}\ecode
-\funcitem{reload}{module}
-Causes an already imported module to be re-parsed and re-initialized.
-This is useful if you have edited the module source file and want to
-try out the new version without leaving {\Python}.
-\funcitem{type}{x}
-Returns the type of an object.
-Types are objects themselves:
-the type of a type object is its own type.
-\end{description}
-
-\section{Built-in Modules}
-
-The modules described in this section are built into the interpreter.
-They must be imported using
-{\tt import}.
-Some modules are not always available; it is a configuration option to
-provide them.
-Details are listed with the descriptions, but the best way to see if
-a module exists in a particular implementation is to attempt to import
-it.
-
-\subsection{Built-in Module {\tt sys}}
-
-This module provides access to some variables used or maintained by the
-interpreter and to functions that interact strongly with the interpreter.
-It is always available.
-\begin{description}
-\funcitem{argv}
-The list of command line arguments passed to a {\Python} script.
-{\tt sys.argv[0]}
-is the script name.
-If no script name was passed to the {\Python} interpreter,
-{\tt sys.argv}
-is empty.
-\funcitem{exit}{n}
-Exits from {\Python} with numeric exit status
-{\tt n}.
-This closes all open files and performs other cleanup-actions required by
-the interpreter (but
-{\em finally clauses}
-of
-{\tt try}
-statements are not executed!).
-\funcitem{modules}
-Gives the list of modules that have already been loaded.
-This can be manipulated to force reloading of modules and other tricks.
-\funcitem{path}
-A list of strings that specifies the search path for modules.
-Initialized from the environment variable {\tt PYTHONPATH}, or an
-installation-dependent default.
-\funcitem{ps1,~ps2}
-Strings specifying the primary and secondary prompt of the interpreter.
-These are only defined if the interpreter is in interactive mode.
-Their initial values in this case are
-{\tt '>>> '}
-and
-{\tt '... '}.
-\funcitem{stdin, stdout, stderr}
-%.br
-File objects corresponding to the interpreter's standard input, output
-and error streams.
-{\tt sys.stdin}
-is used for all interpreter input except for scripts but including calls
-to
-{\tt input()}
-and
-{\tt raw\_input()}.
-{\tt sys.stdout}
-is used for the output of
-{\tt print} and expression statements
-and for the prompts of
-{\tt input()}
-and
-{\tt raw\_input()}.
-The interpreter's own prompts and its error messages are written to
-stderr.
-Assigning to
-{\tt sys.stderr}
-has no effect on the interpreter; it can be used to write error messages
-to stderr using
-{\tt print}.
-\end{description}
-
-\subsection{Built-in Module {\tt math}}
-
-This module is always available.
-It provides access to the mathematical functions defined by the C
-standard.
-They are:
-{\tt acos(x)},
-{\tt asin(x)},
-{\tt atan(x)},
-{\tt atan2(x,y)},
-{\tt ceil(x)},
-{\tt cos(x)},
-{\tt cosh(x)},
-{\tt exp(x)},
-{\tt fabs(x)},
-{\tt floor(x)},
-%{\tt fmod(...)}  XXX not yet
-%{\tt frexp(...)} XXX not yet
-%{\tt ldexp(...)} XXX not yet
-{\tt log(x)},
-{\tt log10(x)},
-%{\tt modf(...)}  XXX not yet
-{\tt pow(x,y)},
-{\tt sin(x)},
-{\tt sinh(x)},
-{\tt sqrt(x)},
-{\tt tan(x)},
-{\tt tanh(x)}.
-
-It also defines two mathematical constants:
-{\tt pi}
-and
-{\tt e}.
-
-\subsection{Built-in Module {\tt time}}
-
-This module provides various time-related functions.
-It is always available.
-Functions are:
-\begin{description}
-\funcitem{sleep}{secs}
-Suspends execution for the given number of seconds.
-\funcitem{time}{}
-Returns the time in seconds since the Epoch (Thursday January 1,
-00:00:00, 1970 UCT on \UNIX\ machines).
-\end{description}
-
-\noindent
-In some versions (Amoeba, Mac) the following functions also exist:
-\begin{description}
-\funcitem{millisleep}{msecs}
-Suspends execution for the given number of milliseconds.
-\funcitem{millitimer}{}
-Returns the number of milliseconds of real time elapsed since some point
-in the past that is fixed per execution of the python interpreter (but
-may change in each following run).
-\end{description}
-
-\noindent
-The granularity of the milliseconds functions may be more than a
-millisecond (100 msecs on Amoeba, 1/60 sec on the Mac).
-
-\subsection{Built-in Module {\tt regexp}}
-
-This module provides a regular expression matching operation.
-It is always available.
-
-The module defines a function and an exception:
-
-\begin{description}
-
-\funcitem{compile}{pattern}
-
-Compile a regular expression given as a string into a regular
-expression object.
-The string must be an egrep-style regular expression;
-this means that the characters {\tt '(' ')' '*' '+' '?' '|' '^' '$'}
-are special.
-(It is implemented using Henry Spencer's regular expression matching
-functions.)
-
-excitem{error}{regexp.error}
-
-Exception raised when a string passed to {\tt compile()} is not a
-valid regular expression (e.g., unmatched parentheses) or when some other
-error occurs during compilation or matching
-(``no match found'' is not an error).
-
-\end{description}
-
-Compiled regular expression objects support a single method:
-
-\begin{description}
-
-\funcitem{exec}{str}
-
-Find the first occurrence of the compiled regular expression in the
-string {\tt str}.
-The return value is a tuple of pairs specifying where a match was
-found and where matches were found for subpatterns specified with
-{\tt '('} and {\tt ')'} in the pattern.
-If no match is found, an empty tuple is returned; otherwise the first
-item of the tuple is a pair of slice indices into the search string
-giving the match found.
-If there were any subpatterns in the pattern, the returned tuple has an
-additional item for each subpattern, giving the slice indices into the
-search string where that subpattern was found.
-
-\end{description}
-
-For example:
-\bcode\begin{verbatim}
->>> import regexp
->>> r = regexp.compile('--(.*)--')
->>> s = 'a--b--c'
->>> r.exec(s)
-((1, 6), (3, 4))
->>> s[1:6] # The entire match
-'--b--'
->>> s[3:4] # The subpattern
-'b'
->>> 
-\end{verbatim}\ecode
-
-\subsection{Built-in Module {\tt posix}}
-
-This module provides access to operating system functionality that is
-standardized by the C Standard and the POSIX standard (a thinly diguised
-{\UNIX} interface).
-It is available in all {\Python} versions except on the Macintosh.
-Errors are reported exceptions.
-It defines the following items:
-\begin{description}
-\funcitem{chdir}{path}
-Changes the current directory to
-{\tt path}.
-\funcitem{chmod}{path, mode}
-Change the mode of
-{\tt path}
-to the numeric
-{\tt mode}.
-\funcitem{environ}
-A dictionary representing the string environment at the time
-the interpreter was started.
-(Modifying this dictionary does not affect the string environment of the
-interpreter.)
-For example,
-{\tt posix.environ['HOME']}
-is the pathname of your home directory, equivalent to
-{\tt getenv("HOME")}
-in C.
-\excitem{error}{posix.error}
-%.br
-The exception raised when an POSIX function returns an error.
-The value accompanying this exception is a pair containing the numeric
-error code from
-{\tt errno}
-and the corresponding string, as would be printed by the C function
-{\tt perror()}.
-\funcitem{getcwd}{}
-Returns a string representing the current working directory.
-\funcitem{link}{src, dst}
-Creates a hard link pointing to
-{\tt src}
-named
-{\tt dst}.
-\funcitem{listdir}{path}
-Returns a list containing the names of the entries in the
-directory.
-The list is in arbitrary order.
-It includes the special entries
-{\tt '.'}
-and
-{\tt '..'}
-if they are present in the directory.
-\funcitem{mkdir}{path, mode}
-Creates a directory named
-{\tt path}
-with numeric mode
-{\tt mode}.
-\funcitem{rename}{src, dst}
-Renames the file or directory
-{\tt src}
-to
-{\tt dst}.
-\funcitem{rmdir}{path}
-Removes the directory
-{\tt path}.
-\funcitem{stat}{path}
-Performs a
-{\em stat}
-system call on the given path.
-The return value is a tuple of at least 10 integers giving the most
-important (and portable) members of the
-{\em stat}
-structure, in the order
-{\tt st\_mode},
-{\tt st\_ino},
-{\tt st\_dev},
-{\tt st\_nlink},
-{\tt st\_uid},
-{\tt st\_gid},
-{\tt st\_size},
-{\tt st\_atime},
-{\tt st\_mtime},
-{\tt st\_ctime}.
-More items may be added at the end by some implementations.
-\funcitem{system}{command}
-Executes the command (a string) in a subshell.
-This is implemented by calling the Standard C function
-{\tt system()},
-and has the same limitations.
-Changes to
-{\tt posix.environ},
-{\tt sys.stdin}
-etc. are not reflected in the environment of the executed command.
-The return value is the exit status of the process as returned by
-Standard C
-{\tt system()}.
-\funcitem{umask}{mask}
-Sets the current numeric umask and returns the previous umask.
-\funcitem{unlink}{path}
-Unlinks the file
-{\tt path}.
-\funcitem{utimes(path, }{atime, mtime)}
-%.br
-Sets the access and modified time of the file to the given values.
-(The second argument is a tuple of two items.)
-\end{description}
-
-The following functions are only available on systems that support
-symbolic links:
-\begin{description}
-\funcitem{lstat}{path}
-Like
-{\tt stat()},
-but does not follow symbolic links.
-\funcitem{readlink}{path}
-Returns a string representing the path to which the symbolic link
-points.
-\funcitem{symlink}{src, dst}
-Creates a symbolic link pointing to
-{\tt src}
-named
-{\tt dst}.
-\end{description}
-
-\subsection{Built-in Module {\tt stdwin}}
-
-This module defines several new object types and functions that
-provide access to the functionality of the Standard Window System
-Interface, STDWIN [CWI report CR-R8817].
-It is available on systems to which STDWIN has been ported (which is
-most systems).
-It is only available if the {\tt DISPLAY} environment variable is set
-or an explicit `{\tt -display \it displayname}' argument is passed to
-the interpreter.
-
-Functions have names that usually resemble their C STDWIN counterparts
-with the initial `w' dropped.
-Points are represented by pairs of integers; rectangles
-by pairs of points.
-For a complete description of STDWIN please refer to the documentation
-of STDWIN for C programmers (aforementioned CWI report).
-\subsubsection{Functions Defined in Module {\tt stdwin}}
-
-The following functions are defined in the {\tt stdwin} module:
-\begin{description}
-\funcitem{open}{title}
-%.br
-Opens a new window whose initial title is given by the string argument.
-Returns a window object; window object methods are described below.%
-\footnote{
-The {\Python} version of STDWIN does not support draw procedures; all
-drawing requests are reported as draw events.
-}
-\funcitem{getevent}{}
-%.br
-Waits for and returns the next event.
-An event is returned as a triple: the first element is the event
-type, a small integer; the second element is the window object to which
-the event applies, or
-{\tt None}
-if it applies to no window in particular;
-the third element is type-dependent.
-Names for event types and command codes are defined in the standard
-module
-{\tt stdwinevent}.
-\funcitem{setdefwinpos}{h, v}
-%.br
-Sets the default window position.
-\funcitem{setdefwinsize}{width, height}
-%.br
-Sets the default window size.
-\funcitem{menucreate}{title}
-%.br
-Creates a menu object referring to a global menu (a menu that appears in
-all windows).
-Methods of menu objects are described below.
-\funcitem{fleep}{}
-%.br
-Causes a beep or bell (or perhaps a `visual bell' or flash, hence the
-name).
-\funcitem{message}{string}
-%.br
-Displays a dialog box containing the string.
-The user must click OK before the function returns.
-\funcitem{askync}{prompt, default}
-%.br
-Displays a dialog that prompts the user to answer a question with yes or
-no.
-The function returns 0 for no, 1 for yes.
-If the user hits the Return key, the default (which must be 0 or 1) is
-returned.
-If the user cancels the dialog, the
-{\tt KeyboardInterrupt}
-exception is raised.
-\funcitem{askstr}{prompt, default}
-%.br
-Displays a dialog that prompts the user for a string.
-If the user hits the Return key, the default string is returned.
-If the user cancels the dialog, the
-{\tt KeyboardInterrupt}
-exception is raised.
-\funcitem{askfile}{prompt, default, new}
-%.br
-Asks the user to specify a filename.
-If
-{\tt new}
-is zero it must be an existing file; otherwise, it must be a new file.
-If the user cancels the dialog, the
-{\tt KeyboardInterrupt}
-exception is raised.
-\funcitem{setcutbuffer}{i, string}
-%.br
-Stores the string in the system's cut buffer number
-{\tt i},
-where it can be found (for pasting) by other applications.
-On X11, there are 8 cut buffers (numbered 0..7).
-Cut buffer number 0 is the `clipboard' on the Macintosh.
-\funcitem{getcutbuffer}{i}
-%.br
-Returns the contents of the system's cut buffer number
-{\tt i}.
-\funcitem{rotatebutbuffers}{n}
-%.br
-On X11, this rotates the 8 cut buffers by
-{\tt n}.
-Ignored on the Macintosh.
-\funcitem{getselection}{i}
-%.br
-Returns X11 selection number
-{\tt i.}
-Selections are not cut buffers.
-Selection numbers are defined in module
-{\tt stdwinevents}.
-Selection {\tt WS\_PRIMARY} is the
-{\em primary}
-selection (used by
-xterm,
-for instance);
-selection {\tt WS\_SECONDARY} is the
-{\em secondary}
-selection; selection {\tt WS\_CLIPBOARD} is the
-{\em clipboard}
-selection (used by
-xclipboard).
-On the Macintosh, this always returns an empty string.
-\funcitem{resetselection}{i}
-%.br
-Resets selection number
-{\tt i},
-if this process owns it.
-(See window method
-{\tt setselection()}).
-\funcitem{baseline}{}
-%.br
-Return the baseline of the current font (defined by STDWIN as the
-vertical distance between the baseline and the top of the
-characters).%
-\footnote{
-There is no way yet to set the current font.
-This will change in a future version.
-}
-\funcitem{lineheight}{}
-%.br
-Return the total line height of the current font.
-\funcitem{textbreak}{str, width}
-%.br
-Return the number of characters of the string that fit into a space of
-{\tt width}
-bits wide when drawn in the curent font.
-\funcitem{textwidth}{str}
-%.br
-Return the width in bits of the string when drawn in the current font.
-\end{description}
-
-\subsubsection{Window Object Methods}
-
-Window objects are created by
-{\tt stdwin.open()}.
-There is no explicit function to close a window; windows are closed when
-they are garbage-collected.
-Window objects have the following methods:
-\begin{description}
-\funcitem{begindrawing}{}
-Returns a drawing object, whose methods (described below) allow drawing
-in the window.
-\funcitem{change}{rect}
-Invalidates the given rectangle; this may cause a draw event.
-\funcitem{gettitle}{}
-Returns the window's title string.
-\funcitem{getdocsize}{}
-\begin{sloppypar}
-Returns a pair of integers giving the size of the document as set by
-{\tt setdocsize()}.
-\end{sloppypar}
-\funcitem{getorigin}{}
-Returns a pair of integers giving the origin of the window with respect
-to the document.
-\funcitem{getwinsize}{}
-Returns a pair of integers giving the size of the window.
-\funcitem{menucreate}{title}
-Creates a menu object referring to a local menu (a menu that appears
-only in this window).
-Methods menu objects are described below.
-\funcitem{scroll}{rect,~point}
-Scrolls the given rectangle by the vector given by the point.
-\funcitem{setwincursor}{name}
-\begin{sloppypar}
-Sets the window cursor to a cursor of the given name.
-It raises the
-{\tt Runtime\-Error}
-exception if no cursor of the given name exists.
-Suitable names are
-{\tt 'ibeam'},
-{\tt 'arrow'},
-{\tt 'cross'},
-{\tt 'watch'}
-and
-{\tt 'plus'}.
-On X11, there are many more (see
-{\tt <X11/cursorfont.h>}).
-\end{sloppypar}
-\funcitem{setdocsize}{point}
-Sets the size of the drawing document.
-\funcitem{setorigin}{point}
-Moves the origin of the window to the given point in the document.
-\funcitem{setselection}{i, str}
-Attempts to set X11 selection number
-{\tt i}
-to the string
-{\tt str}.
-(See stdwin method
-{\tt getselection()}
-for the meaning of
-{\tt i}.)
-Returns true if it succeeds.
-If it succeeds, the window ``owns'' the selection until
-(a) another applications takes ownership of the selection; or
-(b) the window is deleted; or
-(c) the application clears ownership by calling
-{\tt stdwin.resetselection(i)}.
-When another application takes ownership of the selection, a
-{\tt WE\_LOST\_SEL}
-event is received for no particular window and with the selection number
-as detail.
-Ignored on the Macintosh.
-\funcitem{settitle}{title}
-Sets the window's title string.
-\funcitem{settimer}{dsecs}
-Schedules a timer event for the window in
-{\tt dsecs/10}
-seconds.
-\funcitem{show}{rect}
-Tries to ensure that the given rectangle of the document is visible in
-the window.
-\funcitem{textcreate}{rect}
-Creates a text-edit object in the document at the given rectangle.
-Methods of text-edit objects are described below.
-\end{description}
-
-\subsubsection{Drawing Object Methods}
-
-Drawing objects are created exclusively by the window method
-{\tt begindrawing()}.
-Only one drawing object can exist at any given time; the drawing object
-must be deleted to finish drawing.
-No drawing object may exist when
-{\tt stdwin.getevent()}
-is called.
-Drawing objects have the following methods:
-\begin{description}
-\funcitem{box}{rect}
-Draws a box around a rectangle.
-\funcitem{circle}{center, radius}
-%.br
-Draws a circle with given center point and radius.
-\funcitem{elarc(center, (rh, rv), }{a1, a2)}
-%.br
-Draws an elliptical arc with given center point.
-{\tt (rh, rv)}
-gives the half sizes of the horizontal and vertical radii.
-{\tt (a1, a2)}
-gives the angles (in degrees) of the begin and end points.
-0 degrees is at 3 o'clock, 90 degrees is at 12 o'clock.
-\funcitem{erase}{rect}
-Erases a rectangle.
-\funcitem{invert}{rect}
-Inverts a rectangle.
-\funcitem{line}{p1, p2}
-Draws a line from point
-{\tt p1}
-to
-{\tt p2}.
-\funcitem{paint}{rect}
-Fills a rectangle.
-\funcitem{text}{p, str}
-Draws a string starting at point p (the point specifies the
-top left coordinate of the string).
-\funcitem{shade}{rect, percent}
-%.br
-Fills a rectangle with a shading pattern that is about
-{\tt percent}
-percent filled.
-\funcitem{xorline}{p1, p2}
-Draws a line in XOR mode.
-\funcitem{baseline(), lineheight(), textbreak(), textwidth}{}
-%.br
-These functions are similar to the corresponding functions described
-above for the
-{\tt stdwin}
-module, but use the current font of the window instead of the (global)
-default font.
-\end{description}
-
-\subsubsection{Menu Object Methods}
-
-A menu object represents a menu.
-The menu is destroyed when the menu object is deleted.
-The following methods are defined:
-\begin{description}
-\funcitem{additem}{text, shortcut}
-%.br
-Adds a menu item with given text.
-The shortcut must be a string of length 1, or omitted (to specify no
-shortcut).
-\funcitem{setitem}{i, text}
-Sets the text of item number
-{\tt i}.
-\funcitem{enable}{i, flag}
-Enables or disables item
-{\tt i}.
-\funcitem{check}{i, flag}
-Sets or clears the
-{\em check mark}
-for item
-{\tt i}.
-\end{description}
-
-\subsubsection{Text-edit Object Methods}
-
-A text-edit object represents a text-edit block.
-For semantics, see the STDWIN documentation for C programmers.
-The following methods exist:
-\begin{description}
-\funcitem{arrow}{code}
-Passes an arrow event to the text-edit block.
-The
-{\tt code}
-must be one of
-{\tt WC\_LEFT},
-{\tt WC\_RIGHT},
-{\tt WC\_UP}
-or
-{\tt WC\_DOWN}
-(see module
-{\tt stdwinevents}).
-\funcitem{draw}{rect}
-Passes a draw event to the text-edit block.
-The rectangle specifies the redraw area.
-\funcitem{event}{type, window, detail}
-%.br
-Passes an event gotten from
-{\tt stdwin.getevent()}
-to the text-edit block.
-Returns true if the event was handled.
-\funcitem{getfocus}{}
-Returns 2 integers representing the start and end positions of the
-focus, usable as slice indices on the string returned by
-{\tt getfocustext()}.
-\funcitem{getfocustext}{}
-Returns the text in the focus.
-\funcitem{getrect}{}
-Returns a rectangle giving the actual position of the text-edit block.
-(The bottom coordinate may differ from the initial position because
-the block automatically shrinks or grows to fit.)
-\funcitem{gettext}{}
-Returns the entire text buffer.
-\funcitem{move}{rect}
-Specifies a new position for the text-edit block in the document.
-\funcitem{replace}{str}
-Replaces the focus by the given string.
-The new focus is an insert point at the end of the string.
-\funcitem{setfocus}{i,~j}
-Specifies the new focus.
-Out-of-bounds values are silently clipped.
-\end{description}
-
-\subsubsection{Example}
-
-Here is a simple example of using STDWIN in Python.
-It creates a window and draws the string ``Hello world'' in the top
-left corner of the window.
-The window will be correctly redrawn when covered and re-exposed.
-The program quits when the close icon or menu item is requested.
-\bcode\begin{verbatim}
-import stdwin
-from stdwinevents import *
-
-def main():
-    mywin = stdwin.open('Hello')
-    #
-    while 1:
-        (type, win, detail) = stdwin.getevent()
-        if type = WE_DRAW:
-            draw = win.begindrawing()
-            draw.text((0, 0), 'Hello, world')
-            del draw
-        elif type = WE_CLOSE:
-            break
-
-main()
-\end{verbatim}\ecode
-
-\subsection{Built-in Module {\tt amoeba}}
-
-This module provides some object types and operations useful for
-Amoeba applications.
-It is only available on systems that support Amoeba operations.
-RPC errors and other Amoeba errors are reported as the exception
-{\tt amoeba.error = 'amoeba.error'}.
-The module
-{\tt amoeba}
-defines the following items:
-\begin{description}
-\funcitem{name\_append}{path,~cap}
-%.br
-Stores a capability in the Amoeba directory tree.
-Arguments are the pathname (a string) and the capability (a capability
-object as returned by
-{\tt name\_lookup()}).
-\funcitem{name\_delete}{path}
-%.br
-Deletes a capability from the Amoeba directory tree.
-Argument is the pathname.
-\funcitem{name\_lookup}{path}
-%.br
-Looks up a capability.
-Argument is the pathname.
-Returns a
-{\em capability}
-object, to which various interesting operations apply, described below.
-\funcitem{name\_replace}{path,~cap}
-%.br
-Replaces a capability in the Amoeba directory tree.
-Arguments are the pathname and the new capability.
-(This differs from
-{\tt name\_append()}
-in the behavior when the pathname already exists:
-{\tt name\_append()}
-finds this an error while
-{\tt name\_replace()}
-allows it, as its name suggests.)
-\funcitem{capv}
-A table representing the capability environment at the time the
-interpreter was started.
-(Alas, modifying this table does not affect the capability environment
-of the interpreter.)
-For example,
-{\tt amoeba.capv['ROOT']}
-is the capability of your root directory, similar to
-{\tt getcap("ROOT")}
-in C.
-\excitem{error}{amoeba.error}
-%.br
-The exception raised when an Amoeba function returns an error.
-The value accompanying this exception is a pair containing the numeric
-error code and the corresponding string, as returned by the C function
-{\tt err\_why()}.
-\funcitem{timeout}{msecs}
-%.br
-Sets the transaction timeout, in milliseconds.
-Returns the previous timeout.
-Initially, the timeout is set to 2 seconds by the {\Python} interpreter.
-\end{description}
-
-\subsubsection{Capability Operations}
-
-Capabilities are written in a convenient ASCII format, also used by the
-Amoeba utilities
-{\em c2a}(U)
-and
-{\em a2c}(U).
-For example:
-\bcode\begin{verbatim}
->>> amoeba.name_lookup('/profile/cap')
-aa:1c:95:52:6a:fa/14(ff)/8e:ba:5b:8:11:1a
->>> 
-\end{verbatim}\ecode
-The following methods are defined for capability objects.
-\begin{description}
-\funcitem{dir\_list}{}
-Returns a list of the names of the entries in an Amoeba directory.
-\funcitem{b\_read}{offset, maxsize}
-%.br
-Reads (at most)
-{\tt maxsize}
-bytes from a bullet file at offset
-{\tt offset.}
-The data is returned as a string.
-EOF is reported as an empty string.
-\funcitem{b\_size}{}
-Returns the size of a bullet file.
-\funcitem{dir\_append(), dir\_delete(), dir\_lookup(), dir\_replace}{}
-%.br
-\itembreak
-Like the corresponding
-{\tt name\_*}
-functions, but with a path relative to the capability.
-(For paths beginning with a slash the capability is ignored, since this
-is the defined semantics for Amoeba.)
-\funcitem{std\_info}{}
-Returns the standard info string of the object.
-\funcitem{tod\_gettime}{}
-Returns the time (in seconds since the Epoch, in UCT, as for POSIX) from
-a time server.
-\funcitem{tod\_settime}{t}
-Sets the time kept by a time server.
-\end{description}
-
-\subsection{Built-in Module {\tt audio}}
-
-This module provides rudimentary access to the audio I/O device
-{\tt /dev/audio}
-on the Silicon Graphics Personal IRIS; see audio(7).
-It supports the following operations:
-\begin{description}
-\funcitem{setoutgain}{n}
-Sets the output gain (0-255).
-\funcitem{getoutgain}{}
-Returns the output gain.
-\funcitem{setrate}{n}
-Sets the sampling rate: 1=32K/sec, 2=16K/sec, 3=8K/sec.
-\funcitem{setduration}{n}
-Sets the `sound duration' in units of 1/100 seconds.
-\funcitem{read}{n}
-Reads a chunk of
-{\tt n}
-sampled bytes from the audio input (line in or microphone).
-The chunk is returned as a string of length n.
-Each byte encodes one sample as a signed 8-bit quantity using linear
-encoding.
-This string can be converted to numbers using {\tt chr2num()} described
-below.
-\funcitem{write}{buf}
-Writes a chunk of samples to the audio output (speaker).
-\end{description}
-
-These operations support asynchronous audio I/O:
-\begin{description}
-\funcitem{start\_recording}{n}
-%.br
-Starts a second thread (a process with shared memory) that begins reading
-{\tt n}
-bytes from the audio device.
-The main thread immediately continues.
-\funcitem{wait\_recording}{}
-%.br
-Waits for the second thread to finish and returns the data read.
-\funcitem{stop\_recording}{}
-%.br
-Makes the second thread stop reading as soon as possible.
-Returns the data read so far.
-\funcitem{poll\_recording}{}
-%.br
-Returns true if the second thread has finished reading (so
-{\tt wait\_recording()} would return the data without delay).
-\item[{\tt start\_playing(chunk)}, {\tt wait\_playing()},
-{\tt stop\_playing()}, {\tt poll\_playing()}]
-%.br
-\begin{sloppypar}
-Similar but for output.
-{\tt stop\_playing()}
-returns a lower bound for the number of bytes actually played (not very
-accurate).
-\end{sloppypar}
-\end{description}
-
-The following operations do not affect the audio device but are
-implemented in C for efficiency:
-\begin{description}
-\funcitem{amplify}{buf, f1, f2}
-%.br
-Amplifies a chunk of samples by a variable factor changing from
-{\tt f1}/256 to {\tt f2}/256.
-Negative factors are allowed.
-Resulting values that are to large to fit in a byte are clipped.         
-\funcitem{reverse}{buf}
-%.br
-Returns a chunk of samples backwards.
-\funcitem{add}{buf1, buf2}
-%.br
-Bytewise adds two chunks of samples.
-Bytes that exceed the range are clipped.
-If one buffer shorter, it is assumed to be padded with zeros.
-\funcitem{chr2num}{buf}
-%.br
-Converts a string of sampled bytes as returned by {\tt read()} into
-a list containing the numeric values of the samples.
-\funcitem{num2chr}{list}
-%.br
-\begin{sloppypar}
-Converts a list as returned by
-{\tt chr2num()}
-back to a buffer acceptable by
-{\tt write()}.
-\end{sloppypar}
-\end{description}
-
-\subsection{Built-in Module {\tt gl}}
-
-This module provides access to the Silicon Graphics
-{\em Graphics Library}.
-It is available only on Silicon Graphics machines.
-
-{\bf Warning:}
-Some illegal calls to the GL library cause the {\Python} interpreter to dump
-core.
-In particular, the use of most GL calls is unsafe before the first
-window is opened.
-
-The module is too large to document here in its entirety, but the
-following should help you to get started.
-The parameter conventions for the C functions are translated to {\Python} as
-follows:
-
-\begin{itemize}
-\item
-All (short, long, unsigned) int values are represented by {\Python}
-integers.
-\item
-All float and double values are represented by {\Python} floating point
-numbers.
-In most cases, {\Python} integers are also allowed.
-\item
-All arrays are represented by one-dimensional {\Python} lists.
-In most cases, tuples are also allowed.
-\item
-\begin{sloppypar}
-All string and character arguments are represented by {\Python} strings,
-for instance,
-{\tt winopen('Hi~There!')}
-and
-{\tt rotate(900,~'z')}.
-\end{sloppypar}
-\item
-All (short, long, unsigned) integer arguments or return values that are
-only used to specify the length of an array argument are omitted.
-For example, the C call
-\bcode\begin{verbatim}
-lmdef(deftype, index, np, props)
-\end{verbatim}\ecode
-is translated to {\Python} as
-\bcode\begin{verbatim}
-lmdef(deftype, index, props)
-\end{verbatim}\ecode
-\item
-Output arguments are omitted from the argument list; they are
-transmitted as function return values instead.
-If more than one value must be returned, the return value is a tuple.
-If the C function has both a regular return value (that is not omitted
-because of the previous rule) and an output argument, the return value
-comes first in the tuple.
-Examples: the C call
-\bcode\begin{verbatim}
-getmcolor(i, &red, &green, &blue)
-\end{verbatim}\ecode
-is translated to {\Python} as
-\bcode\begin{verbatim}
-red, green, blue = getmcolor(i)
-\end{verbatim}\ecode
-\end{itemize}
-
-The following functions are non-standard or have special argument
-conventions:
-\begin{description}
-\funcitem{varray}{}
-Equivalent to but faster than a number of
-{\tt v3d()}
-calls.
-The argument is a list (or tuple) of points.
-Each point must be a tuple of coordinates (x, y, z) or (x, y).
-The points may be 2- or 3-dimensional but must all have the
-same dimension.
-Float and int values may be mixed however.
-The points are always converted to 3D double precision points
-by assuming z=0.0 if necessary (as indicated in the man page),
-and for each point
-{\tt v3d()}
-is called.
-\funcitem{nvarray}{}
-Equivalent to but faster than a number of
-{\tt n3f}
-and
-{\tt v3f}
-calls.
-The argument is an array (list or tuple) of pairs of normals and points.
-Each pair is a tuple of a point and a normal for that point.
-Each point or normal must be a tuple of coordinates (x, y, z).
-Three coordinates must be given.
-Float and int values may be mixed.
-For each pair,
-{\tt n3f()}
-is called for the normal, and then
-{\tt v3f()}
-is called for the point.
-\funcitem{vnarray}{}
-Similar to 
-{\tt nvarray()}
-but the pairs have the point first and the normal second.
-\funcitem{nurbssurface}{s\_k[], t\_k[], ctl[][], s\_ord, t\_ord, type}
-%.br
-\itembreak
-Defines a nurbs surface.
-The dimensions of
-{\tt ctl[][]}
-are computed as follows:
-{\tt [len(s\_k)~-~s\_ord]},
-{\tt [len(t\_k)~-~t\_ord]}.
-\funcitem{nurbscurve}{knots, ctlpoints, order, type}
-%.br
-Defines a nurbs curve.
-The length of ctlpoints is
-{\tt len(knots)~-~order}.
-\funcitem{pwlcurve}{points, type}
-%.br
-Defines a piecewise-linear curve.
-{\tt points}
-is a list of points.
-{\tt type}
-must be
-{\tt N\_ST}.
-\funcitem{pick(n), select}{n}
-%.br
-The only argument to these functions specifies the desired size of the
-pick or select buffer.
-\funcitem{endpick(), endselect}{}
-%.br
-These functions have no arguments.
-They return a list of integers representing the used part of the
-pick/select buffer.
-No method is provided to detect buffer overrun.
-\end{description}
-
-Here is a tiny but complete example GL program in {\Python}:
-\bcode\begin{verbatim}
-import gl, GL, time
-
-def main():
-    gl.foreground()
-    gl.prefposition(500, 900, 500, 900)
-    w = gl.winopen('CrissCross')
-    gl.ortho2(0.0, 400.0, 0.0, 400.0)
-    gl.color(GL.WHITE)
-    gl.clear()
-    gl.color(GL.RED)
-    gl.bgnline()
-    gl.v2f(0.0, 0.0)
-    gl.v2f(400.0, 400.0)
-    gl.endline()
-    gl.bgnline()
-    gl.v2f(400.0, 0.0)
-    gl.v2f(0.0, 400.0)
-    gl.endline()
-    time.sleep(5)
-
-main()
-\end{verbatim}\ecode
-
-\subsection{Built-in Module {\tt pnl}}
-
-This module provides access to the
-{\em Panel Library}
-built by NASA Ames (to get it, send e-mail to
-{\tt panel-request@nas.nasa.gov}).
-All access to it should be done through the standard module
-{\tt panel},
-which transparantly exports most functions from
-{\tt pnl}
-but redefines
-{\tt pnl.dopanel()}.
-
-{\bf Warning:}
-the {\Python} interpreter will dump core if you don't create a GL window
-before calling
-{\tt pnl.mkpanel()}.
-
-The module is too large to document here in its entirety.
-
-\section{Standard Modules}
-
-The following standard modules are defined.
-They are available in one of the directories in the default module
-search path (try printing
-{\tt sys.path}
-to find out the default search path.)
-
-\subsection{Standard Module {\tt string}}
-
-This module defines some constants useful for checking character
-classes, some exceptions, and some useful string functions.
-The constants are:
-\begin{description}
-\funcitem{digits}
-The string
-{\tt '0123456789'}.
-\funcitem{hexdigits}
-The string
-{\tt '0123456789abcdefABCDEF'}.
-\funcitem{letters}
-The concatenation of the strings
-{\tt lowercase}
-and
-{\tt uppercase}
-described below.
-\funcitem{lowercase}
-The string
-{\tt 'abcdefghijklmnopqrstuvwxyz'}.
-\funcitem{octdigits}
-The string
-{\tt '01234567'}.
-\funcitem{uppercase}
-The string
-{\tt 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.
-\funcitem{whitespace}
-A string containing all characters that are considered whitespace,
-i.e.,
-space, tab and newline.
-This definition is used by
-{\tt split()}
-and
-{\tt strip()}.
-\end{description}
-
-The exceptions are:
-\begin{description}
-\excitem{atoi\_error}{non-numeric argument to string.atoi}
-%.br
-Exception raised by
-{\tt atoi}
-when a non-numeric string argument is detected.
-The exception argument is the offending string.
-\excitem{index\_error}{substring not found in string.index}
-%.br
-Exception raised by
-{\tt index}
-when
-{\tt sub}
-is not found.
-The argument are the offending arguments to index: {\tt (s, sub)}.
-\end{description}
-
-The functions are:
-\begin{description}
-\funcitem{atoi}{s}
-Converts a string to a number.
-The string must consist of one or more digits, optionally preceded by a
-sign ({\tt '+'} or {\tt '-'}).
-\funcitem{index}{s, sub}
-Returns the lowest index in
-{\tt s}
-where the substring
-{\tt sub}
-is found.
-\funcitem{lower}{s}
-Convert letters to lower case.
-\funcitem{split}{s}
-Returns a list of the whitespace-delimited words of the string
-{\tt s}.
-\funcitem{splitfields}{s, sep}
-%.br
-Returns a list containing the fields of the string
-{\tt s},
-using the string
-{\tt sep}
-as a separator.
-The list will have one more items than the number of non-overlapping
-occurrences of the separator in the string.
-Thus,
-{\tt string.splitfields(s, ' ')}
-is not the same as
-{\tt string.split(s)},
-as the latter only returns non-empty words.
-\funcitem{strip}{s}
-Removes leading and trailing whitespace from the string
-{\tt s}.
-\funcitem{swapcase}{s}
-Converts lower case letters to upper case and vice versa.
-\funcitem{upper}{s}
-Convert letters to upper case.
-\funcitem{ljust(s, width), rjust(s, width),  center}{s, width}
-%.br
-These functions respectively left-justify, right-justify and center a
-string in a field of given width.
-They return a string that is at least
-{\tt width}
-characters wide, created by padding the string
-{\tt s}
-with spaces until the given width on the right, left or both sides.
-The string is never truncated.
-\end{description}
-
-\subsection{Standard Module {\tt path}}
-
-This module implements some useful functions on POSIX pathnames.
-\begin{description}
-\funcitem{basename}{p}
-Returns the base name of pathname
-{\tt p}.
-This is the second half of the pair returned by
-{\tt path.split(p)}.
-\funcitem{cat}{p, q}
-Performs intelligent pathname concatenation on paths
-{\tt p}
-and
-{\tt q}:
-If
-{\tt q}
-is an absolute path, the return value is
-{\tt q}.
-Otherwise, the concatenation of
-{\tt p}
-and
-{\tt q}
-is returned, with a slash ({\tt '/'}) inserted unless
-{\tt p}
-is empty or ends in a slash.
-\funcitem{commonprefix}{list}
-%.br
-Returns the longest string that is a prefix of all strings in
-{\tt list}.
-If
-{\tt list}
-is empty, the empty string ({\tt ''}) is returned.
-\funcitem{exists}{p}
-Returns true if
-{\tt p}
-refers to an existing path.
-\funcitem{isdir}{p}
-Returns true if
-{\tt p}
-refers to an existing directory.
-\funcitem{islink}{p}
-Returns true if
-{\tt p}
-refers to a directory entry that is a symbolic link.
-Always false if symbolic links are not supported.
-\funcitem{ismount}{p}
-Returns true if
-{\tt p}
-is an absolute path that occurs in the mount table as output by the
-{\tt /etc/mount}
-utility.
-This output is read once when the function is used for the first
-time.%
-\footnote{
-Is there a better way to check for mount points?
-}
-\funcitem{split}{p}
-Returns a pair
-{\tt (head,~tail)}
-such that
-{\tt tail}
-contains no slashes and
-{\tt path.cat(head, tail)}
-is equal to
-{\tt p}.
-\funcitem{walk}{p, visit, arg}
-%.br
-Calls the function
-{\tt visit}
-with arguments
-{\tt (arg, dirname, names)}
-for each directory in the directory tree rooted at
-{\tt p}
-(including
-{\tt p}
-itself, if it is a directory).
-The argument
-{\tt dirname}
-specifies the visited directory, the argument
-{\tt names}
-lists the files in the directory (gotten from
-{\tt posix.listdir(dirname)}).
-The
-{\tt visit}
-function may modify
-{\tt names}
-to influence the set of directories visited below
-{\tt dirname},
-e.g.,
-to avoid visiting certain parts of the tree.
-(The object referred to by
-{\tt names}
-must be modified in place, using
-{\tt del}
-or slice assignment.)
-\end{description}
-
-\subsection{Standard Module {\tt getopt}}
-
-This module helps scripts to parse the command line arguments in
-{\tt sys.argv}.
-It uses the same conventions as the {\UNIX}
-{\tt getopt()}
-function.
-It defines the function
-{\tt getopt.getopt(args, options)}
-and the exception
-{\tt getopt.error}.
-
-The first argument to
-{\tt getopt()}
-is the argument list passed to the script with its first element
-chopped off (i.e.,
-{\tt sys.argv[1:]}).
-The second argument is the string of option letters that the
-script wants to recognize, with options that require an argument
-followed by a colon (i.e., the same format that {\UNIX}
-{\tt getopt()}
-uses).
-The return value consists of two elements: the first is a list of
-option-and-value pairs; the second is the list of program arguments
-left after the option list was stripped (this is a trailing slice of the
-first argument).
-Each option-and-value pair returned has the option as its first element,
-prefixed with a hyphen (e.g.,
-{\tt '-x'}),
-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.
-Example:
-\bcode\begin{verbatim}
->>> import getopt, string
->>> args = string.split('-a -b -cfoo -d bar a1 a2')
->>> 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}\ecode
-The exception
-{\tt getopt.error = 'getopt error'}
-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.
-
-\subsection{Standard Module {\tt rand}}
-
-This module implements a pseudo-random number generator similar to
-{\tt rand()}
-in C.
-It defines the following functions:
-\begin{description}
-\funcitem{rand}{}
-Returns an integer random number in the range [0 ... 32768).
-\funcitem{choice}{s}
-Returns a random element from the sequence (string, tuple or list)
-{\tt s.}
-\funcitem{srand}{seed}
-Initializes the random number generator with the given integral seed.
-When the module is first imported, the random number is initialized with
-the current time.
-\end{description}
-
-\subsection{Standard Module {\tt whrandom}}
-
-This module implements a Wichmann-Hill pseudo-random number generator.
-It defines the following functions:
-\begin{description}
-\funcitem{random}{}
-Returns the next random floating point number in the range [0.0 ... 1.0).
-\funcitem{seed}{x, y, z}
-Initializes the random number generator from the integers
-{\tt x},
-{\tt y}
-and
-{\tt z}.
-When the module is first imported, the random number is initialized
-using values derived from the current time.
-\end{description}
-
-\subsection{Standard Module {\tt stdwinevents}}
-
-This module defines constants used by STDWIN for event types
-({\tt WE\_ACTIVATE} etc.), command codes ({\tt WC\_LEFT} etc.)
-and selection types ({\tt WS\_PRIMARY} etc.).
-Read the file for details.
-Suggested usage is
-\bcode\begin{verbatim}
->>> from stdwinevents import *
->>> 
-\end{verbatim}\ecode
-
-\subsection{Standard Module {\tt rect}}
-
-This module contains useful operations on rectangles.
-A rectangle is defined as in module
-{\tt stdwin}:
-a pair of points, where a point is a pair of integers.
-For example, the rectangle
-\bcode\begin{verbatim}
-(10, 20), (90, 80)
-\end{verbatim}\ecode
-is a rectangle whose left, top, right and bottom edges are 10, 20, 90
-and 80, respectively.
-Note that the positive vertical axis points down (as in
-{\tt stdwin}).
-
-The module defines the following objects:
-\begin{description}
-\excitem{error}{rect.error}
-%.br
-The exception raised by functions in this module when they detect an
-error.
-The exception argument is a string describing the problem in more
-detail.
-\funcitem{empty}
-%.br
-The rectangle returned when some operations return an empty result.
-This makes it possible to quickly check whether a result is empty:
-\bcode\begin{verbatim}
->>> import rect
->>> r1 = (10, 20), (90, 80)
->>> r2 = (0, 0), (10, 20)
->>> r3 = rect.intersect(r1, r2)
->>> if r3 is rect.empty: print 'Empty intersection'
-Empty intersection
->>> 
-\end{verbatim}\ecode
-\funcitem{is\_empty}{r}
-%.br
-Returns true if the given rectangle is empty.
-A rectangle
-{\em (left,~top), (right,~bottom)}
-is empty if
-{\em left~$\geq$~right}
-or
-{\em top~$\leq$~bottom}.
-\funcitem{intersect}{list}
-%.br
-Returns the intersection of all rectangles in the list argument.
-It may also be called with a tuple argument or with two or more
-rectangles as arguments.
-Raises
-{\tt rect.error}
-if the list is empty.
-Returns
-{\tt rect.empty}
-if the intersection of the rectangles is empty.
-\funcitem{union}{list}
-%.br
-Returns the smallest rectangle that contains all non-empty rectangles in
-the list argument.
-It may also be called with a tuple argument or with two or more
-rectangles as arguments.
-Returns
-{\tt rect.empty}
-if the list is empty or all its rectangles are empty.
-\funcitem{pointinrect}{point, rect}
-%.br
-Returns true if the point is inside the rectangle.
-By definition, a point
-{\em (h,~v)}
-is inside a rectangle
-{\em (left,~top),}
-{\em (right,~bottom)}
-if
-{\em left~$\leq$~h~$<$~right}
-and
-{\em top~$\leq$~v~$<$~bottom}.
-\funcitem{inset(rect, }{dh, dv)}
-%.br
-Returns a rectangle that lies inside the
-{\tt rect}
-argument by
-{\tt dh}
-pixels horizontally
-and
-{\tt dv}
-pixels
-vertically.
-If
-{\tt dh}
-or
-{\tt dv}
-is negative, the result lies outside
-{\tt rect}.
-\funcitem{rect2geom}{rect}
-%.br
-Converts a rectangle to geometry representation:
-{\em (left,~top),}
-{\em (width,~height)}.
-\funcitem{geom2rect}{geom}
-%.br
-Converts a rectangle given in geometry representation back to the
-standard rectangle representation
-{\em (left,~top),}
-{\em (right,~bottom)}.
-\end{description}
-
-\subsection{Standard Modules {\tt GL} and {\tt DEVICE}}
-
-These modules define the constants used by the Silicon Graphics
-{\em Graphics Library}
-that C programmers find in the header files
-{\tt <gl/gl.h>}
-and
-{\tt <gl/device.h>}.
-Read the module files for details.
-
-\subsection{Standard Module {\tt panel}}
-
-This module should be used instead of the built-in module
-{\tt pnl}
-to interface with the
-{\em Panel Library}.
-
-The module is too large to document here in its entirety.
-One interesting function:
-\begin{description}
-\funcitem{defpanellist}{filename}
-%.br
-Parses a panel description file containing S-expressions written by the
-{\em Panel Editor}
-that accompanies the Panel Library and creates the described panels.
-It returns a list of panel objects.
-\end{description}
-
-{\bf Warning:}
-the {\Python} interpreter will dump core if you don't create a GL window
-before calling
-{\tt panel.mkpanel()}
-or
-{\tt panel.defpanellist()}.
-
-\subsection{Standard Module {\tt panelparser}}
-
-This module defines a self-contained parser for S-expressions as output
-by the Panel Editor (which is written in Scheme so it can't help writing
-S-expressions).
-The relevant function is
-{\tt panelparser.parse\_file(file)}
-which has a file object (not a filename!) as argument and returns a list
-of parsed S-expressions.
-Each S-expression is converted into a {\Python} list, with atoms converted
-to {\Python} strings and sub-expressions (recursively) to {\Python} lists.
-For more details, read the module file.
-
-\section{P.M.}
-
-\begin{verse}
-
-commands
-
-cmp?
-
-*cache?
-
-localtime?
-
-calendar?
-
-\_\_dict?
-
-mac?
-
-\end{verse}
+\input{mod1.tex}
+\input{mod2.tex}
+\input{mod3.tex}
 
 \end{document}