14.4.1 Simple Types

This section describes all the simple customization types.

sexp

The value may be any Lisp object that can be printed and read back. You can use sexp as a fall-back for any option, if you don't want to take the time to work out a more specific type to use.

integer

The value must be an integer, and is represented textually in the customization buffer.

number

The value must be a number, and is represented textually in the customization buffer.

string

The value must be a string, and the customization buffer shows just the contents, with no delimiting `"' characters and no quoting with `\'.

regexp

Like string except that the string must be a valid regular expression.

character

The value must be a character code. A character code is actually an integer, but this type shows the value by inserting the character in the buffer, rather than by showing the number.

file

The value must be a file name, and you can do completion with M-TAB.

(file :must-match t)

The value must be a file name for an existing file, and you can do completion with M-TAB.

directory

The value must be a directory name, and you can do completion with M-TAB.

hook

The value must be a list of functions (or a single function, but that is obsolete usage). This customization type is used for hook variables. You can use the :options keyword in a hook variable's defcustom to specify a list of functions recommended for use in the hook; see 14.3 Defining Customization Variables.

alist

The value must be a list of cons-cells, the CAR of each cell representing a key, and the CDR of the same cell representing an associated value. The user can add and delete key/value pairs, and edit both the key and the value of each pair.

You can specify the key and value types like this:

(alist :key-type key-type :value-type value-type)

where key-type and value-type are customization type specifications. The default key type is sexp, and the default value type is sexp.

The user can add any key matching the specified key type, but you can give some keys a preferential treatment by specifying them with the :options (see 14.3 Defining Customization Variables). The specified keys will always be shown in the customize buffer (together with a suitable value), with a checkbox to include or exclude or disable the key/value pair from the alist. The user will not be able to edit the keys specified by the :options keyword argument.

The argument to the :options keywords should be a list of option specifications. Ordinarily, the options are simply atoms, which are the specified keys. For example:

:options '("foo" "bar" "baz")

specifies that there are three "known" keys, namely "foo", "bar" and "baz", which will always be shown first.

You may want to restrict the value type for specific keys, for example, the value associated with the "bar" key can only be an integer. You can specify this by using a list instead of an atom in the option specification. The first element will specify the key, like before, while the second element will specify the value type.

:options '("foo" ("bar" integer) "baz")

Finally, you may want to change how the key is presented. By default, the key is simply shown as a const, since the user cannot change the special keys specified with the :options keyword. However, you may want to use a more specialized type for presenting the key, like function-item if you know it is a symbol with a function binding. This is done by using a customization type specification instead of a symbol for the key.

:options '("foo" ((function-item some-function) integer) "baz")

Many alists use lists with two elements, instead of cons cells. For example,

(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) "Each element is a list of the form (KEY VALUE).")

instead of

(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3)) "Each element is a cons-cell (KEY . VALUE).")

Because of the way lists are implemented on top of cons cells, you can treat list-alist in the example above as a cons cell alist, where the value type is a list with a single element containing the real value.

(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) "Each element is a list of the form (KEY VALUE)." :type '(alist :value-type (group integer)))

The group widget is used here instead of list only because the formatting is better suited for the purpose.

Similarily, you can have alists with more values associated with each key, using variations of this trick:

(defcustom person-data '(("brian" 50 t) ("dorith" 55 nil) ("ken" 52 t)) "Alist of basic info about people. Each element has the form (NAME AGE MALE-FLAG)." :type '(alist :value-type (group age boolean))) (defcustom pets '(("brian") ("dorith" "dog" "guppy") ("ken" "cat")) "Alist of people's pets. In an element (KEY . VALUE), KEY is the person's name, and the VALUE is a list of that person's pets." :type '(alist :value-type (repeat string)))

plist

The plist custom type is similar to the alist (see above), except that the information is stored as a property list, i.e. a list of this form:

(key value key value key value ...)

The default :key-type for plist is symbol, rather than sexp.

symbol

The value must be a symbol. It appears in the customization buffer as the name of the symbol.

function

The value must be either a lambda expression or a function name. When it is a function name, you can do completion with M-TAB.

variable

The value must be a variable name, and you can do completion with M-TAB.

face

The value must be a symbol which is a face name, and you can do completion with M-TAB.

boolean

The value is boolean--either nil or t. Note that by using choice and const together (see the next section), you can specify that the value must be nil or t, but also specify the text to describe each value in a way that fits the specific meaning of the alternative.

coding-system

The value must be a coding-system name, and you can do completion with M-TAB.

color

The value must be a valid color name, and you can do completion with M-TAB. A sample is provided,