The hu.dwim.zlib Reference Manual

Table of Contents

The hu.dwim.zlib Reference Manual

This is the hu.dwim.zlib Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 11:12:42 2021 GMT+0.

1 Introduction

hu.dwim.zlib

What

A Common Lisp FFI for zlib (which is a compression library for deflate and gzip written in C).

Why

It uses CFFI/C2FFI to automatically generate the CFFI definitions, so it's a complete interface based on the C header files.

zlib's gzip format can be used for compressing HTTP responses to browsers.

Who

Written by attila@lendvai.name.

Where

The primary communication channel is the facilities on the project's GitHub page.

Status

The raw FFI part is almost complete (except some va_list stuff).

No fancy lispy overlay API has been added; it seems to be convenient enough without it.

It's used in hu.dwim.web-server to compress HTTP responses.

It has a test that compresses and decompresses random data in random zlib configurations, and it doesn't yield any errors for me when run for minutes (besides some zlib peculiarities/bugs that are avoided by the test code).

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 hu.dwim.zlib

Author

Attila Lendvai

License

BSD or Bugroff

Description

Common Lisp FFI wrapper for zlib, aka http://zlib.net/

Version

0.1

Defsystem Dependency

cffi/c2ffi

Dependencies

• alexandria
• cffi
• cffi/c2ffi
• cffi-libffi

Source

hu.dwim.zlib.asd (file)

Components

