CL-CHMLIB

Summary

CL-CHMLIB is a small Common Lisp bindings set for the chmlib C library, using CFFI. It provides access to all the public API provided by this library. It is released with a LGPL license.

It was developped and tested under SBCL 0.9.12 with Linux kernel 2.6. It also works with CMUCL 19c. It doesn't works under CLISP, LispWorks nor Allegro CL (because CFFI doesn't appear to support 64 bits integers on these implementations.)

From the chmlib homepage:

CHMLIB is a library for dealing with Microsoft ITSS/CHM format files. Right now, it is a very simple library, but sufficient for dealing with all of the .chm files I've come across.

chmlib was created by Jed Wing.

Changelogs

June 25, 2006: Wrapped callback invocation to catch non-local control transfer when enumerating a CHM file. Examples updated. (version 0.1.3)
June 20, 2006: Updated with-chm-unit-info. Same update as for with-chm. Now, chm-retrieve-object returns an array of (unsigned-byte 8) rather than a string. (version 0.1.2)
May 29, 2006: Updated with-chm macro. Passing a pathname as filename is supported now. And the body is enclosed in a let form, allowing declarations. (version 0.1.1)
May 25, 2006: Initial release (version 0.1)

Installation

You can find the latest release here: cl-chmlib-latest.tar.gz.

CL-CHMLIB use ASDF, so please refer to it for installation procedure.

Basically, you just have to uncompress the source then create a symbolic link in your project pointing at the chmlib.asd file (and optionnaly chmlib-examples.asd), then use:

(asdf:oos 'asdf:load-op 'chmlib)

or alternatively, if your Common Lisp implementation allows it:

(require 'chmlib)

Summary

To work with a CHM:

(with-chm (<var> <filename>) <body>)

To get information about an objet:

(chm-object-info <chm> <path>)

To retrieve an object:

(chm-retrieve-object <chm> <path>)

Two functions allows to enumerate objects:

(chm-enumerate <chm> <what> <callback>)
(chm-enumerate-directory <chm> <prefix> <what> <callback>)

where <callback> is a function which take one parameter, and must return NIL to stop enumeration.

Examples

CL-USER> (require 'chmlib-examples)
CL-USER> (use-package 'chmlib-examples)
CL-USER> (use-package 'chmlib)
CL-USER> (chm-enumdir "sapi.chm")
/:
 spc     start    length type           name
 ===     =====    ====== ====           ====
   1   8560149      4096 special files  /#IDXHDR
   0         0         0 special files  /#ITBITS
   1   8644838     34113 special files  /#STRINGS
[..]
   1   1674334      3459 normal files   /XML_GrmFmt_topnode.htm
   1   1818569     12988 normal files   /XML_GrmFmt_Using_Grammars.htm
   1   2498825     28582 normal files   /XML_Japanese_Context_Tag.htm
   1   2434560      9699 normal files   /XML_Synthesis_Markup.htm
   1   2431695      2865 normal files   /XML_Synthesis_topnode.htm
NIL
CL-USER> (with-chm (chm "sapi.chm")
           (print (sb-ext:octets-to-string
                    (chm-retrieve-object chm "/Welcome.htm"
                                         :offset 140 :length 51)))
           (values))
"<TITLE>Welcome to the Microsoft Speech SDK </TITLE>" 
; No value
CL-USER>

Note that this example now use sb-ext:octets-to-string (specific to the SBCL implementation) to print the object because chm-retrieve-object returns an array of (unsigned-byte 8) since version 0.1.2, unlike previous versions that returned a string instead. But since the encoding is unspecified, it is now the responsability of the user to translate the octets to a string accordingly to the encoding of the CHM.

Author

Frederic Jolliton made the initial release.

Last update: May 27, 2006