cl-zstd

cl-zstd copied to clipboard

#+TITLE: cl-zstd #+AUTHOR: Guillaume LE VAILLANT #+DATE: 2022-06-20 #+EMAIL: [email protected] #+LANGUAGE: en #+OPTIONS: num:nil toc:nil html-postamble:nil html-scripts:nil #+HTML_DOCTYPE: html5

The active repository is at https://codeberg.org/glv/cl-zstd

• 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