Go to the first, previous, next, last section, table of contents.


Sexp Types

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

The Constant Widgets.

The const widget can contain any lisp expression, but the user is prohibited from editing edit 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.

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.

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.

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 confuse 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 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.


Go to the first, previous, next, last section, table of contents.