% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(hash_stream): Maintain a hash on a stream}

\label{sec:hashstream}

\begin{tags}
    \tag{See also}
In addition to this hash library, SWI-Prolog provides
\file{library(md5)}, \file{library(sha)} and hash functions through
\file{library(crypto)}, part of the \const{ssl} package.
\end{tags}

This library defines a filter stream that maintains a hash of the data
that passes through the stream. It can be used to compute the hash of
input data while it is being processed. This is notably interesting if
data is processed from a socket as it avoids the need for collecting the
data first in a temporary file.

A typical processing sequence is illustrated below, where \predref{process}{2}
somehow processed the data and \predref{save_result}{3} records the result as
obtained from \arg{URL} with content digest \arg{SHA256} its \arg{Result}.

\begin{code}
    ...,
    http_open(URL, In0, []),
    open_hash_stream(In0, In, [algorithm(sha256)]),
    process(In, Result),
    stream_hash(In, SHA256),
    close(In),
    save_result(URL, SHA256, Result)
\end{code}

This library can also be used to compute the hash for the content of a
file. The advantage is that this code doesn't rely on external tools. It
is considerably faster for short files, but considerably slower on large
files because Prolog I/O is based on character streams rather than
blocks.

\begin{code}
file_hash(Algorithm, File, Hash) :-
    setup_call_cleanup(
        open(File, read, In0, [type(binary)]),
        setup_call_cleanup(
            open_hash_stream(In0, In,
                             [ algorithm(Algorithm),
                               close_parent(false)
                             ]),
            ( setup_call_cleanup(
                  open_null_stream(Null),
                  copy_stream_data(In, Null),
                  close(Null)),
              stream_hash(In, Hash)
            ),
            close(In)),
        close(In0)).
\end{code}

\vspace{0.7cm}

\begin{description}
    \predicate[det]{open_hash_stream}{3}{+OrgStream, -HashStream, +Options}
Open a filter stream on \arg{OrgStream} that maintains a hash. The
hash can be retrieved at any time using \predref{stream_hash}{2}. Provided
options:

\begin{description}
    \termitem{algorithm}{+Algorithm}
One of \const{md5}, \const{sha1}, \const{sha224}, \const{sha256}, \const{sha384} or
\const{sha512}. Default is \const{sha1}.
    \termitem{close_parent}{+Bool}
If \const{true} (default), closing the filter stream also closes the
original (parent) stream.
\end{description}

    \predicate[det]{stream_hash}{2}{+HashStream, -Digest:atom}
Unify \arg{Digest} with a hash for the bytes send to or read from
\arg{HashStream}. Note that the hash is computed on the stream
buffers. If the stream is an output stream, it is first flushed
and the \arg{Digest} represents the hash at the current location. If
the stream is an input stream the \arg{Digest} represents the hash of
the processed input including the already buffered data.
\end{description}