19.4.2 Composite Types

When none of the simple types is appropriate, you can use composite types, which build new types from other types. Here are several ways of doing that:

(restricted-sexp :match-alternatives criteria)

The value may be any Lisp object that satisfies one of criteria. criteria should be a list, and each elements should be one of these possibilities:

• A predicate—that is, a function of one argument that returns non-nil if the argument fits a certain type. This means that objects of that type are acceptable.
• A quoted constant—that is, 'object. This means that object itself is an acceptable value.

For example,

(restricted-sexp :match-alternatives (integerp 't 'nil))

allows integers, t and nil as legitimate values.

The customization buffer shows all legitimate values using their read syntax, and the user edits them textually.

(cons car-type cdr-type)

The value must be a cons cell, its CAR must fit car-type, and its CDR must fit cdr-type. For example, (cons string symbol) is a customization type which matches values such as ("foo" . foo).

In the customization buffer, the CAR and the CDR are displayed and edited separately, each according to the type that you specify for it.

(list element-types…)

The value must be a list with exactly as many elements as the element-types you have specified; and each element must fit the corresponding element-type.

For example, (list integer string function) describes a list of three elements; the first element must be an integer, the second a string, and the third a function.

In the customization buffer, the each element is displayed and edited separately, according to the type specified for it.

(vector element-types…)

Like list except that the value must be a vector instead of a list. The elements work the same as in list.

(choice alternative-types...)

The value must fit at least one of alternative-types. For example, (choice integer string) allows either an integer or a string.

In the customization buffer, the user selects one of the alternatives using a menu, and can then edit the value in the usual way for that alternative.

Normally the strings in this menu are determined automatically from the choices; however, you can specify different strings for the menu by including the :tag keyword in the alternatives. For example, if an integer stands for a number of spaces, while a string is text to use verbatim, you might write the customization type this way,

(choice (integer :tag "Number of spaces")
        (string :tag "Literal text"))

so that the menu offers ‘Number of spaces’ and ‘Literal Text’.

In any alternative for which nil is not a valid value, other than a const, you should specify a valid default for that alternative using the :value keyword. See Type Keywords.

(const value)

The value must be value—nothing else is allowed.

The main use of const is inside of choice. For example, (choice integer (const nil)) allows either an integer or nil.

:tag is often used with const, inside of choice. For example,

(choice (const :tag "Yes" t)
        (const :tag "No" nil)
        (const :tag "Ask" foo))

(function-item function)

Like const, but used for values which are functions. This displays the documentation string as well as the function name. The documentation string is either the one you specify with :doc, or function’s own documentation string.

(variable-item variable)

Like const, but used for values which are variable names. This displays the documentation string as well as the variable name. The documentation string is either the one you specify with :doc, or variable’s own documentation string.

(set elements…)

The value must be a list and each element of the list must be one of the elements specified. This appears in the customization buffer as a checklist.

(repeat element-type)

The value must be a list and each element of the list must fit the type element-type. This appears in the customization buffer as a list of elements, with ‘[INS]’ and ‘[DEL]’ buttons for adding more elements or removing elements.