common lisp bindings to the C library libconfig
Common Lisp NewLisp
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
tests
API.lisp
BUGS.org
README.html
README.org
TODO
grovel.lisp
libconfig.asd
libconfig.lisp
package.lisp

README.org

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.