\documentclass[11pt]{article}
\usepackage{times}
\usepackage{pl}
\usepackage{html}
\sloppy
\makeindex

\onefile
\htmloutput{html}				% Output directory
\htmlmainfile{index}				% Main document file
\bodycolor{white}				% Page colour

\begin{document}

\title{SWI-Prolog binding to zlib}
\author{Jan Wielemaker \\
	HCS, \\
	University of Amsterdam \\
	The Netherlands \\
	E-mail: \email{wielemak@science.uva.nl}}

\maketitle

\begin{abstract}
The library \pllib{zlib} provides a binding to the
\url[zlib]{http://www.zlib.net/} general purpose compression library.
The prolog library aims as seamlessly reading and writing files
compatible to the \program{gzip} program as well as compressed (network)
communication.
\end{abstract}

\pagebreak
\tableofcontents

\vfill
\vfill

\newpage

\section{Zlib and compression}

Zlib is a widespread library implementing the RFC1950 (zlib wrapper),
RFC1951 (deflate stream) and RFC1952 (gzip wrapper) compression
standards. The SWI-Prolog binding is a foreign library that creates a
compressed stream as a wrapper around a normal stream. Implemented this
way, it can perform a wide variety of tasks:

\begin{itemize}
    \item Read/write gzip compatible files
    \item Setup standard compressed stream communication
    \item Realise in-memory compression or decompression
    \item Deal with streams holding embedded compressed objects
\end{itemize}

The core predicate of the library is zopen/3. The remainder of the
functionality of \pllib{zlib} is defined in Prolog and can be used as a
starting point for other high-level primitives. See also \file{ztest.pl}
providing test and demo code. This file is part of the source
distribution.

Part of the functionality of this library can also be realised using
the pipe interface and the \program{gzip} program.  For example, a
gziped file can also be opened in Prolog using the code below.

\begin{code}
	...
	open(pipe('gunzip < file.gz'), read, In),
	...
\end{code}

The advantage of this library for such tasks is enhanced platform
independence and reduced time to open a file. Platform independence is
improved as we do not have to worry about availability of the
\program{gunzip} utility and we do not have to worry about shell and
filename quoting issues. While the above works well on most modern Unix
systems, it only works with special precautions on Windows.%
	\footnote{Install gunzip, deal with Windows path-names, the
		  windows shell and quoting.}

The library becomes really valuable if we consider compressed network
communication. Here we get the stream from tcp_open_socket/3. The
library provides efficient creation of a compressed stream, as well as
support for flushing output through the standard Prolog flush_output/1
call.


\section{Predicate reference}

\begin{description}
    \predicate{zopen}{3}{+Stream, -ZStream, +Options}
Creates \arg{ZStream}, providing compressed access to \arg{Stream}. If
an input stream is wrapped, it recognises a gzip or deflate header.

If an output stream is enabled, \arg{Options} define the desired wrapper
and compression level. Defined options on output streams are:

    \begin{description}
	\termitem{format}{+Format}
Either \const{deflate} (default) or \const{gzip}. The \const{deflate}
envelope is simple and short and is typically used for compressed
(network) communication.  The \const{gzip} envelope is compatible to
the \program{gzip} program and intended to read/write compressed files.
	
	\termitem{level}{+Level}
Number between 0 and 9, specifying the compression level, Higher levels
use more resources. Default is 6, generally believed to be a good
compromise between speed, memory requirement and compression.
    \end{description}

Generic options are:

    \begin{description}
	\termitem{close_parent}{Bool}
If \const{true} (default), closing the compressed stream also closes
(and thus invalidates) the wrapped stream. If \const{false}, the wrapped
stream is \emph{not} closed. This can be used to read/write a compressed
ndata block as partial input/output on a stream.
    \end{description}

    \predicate{gzopen}{3}{+File, +Mode, -Stream}
Same as \exam{gzopen}{File, Mode, Stream, []}.

    \predicate{gzopen}{4}{+File, +Mode, -Stream, +Options}
Open \program{gzip} compatible \arg{File} for reading or writing.
\end{description}

\section{Interaction with Prolog stream predicates}

Using flush_output/1 on a compressed stream causes a
\const{Z_SYNC_FLUSH} on the stream.  Using close/1 on a compressed
stream causes a \const{Z_FINISH} on the stream.  If the stream uses
the \const{gzip} format, a \program{gzip} compatible footer is
written to the stream.  If \const{close_parent} is set (default)
the underlying stream is closed too.  Otherwise it remains open
and the user can continue communication in non-compressed format
or reopen the stream for compression using zopen/3.


\section{Installation}

\subsection{Unix systems}

Installation on Unix system uses the commonly found {\em configure},
{\em make} and {\em make install} sequence. SWI-Prolog should be
installed before building this package. If SWI-Prolog is not installed
as \program{pl}, the environment variable \env{PL} must be set to the
name of the SWI-Prolog executable. Installation is now accomplished
using:

\begin{code}
% ./configure
% make
% make install
\end{code}

This installs the foreign libraries in \file{$PLBASE/lib/$PLARCH} and
the Prolog library files in \file{$PLBASE/library}, where
\file{$PLBASE} refers to the SWI-Prolog `home-directory'.

\printindex

\end{document}