Zstandard (de)compression using bindings to libzstd

cl-zstd

#+TITLE: cl-zstd
#+AUTHOR: Guillaume LE VAILLANT
#+DATE: 2022-06-20
#+EMAIL: glv@posteo.net
#+LANGUAGE: en
#+OPTIONS: num:nil toc:nil html-postamble:nil html-scripts:nil
#+HTML_DOCTYPE: html5

* Description

*cl-zstd* is a Common Lisp library for Zstandard compression/decompression
using bindings to the libzstd C library.

* License

*cl-zstd* is released under the GPL-3 license or later. See the [[file:LICENSE][LICENSE]] file
for details.

* Dependencies

*cl-zstd* requires:
 - [[https://cffi.common-lisp.dev/][cffi]]
 - [[https://codeberg.org/glv/cl-octet-streams][cl-octet-streams]]
 - [[https://facebook.github.io/zstd/][libzstd]]
 - [[https://trivial-gray-streams.common-lisp.dev/][trivial-gray-streams]]

There should be a package providing *libzstd* in almost every GNU/Linux or *BSD
distribution. For example it is called /libzstd1/ on Debian, /zstd/ on Gentoo,
and /zstd:lib/ on Guix.

* API

The library can be loaded with the usual:

#+BEGIN_SRC lisp
(asdf:load-system "zstd")
#+END_SRC

or

#+BEGIN_SRC lisp
(quicklisp:quickload "zstd")
#+END_SRC

The functions will then be available in the ~zstd~ package.

** Compression

#+BEGIN_SRC lisp
(compress-stream input output &key level) => t
#+END_SRC

Read the data from the /input/ octet stream, compress it, and write the result
to the /output/ octet stream.

#+BEGIN_SRC lisp
(compress-file input output &key level) => t
#+END_SRC

Read the data from the /input/ file, compress it, and write the result to the
/output/ file.

#+BEGIN_SRC lisp
(compress-buffer buffer &key start end level) => bytes
#+END_SRC

Read the data between the /start/ and /end/ offsets in the /buffer/, compress
it, and return the resulting octet vector.

#+BEGIN_SRC lisp
(make-compressing-stream output-stream &key level) => stream
#+END_SRC

Return a stream that will compress the bytes written to it at the given
compression /level/ and write them to the /output-stream/.

#+BEGIN_SRC lisp
(with-compressing-stream (stream output-stream &key level) &body body)
#+END_SRC

Within /body/, /stream/ is bound to a compressing stream for the given
compression /level/ and /output-stream/. The result of the last form of /body/
is returned.

** Decompression

#+BEGIN_SRC lisp
(decompress-stream input output) => t
#+END_SRC

Read the data from the /input/ octet stream, decompress it, and write the result
to the /output/ octet stream.

#+BEGIN_SRC lisp
(decompress-file input output) => t
#+END_SRC

Read the data from the /input/ file, decompress it, and write the result to the
/output/ file.

#+BEGIN_SRC lisp
(decompress-buffer buffer &key start end) => bytes
#+END_SRC

Read the data between the /start/ and /end/ offsets in the /buffer/, decompress
it, and return the resulting octet vector.

#+BEGIN_SRC lisp
(make-decompressing-stream input-stream) => stream
#+END_SRC

Return a stream that will supply the bytes resulting from the decompression of
the data read from the /input-stream/.

#+BEGIN_SRC lisp
(with-decompressing-stream (stream input-stream) &body body)
#+END_SRC

Within /body/, /stream/ is bound to a decompressing stream for the given
/input-stream/. The result of the last form of /body/ is returned.

* Tests

The tests require the [[https://common-lisp.net/project/fiveam/][fiveam]] package. They can be run with:

#+BEGIN_SRC lisp
(asdf:test-system "zstd")
#+END_SRC


cl-zstd

Upstream URL

Author

License

zstd

Version:

License:

Authors:

Dependencies:

zstd-tests

Version:

License:

Authors:

Dependencies:

Dependencies (5)

Dependents (0)