The chameleon Reference Manual

Table of Contents

The chameleon Reference Manual

This is the chameleon Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 09:14:57 2021 GMT+0.

1 Introduction

* Chameleon

** Introduction

Chameleon is a configuration management library shipped with profile support. It mainly help you to:

1. Define a set of configurations with default values.
2. Define multiple profiles that optionally overriding the default values.
3. Switch between several profiles just like a chameleon switching its colors!

Access function with the same name of configurations will be generated into the caller package, which makes it easy to access and modify. It makes use of function name completion and no more symbol/keyword/string lookup!

Also, by switching profiles you may use different configurations for unit testing, development, production etc.

** Installation

It is now in Quicklisp! You may simply install it by Quicklisp:

#+BEGIN_SRC lisp
(ql:quickload :chameleon)
#+END_SRC

To test it:

#+BEGIN_SRC lisp
(asdf:test-system :chameleon)
#+END_SRC

** Usage

Chameleon provides 2 macros that generates corresponding functions:
~defconfig~ and ~defprofile~.

- The ~defconfig~ macro defines the schema of configuration set.
- The ~defprofile~ macro defines a profile with values of configurations.

*** Defining a Configuration Set

A configuration set contains multiple items, with each consisting of name,
default value and optional doc string. The ~defconfig~ macro defines a profile
with name ~NIL~ and puts the default values inside.

Talk is cheap, here is the code:

#+BEGIN_SRC lisp
(defpackage config
  (:use #:cl
        #:chameleon))

(in-package config)

(defconfig
  (server-port 5000 "The port of running server.")
  (database-driver-name :sqlite3 "The driver of database."))
#+END_SRC

The code above defines 2 configuration items: ~server-port~ and
~database-driver-name~ with default values and optional documentation, just
like ~defvar~.

After evaluating the code 2 functions and their ~setf~ versions will be
generated and exported, as shown below:

#+BEGIN_SRC lisp
(defpackage use-config
  (:use #:cl))

(in-package use-config)

(config:server-port)
 ; => 5000 (13 bits, #x1388)

(documentation 'config:database-driver-name 'function)
 ; => "The driver of database."

(setf (config:server-port) 15000)
 ; => 15000 (14 bits, #x3A98)

(config:server-port)
 ; => 15000 (14 bits, #x3A98)
#+END_SRC

The ~defconfig~ macro also generates some other functions for convenience:

- ~(profiles)~ returns the defined profiles.
- ~(active-profile)~ returns the current profile. The default profile is ~NIL~.

And some special variables that might be useful in some corner cases:

- ~*profile*~ represents the current active profile.
- ~*configs*~ represents profiles and configuration values.

Pleaes note that these built-in functions and variables are *not* exported by
default. Also, Chameleon always generates everything mentioned above to the
package where it is called.

*** Defining Some Profiles

A profile consists of values for each configuration item. If an item is missing, the default value will be used.

#+BEGIN_SRC lisp
(in-package config)

;; Define a profile with name :DEVELOP.
(defprofile :develop
  (server-port 5001))
 ; => :DEVELOP

;; Define a profile with name :PRODUCT.
(defprofile :product
  (server-port 5002)
  (database-driver-name :mysql))
 ; => PRODUCT

;; Get current profile.
(active-profile)
 ; => NIL

;; Switch current profile.
(setf (active-profile) :develop)
 ; => :DEVELOP

(server-port)
 ; => 5001 (13 bits, #x1389)

(database-driver-name)
 ; => :SQLITE3, T

;; Switch back to default profile.
(setf (active-profile) nil)
 ; => nil
#+END_SRC

2 Systems

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

2.1 chameleon

Author

YUE Daian

License

MIT

Description

Configuration management facilities for Common Lisp with multiple profile support.

Version

1.0.0

Dependencies

• alexandria
• trivia

Source

chameleon.asd (file)

Component

src (module)

3 Modules

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

3.1 chameleon/src

Parent

chameleon (system)

Location

src/

Components

• packages.lisp (file)
• chameleon.lisp (file)

4 Files

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

4.1 Lisp

4.1.1 chameleon.asd

Location

chameleon.asd

Systems

chameleon (system)

4.1.2 chameleon/src/packages.lisp

Parent

src (module)

Location

src/packages.lisp

Packages

chameleon

4.1.3 chameleon/src/chameleon.lisp

Parent

src (module)

Location

src/chameleon.lisp

Exported Definitions

• defconfig (macro)
• defprofile (macro)

5 Packages

Packages are listed by definition order.

5.1 chameleon

Source

packages.lisp (file)

Use List

• trivia.level2
• alexandria
• common-lisp

Exported Definitions

• defconfig (macro)
• defprofile (macro)

6 Definitions

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

6.1 Exported definitions

6.1.1 Macros

Macro: defconfig &body CONFIGS

Defines a configuration set. The CONFIGS is one or more lists, with each list in the following form, very similar to DEFVAR:
(name default-value [docstring])

This macro then generates access function with the name defined above.

It also generates some general-purpose functions:
- (PROFILES) returns a list of defined profiles.
- (ACTIVE-PROFILE) returns the currently active profile.
- (SETF ACTIVE-PROFILE PROFILE) sets the active profile to PROFILE.

In addition, the following special variables are exposed:
*PROFILE* => the current active profile.
*CONFIGS* => Hash table of defined configurations.

The key of *CONFIGS* is profile name and the value is a hash table containing configuration items and their values. In normal cases, it should not be touched directly.

Package

chameleon

Source

chameleon.lisp (file)

Macro: defprofile PROFILE-NAME &body CONFIGS

Define a profile with name PROFILE-NAME.
A profile consists of a set of configurations.
CONFIGS is one or more lists, with each list of the following form: (key value)

Package

chameleon

Source

chameleon.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types