164 lines
5.4 KiB
Plaintext
164 lines
5.4 KiB
Plaintext
\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}
|
|
|