1.5 Sexp Types

A number of widgets for editing s-expressions (lisp types) are also available. These basically fall in the following categories.

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.

1.5.3 Atomic Sexp Widgets.

The atoms are s-expressions that does not consist of other s-expressions. A string is an atom, 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 ::= (NAME [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. I.e. the string widget can only be initialized with a string.

All the atom widgets take the same keyword arguments as 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. If you invoke the tag button, you can edit the file name in the mini-buffer with completion.

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 are

TYPE ::= (NAME [KEYWORD ARGUMENT]...  COMPONENT...)

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

Widget: cons

The value of a cons widget is a cons-cell where the car is the value of the first component and the cdr is the value of the second component. There must be exactly two components.

Widget: list

The value of a list widget is a list containing the value of each of its component.

Widget: vector

The value of a vector widget is a vector containing the value of each of its component.

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 widgets together with the :inline keywords. 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 arguments should either by the symbol t or two files, 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 is probably 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: choice

Allows you to edit a sexp which may have one of a fixed set of types. It is currently implemented with the choice-menu basic widget, and has a similar syntax.

Widget: set

Allows you to specify a type which must be a list whose elements all belong to given set. The elements of the list is not significant. This is implemented on top of the checklist basic widget, and has a similar syntax.

Widget: repeat

Allows you to specify a variable length list whose members are all of the same type. Implemented on top of the `editable-list' basic widget, and has a similar syntax.