The chameleon Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

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.

Next: , Previous: , Up: Top   [Contents][Index]

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)

To test it:

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

** 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

(in-package config)

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

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)

 ; => 5000 (13 bits, #x1388)

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

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

 ; => 15000 (14 bits, #x3A98)

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))

;; Get current profile.
 ; => NIL

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

 ; => 5001 (13 bits, #x1389)

 ; => :SQLITE3, T

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

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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

Previous: , Up: Systems   [Contents][Index]

2.1 chameleon


YUE Daian




Configuration management facilities for Common Lisp with multiple profile support.




chameleon.asd (file)


src (module)

Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

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

Previous: , Up: Modules   [Contents][Index]

3.1 chameleon/src


chameleon (system)




Next: , Previous: , Up: Top   [Contents][Index]

4 Files

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

Previous: , Up: Files   [Contents][Index]

4.1 Lisp

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 chameleon.asd




chameleon (system)

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 chameleon/src/packages.lisp


src (module)





Previous: , Up: Lisp files   [Contents][Index]

4.1.3 chameleon/src/chameleon.lisp


src (module)



Exported Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.

Previous: , Up: Packages   [Contents][Index]

5.1 chameleon


packages.lisp (file)

Use List
Exported Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

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

Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions

Previous: , Up: Exported definitions   [Contents][Index]

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.




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)




chameleon.lisp (file)

Previous: , Up: Top   [Contents][Index]

Appendix A Indexes

Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

chameleon.asd: The chameleon․asd file
chameleon/src: The chameleon/src module
chameleon/src/chameleon.lisp: The chameleon/src/chameleon․lisp file
chameleon/src/packages.lisp: The chameleon/src/packages․lisp file

File, Lisp, chameleon.asd: The chameleon․asd file
File, Lisp, chameleon/src/chameleon.lisp: The chameleon/src/chameleon․lisp file
File, Lisp, chameleon/src/packages.lisp: The chameleon/src/packages․lisp file

Lisp File, chameleon.asd: The chameleon․asd file
Lisp File, chameleon/src/chameleon.lisp: The chameleon/src/chameleon․lisp file
Lisp File, chameleon/src/packages.lisp: The chameleon/src/packages․lisp file

Module, chameleon/src: The chameleon/src module

Jump to:   C   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   D   M  
Index Entry  Section

defconfig: Exported macros
defprofile: Exported macros

Macro, defconfig: Exported macros
Macro, defprofile: Exported macros

Jump to:   D   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

chameleon: The chameleon system
chameleon: The chameleon package

Package, chameleon: The chameleon package

System, chameleon: The chameleon system

Jump to:   C   P   S