path: root/doc/mod3.tex

\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}