add hg and python

1 files changed, 100 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libgdbm.tex b/sys/src/cmd/python/Doc/lib/libgdbm.tex
new file mode 100644
index 000000000..0c36677fd
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libgdbm.tex
@@ -0,0 +1,100 @@
+\section{\module{gdbm} ---
+         GNU's reinterpretation of dbm}
+
+\declaremodule{builtin}{gdbm}
+  \platform{Unix}
+\modulesynopsis{GNU's reinterpretation of dbm.}
+
+
+This module is quite similar to the \refmodule{dbm}\refbimodindex{dbm}
+module, but uses \code{gdbm} instead to provide some additional
+functionality.  Please note that the file formats created by
+\code{gdbm} and \code{dbm} are incompatible.
+
+The \module{gdbm} module provides an interface to the GNU DBM
+library.  \code{gdbm} objects behave like mappings
+(dictionaries), except that keys and values are always strings.
+Printing a \code{gdbm} object doesn't print the keys and values, and
+the \method{items()} and \method{values()} methods are not supported.
+
+The module defines the following constant and functions:
+
+\begin{excdesc}{error}
+Raised on \code{gdbm}-specific errors, such as I/O errors.
+\exception{KeyError} is raised for general mapping errors like
+specifying an incorrect key.
+\end{excdesc}
+
+\begin{funcdesc}{open}{filename, \optional{flag, \optional{mode}}}
+Open a \code{gdbm} database and return a \code{gdbm} object.  The
+\var{filename} argument is the name of the database file.
+
+The optional \var{flag} argument can be
+\code{'r'} (to open an existing database for reading only --- default),
+\code{'w'} (to open an existing database for reading and writing),
+\code{'c'} (which creates the database if it doesn't exist), or
+\code{'n'} (which always creates a new empty database).
+
+The following additional characters may be appended to the flag to
+control how the database is opened:
+
+\begin{itemize}
+\item \code{'f'} --- Open the database in fast mode.  Writes to the database
+                     will not be synchronized.
+\item \code{'s'} --- Synchronized mode. This will cause changes to the database
+                     will be immediately written to the file.
+\item \code{'u'} --- Do not lock database. 
+\end{itemize}
+
+Not all flags are valid for all versions of \code{gdbm}.  The
+module constant \code{open_flags} is a string of supported flag
+characters.  The exception \exception{error} is raised if an invalid
+flag is specified.
+
+The optional \var{mode} argument is the \UNIX{} mode of the file, used
+only when the database has to be created.  It defaults to octal
+\code{0666}.
+\end{funcdesc}
+
+In addition to the dictionary-like methods, \code{gdbm} objects have the
+following methods:
+
+\begin{funcdesc}{firstkey}{}
+It's possible to loop over every key in the database using this method 
+and the \method{nextkey()} method.  The traversal is ordered by
+\code{gdbm}'s internal hash values, and won't be sorted by the key
+values.  This method returns the starting key.
+\end{funcdesc}
+
+\begin{funcdesc}{nextkey}{key}
+Returns the key that follows \var{key} in the traversal.  The
+following code prints every key in the database \code{db}, without
+having to create a list in memory that contains them all:
+
+\begin{verbatim}
+k = db.firstkey()
+while k != None:
+    print k
+    k = db.nextkey(k)
+\end{verbatim}
+\end{funcdesc}
+
+\begin{funcdesc}{reorganize}{}
+If you have carried out a lot of deletions and would like to shrink
+the space used by the \code{gdbm} file, this routine will reorganize
+the database.  \code{gdbm} will not shorten the length of a database
+file except by using this reorganization; otherwise, deleted file
+space will be kept and reused as new (key, value) pairs are added.
+\end{funcdesc}
+
+\begin{funcdesc}{sync}{}
+When the database has been opened in fast mode, this method forces any 
+unwritten data to be written to the disk.
+\end{funcdesc}
+
+
+\begin{seealso}
+  \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
+  \seemodule{whichdb}{Utility module used to determine the type of an
+                      existing database.}
+\end{seealso}