chalaev / cl-libconfig

common lisp bindings to the C library libconfig

cl-libconfig

This quicklisp package allows using standard libconfig library in Common LISP on linux. Requires linux libconfig-dev package.

libconfig supports several important data types, see write-structure description below. Apart from its usage as a handy configuration tool, libconfig is also a universal language for communication between programs written in different programming languages and in different OS.

Note that libconfig is not thread-safe.

Quick start

I assume that quicklisp is already installed and resides in home directory; lisp is also installed locally: ~/local/bin/sbcl

1. Install libconfig-dev:

   apt-get install libconfig-dev
       

2. download the code (I assume that your quicklisp directory is ~/quicklisp/):

   cd ~/quicklisp/local-projects/
   git clone https://github.com/chalaev/cl-libconfig
   mv cl-libconfig/tests ~/test-cl-libconfig
       

3. Ensure that the tests are running ok:

   ~/local/bin/sbcl --load read.lisp
   ~/local/bin/sbcl --load write.lisp
   ~/local/bin/sbcl --load change.lisp
       

4. Now examine ~/test-cl-libconfig/*.lisp, read-1.conf and (newly created) change.conf. Take a look on tests/*.lisp files which are designed to be self-explanatory; they show how one can read, wrote, and change conf files in common lisp using this software.

Functions

read-file

Syntax:

(read-file fileName)

Reads entire conf-file named fileName into the hash-table. See usage example in tests/read.lisp

Macros

with-read-config-file

Syntax:

(with-read-config-file fileName body)

where fileName is the name of the conf-file to read (the conf-file must comply with the standard libconfig syntax). Inside this macro, macro read-setting can be used. See usage example in tests/read.lisp

with-write-config-file

Syntax:

(with-write-config-file fileName body)

where fileName is the name of the conf-file to write. This conf-file will be newly created; an existing file wil be ovewritten. Inside this macro, function write-structure can be used. See usage example in tests/write.lisp

read-setting

Syntax:

(read-setting parName [default])

where parName is the name of the parameter from the conf-file, and optional default parameter specifies the value to be returned in case the parameter is not found in the conf-file. See usage example in tests/read.lisp

with-rw-config-file

Syntax:

(with-rw-config-file fileName body)

with-rw-config-file is similar to with-read-config-file and with-write-config-file; First, it reads conf-file named fileName (which must exist or the condition conf-file-read-error is raised). In the body one can read/erase/write conf-parameters like it is done inside “with-read-config-file” and “with-write-config-file” environments. See usage example in tests/change.lisp

write-structure

(To be used from inside of “with-rw-config-file” and “with-write-config-file” macros.) Syntax:

(write-structure parName value)

where value must have one of the following types: integer string boolean cons hash single-float double-float ratio. The value parameter can also have nested structure: for example, it can be an array/hash of any of above-enumerated types. See usage examples in tests/write.lisp and tests/change.lisp

remove-setting

(To be used from inside of with-rw-config-file macro.) Removes a setting. Syntax:

(remove-setting parName)

where parName is the name of the setting which we want to remove. See usage example in tests/change.lisp

Exceptions (conditions)

conf-file-read-error

This condition occurs when the conf-file does not exist or is unreadable. See usage example in tests/read.lisp

config-parse-error

This condition occurs when the conf-file has grammar errors. This often happens for the conf-files that have been writen manually. An extra bracket, brace, or a missing semicolon in the conf-file will raise this condition.