• package-stage-1.lisp (file)
• source (module)
• c2ffi-spec (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 hu.dwim.zlib/source

Dependencies

• c2ffi-spec (module)
• package-stage-1.lisp (file)

Parent

hu.dwim.zlib (system)

Location

source/

Components

• package-stage-2.lisp (file)
• package-stage-3.lisp (file)
• zlib.lisp (file)

3.2 hu.dwim.zlib/c2ffi-spec

Dependency

package-stage-1.lisp (file)

Parent

hu.dwim.zlib (system)

Location

c2ffi-spec/

Component

zlib.h (file)

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 hu.dwim.zlib.asd

Location

hu.dwim.zlib.asd

Systems

hu.dwim.zlib (system)

4.1.2 hu.dwim.zlib/package-stage-1.lisp

Parent

hu.dwim.zlib (system)

Location

source/package-stage-1.lisp

Packages

hu.dwim.zlib

4.1.3 hu.dwim.zlib/source/package-stage-2.lisp

Parent

source (module)

Location

source/package-stage-2.lisp

Internal Definitions

import-all-owned-symbols (function)

4.1.4 hu.dwim.zlib/source/package-stage-3.lisp

Dependency

package-stage-2.lisp (file)

Parent

source (module)

Location

source/package-stage-3.lisp

4.1.5 hu.dwim.zlib/source/zlib.lisp

Dependency

package-stage-3.lisp (file)

Parent

source (module)

Location

source/zlib.lisp

Exported Definitions

• +default-buffer-size+ (constant)
• allocate-compress-buffer (function)
• c-fun/zlib (macro)
• compress (function)
• deflate (function)
• deflate-sequence (function)
• free-deflate-z-stream (function)
• free-inflate-z-stream (function)
• inflate (function)
• inflate-sequence (function)
• make-deflate-z-stream (function)
• make-inflate-z-stream (function)
• uncompress (function)

Internal Definitions

• %c-fun/zlib/check-error (function)
• %encode-container (function)
• %inflate-or-deflate (function)
• +default-memory-level+ (constant)
• c-ref (macro)
• container-kind (type)
• operation-kind (type)
• stream-ref (macro)
• ub8-vector (type)
• window-bits (type)

4.1.6 hu.dwim.zlib/c2ffi-spec/zlib.h

Parent

c2ffi-spec (module)

Location

c2ffi-spec/zlib.h

5 Packages

Packages are listed by definition order.

5.1 hu.dwim.zlib

Source

package-stage-1.lisp (file)

Use List

• cffi
• alexandria
• common-lisp

Exported Definitions

• +default-buffer-size+ (constant)
• allocate-compress-buffer (function)
• c-fun/zlib (macro)
• compress (function)
• deflate (function)
• deflate-sequence (function)
• free-deflate-z-stream (function)
• free-inflate-z-stream (function)
• inflate (function)
• inflate-sequence (function)
• make-deflate-z-stream (function)
• make-inflate-z-stream (function)
• uncompress (function)

Internal Definitions

• %c-fun/zlib/check-error (function)
• %encode-container (function)
• %inflate-or-deflate (function)
• +default-memory-level+ (constant)
• c-ref (macro)
• container-kind (type)
• import-all-owned-symbols (function)
• operation-kind (type)
• stream-ref (macro)
• ub8-vector (type)
• window-bits (type)

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Constants

Constant: +default-buffer-size+

Package

hu.dwim.zlib

Source

zlib.lisp (file)

6.1.2 Macros

Macro: c-fun/zlib FN-NAME &rest ARGS

Package

hu.dwim.zlib

Source

zlib.lisp (file)

6.1.3 Functions

Function: allocate-compress-buffer SOURCE &key START END

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Function: compress SOURCE DESTINATION &key SOURCE-START SOURCE-END DESTINATION-START LEVEL

A simpler API for the stream based DEFLATE.

Compress the first SOURCE-START bytes of SOURCE into DESTINATION. DESTINATION should be an array of (unsigned-byte 8), and should be large enough to hold the compressed contents. ALLOCATE-COMPRESS-BUFFER can be used to allocate a proper buffer.

Note that the size of the DESTINATION array should be at least 0.1% more than the souce plus 12 bytes, but the actual number of array elements filled in by the compression algorithm will usually be smaller (depending on how ’predictable’ the input data is).

Returns DESTINATION-END i.e. compressed length if DESTINATION-START was zero.

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Function: deflate INPUT-FN OUTPUT-FN &key BUFFER-SIZE LEVEL METHOD WINDOW-BITS CONTAINER MEMORY-LEVEL STRATEGY

See DEFLATE-SEQUENCE for usage.

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Function: deflate-sequence SOURCE &rest ARGS &key START END &allow-other-keys

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Function: free-deflate-z-stream STREAM

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Function: free-inflate-z-stream STREAM

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Function: inflate INPUT-FN OUTPUT-FN &key BUFFER-SIZE WINDOW-BITS CONTAINER

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Function: inflate-sequence COMPRESSED-BYTES &key START END BUFFER-SIZE WINDOW-BITS CONTAINER

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Function: make-deflate-z-stream &key LEVEL METHOD WINDOW-BITS CONTAINER MEMORY-LEVEL STRATEGY

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Function: make-inflate-z-stream &key WINDOW-BITS CONTAINER

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Function: uncompress SOURCE DESTINATION &key SOURCE-START SOURCE-END DESTINATION-START

A simpler API for the stream based INFLATE.

Pretty useless because DESTINATION must be long enough to hold the uncompressed contents, otherwise it errors out. Returns (values destination-end).

Package

hu.dwim.zlib

Source

zlib.lisp (file)

6.2 Internal definitions

6.2.1 Constants

Constant: +default-memory-level+

Package

hu.dwim.zlib

Source

zlib.lisp (file)

6.2.2 Macros

Macro: c-ref OBJECT TYPE SLOT

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Macro: stream-ref STREAM SLOT

Package

hu.dwim.zlib

Source

zlib.lisp (file)

6.2.3 Functions

Function: %c-fun/zlib/check-error RC FN-NAME WHOLE-FORM

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Function: %encode-container CONTAINER WINDOW-BITS

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Function: %inflate-or-deflate OPERATION MAKE-STREAM-FN FREE-STREAM-FN INPUT-FN OUTPUT-FN &key BUFFER-SIZE

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Function: import-all-owned-symbols SOURCE-PACKAGE TARGET-PACKAGE &key OVERWRITE

Package

hu.dwim.zlib

Source

package-stage-2.lisp (file)

6.2.4 Types

Type: container-kind ()

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Type: operation-kind ()

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Type: ub8-vector ()

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Type: window-bits ()

Package

hu.dwim.zlib

Source

zlib.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types