1.5 Sexp Types

A number of widgets for editing s-expressions (Lisp types), sexp for short, are also available. These basically fall in several categories described in this section.

1.5.1 The Constant Widgets

The const widget can contain any Lisp expression, but the user is prohibited from editing it, which is mainly useful as a component of one of the composite widgets.

The syntax for the const widget is:

type ::= (const [keyword argument]...  [ value ])

The value, if present, is used to initialize the :value property and can be any s-expression.

Widget: const

This will display any valid s-expression in an immutable part of the buffer.

There are two variations of the const widget, namely variable-item and function-item. These should contain a symbol with a variable or function binding. The major difference from the const widget is that they will allow the user to see the variable or function documentation for the symbol.

Widget: variable-item

An immutable symbol that is bound as a variable.

Widget: function-item

An immutable symbol that is bound as a function.

1.5.2 Generic Sexp Widget

The sexp widget can contain any Lisp expression, and allows the user to edit it inline in the buffer.

The syntax for the sexp widget is:

type ::= (sexp [keyword argument]...  [ value ])

Widget: sexp

This will allow you to edit any valid s-expression in an editable buffer field.

The sexp widget takes the same keyword arguments as the editable-field widget. See section 1.4.5 The editable-field Widget.

1.5.3 Atomic Sexp Widgets

The atoms are s-expressions that do not consist of other s-expressions. For example, a string, a file name, or a symbol are atoms, while a list is a composite type. You can edit the value of an atom with the following widgets.

The syntax for all the atoms are:

type ::= (construct [keyword argument]...  [ value ])

The value, if present, is used to initialize the :value property and must be an expression of the same type as the widget. That is, the string widget can only be initialized with a string.

All the atom widgets take the same keyword arguments as the editable-field widget. See section 1.4.5 The editable-field Widget.

Widget: string

Allows you to edit a string in an editable field.

Widget: regexp

Allows you to edit a regular expression in an editable field.

Widget: character

Allows you to enter a character in an editable field.

Widget: file

Allows you to edit a file name in an editable field.

Keywords:

:must-match

If this is set to non-nil, only existing file names will be allowed in the minibuffer.

Widget: directory

Allows you to edit a directory name in an editable field. Similar to the file widget.

Widget: symbol

Allows you to edit a Lisp symbol in an editable field.

Widget: function

Allows you to edit a lambda expression, or a function name with completion.

Widget: variable

Allows you to edit a variable name, with completion.

Widget: integer

Allows you to edit an integer in an editable field.

Widget: number

Allows you to edit a number in an editable field.

Widget: boolean

Allows you to edit a boolean. In Lisp this means a variable which is either nil meaning false, or non-nil meaning true.

1.5.4 Composite Sexp Widgets

The syntax for the composite widget construct is:

type ::= (construct [keyword argument]...  component...)

where each component must be a widget type. Each component widget will be displayed in the buffer, and will be editable by the user.

Widget: cons

The value of a cons widget must be a cons-cell whose CAR and CDR have two specified types. It uses this syntax:

type ::= (cons [keyword argument]... car-type cdr-type)

Widget: choice

The value matched by a choice widget must have one of a fixed set of types. The widget's syntax is as follows:

type ::= (choice [keyword argument]... type ... )

The value of a choice widget can be anything that matches any of the types.

Widget: list

The value of a list widget must be a list whose element types match the specified component types:

type ::= (list [keyword argument]... component-type...)

Thus, (list string number) matches lists of two elements, the first being a string and the second being a number.

Widget: vector

The vector widget is like the list widget but matches vectors instead of lists. Thus, (vector string number) matches vectors of two elements, the first being a string and the second being a number.

The above suffice for specifying fixed size lists and vectors. To get variable length lists and vectors, you can use a choice, set, or repeat widget together with the :inline keyword. If any component of a composite widget has the :inline keyword set, its value must be a list which will then be spliced into the composite. For example, to specify a list whose first element must be a file name, and whose remaining elements should either be the symbol t or two strings (file names), you can use the following widget specification:

(list file
      (choice (const t)
              (list :inline t
                    :value ("foo" "bar")
                    string string)))

The value of a widget of this type will either have the form (file t) or (file string string).

This concept of :inline may be hard to understand. It was certainly hard to implement, so instead of confusing you more by trying to explain it here, I'll just suggest you meditate over it for a while.

Widget: set

Specifies a type whose values are the lists whose elements all belong to a given set. The order of elements of the list is not significant. Here's the syntax:

type ::= (set [keyword argument]... permitted-element ... )

Use const to specify each permitted element, like this: (set (const a) (const b)).

Widget: repeat

Specifies a list of any number of elements that fit a certain type.

type ::= (repeat [keyword argument]... type)