48.6 Adding specifications to a Specifier

Function: add-spec-to-specifier specifier instantiator &optional locale tag-set how-to-add

This function adds a specification to specifier. The specification maps from locale (which should be a window, buffer, frame, device, or the symbol global, and defaults to global) to instantiator, whose allowed values depend on the type of the specifier. Optional argument tag-set limits the instantiator to apply only to the specified tag set, which should be a list of tags all of which must match the device being instantiated over (tags are a device type, a device class, or tags defined with define-specifier-tag). Specifying a single symbol for tag-set is equivalent to specifying a one-element list containing that symbol. Optional argument how-to-add specifies what to do if there are already specifications in the specifier. It should be one of

prepend

Put at the beginning of the current list of instantiators for locale.

append

Add to the end of the current list of instantiators for locale.

remove-tag-set-prepend

This is the default. Remove any existing instantiators whose tag set is the same as tag-set; then put the new instantiator at the beginning of the current list.

remove-tag-set-append

Remove any existing instantiators whose tag set is the same as tag-set; then put the new instantiator at the end of the current list.

remove-locale

Remove all previous instantiators for this locale before adding the new spec.

remove-locale-type

Remove all specifications for all locales of the same type as locale (this includes locale itself) before adding the new spec.

remove-all

Remove all specifications from the specifier before adding the new spec.

remove-tag-set-prepend is the default.

You can retrieve the specifications for a particular locale or locale type with the function specifier-spec-list or specifier-specs.

Function: add-spec-list-to-specifier specifier spec-list &optional how-to-add

This function adds a spec-list (a list of specifications) to specifier. The format of a spec-list is

  ((locale (tag-set . instantiator) ...) ...)

where

• locale := a window, a buffer, a frame, a device, or global
• tag-set := an unordered list of zero or more tags, each of which is a symbol
• tag := a device class (see Consoles and Devices), a device type, or a tag defined with define-specifier-tag
• instantiator := format determined by the type of specifier

The pair (tag-set . instantiator) is called an inst-pair. A list of inst-pairs is called an inst-list. The pair (locale . inst-list) is called a specification. A spec-list, then, can be viewed as a list of specifications.

how-to-add specifies how to combine the new specifications with the existing ones, and has the same semantics as for add-spec-to-specifier.

The higher-level function set-specifier is often more convenient because it allows abbreviations of spec-lists to be used instead of the heavily nested canonical syntax. However, one should take great care in using them with specifiers types which can have lists as instantiators, such as toolbar specifiers and generic specifiers. In those cases it’s probably best to use add-spec-to-specifier or add-spec-list-to-specifier.

Special Form: let-specifier specifier-list &rest body

This special form temporarily adds specifications to specifiers, evaluates forms in body and restores the specifiers to their previous states. The specifiers and their temporary specifications are listed in specifier-list.

The format of specifier-list is

((specifier value &optional locale tag-set how-to-add) ...)

specifier is the specifier to be temporarily modified. value is the instantiator to be temporarily added to specifier in locale. locale, tag-set and how-to-add have the same meaning as in add-spec-to-specifier.

This special form is implemented as a macro; the code resulting from macro expansion will add specifications to specifiers using add-spec-to-specifier. After forms in body are evaluated, the temporary specifications are removed and old specifier spec-lists are restored.

locale, tag-set and how-to-add may be omitted, and default to nil. The value of the last form in body is returned.

NOTE: If you want the specifier’s instance to change in all circumstances, use (selected-window) as the locale. If locale is nil or omitted, it defaults to global.

The following example removes the 3D modeline effect in the currently selected window for the duration of a second:

(let-specifier ((modeline-shadow-thickness 0 (selected-window)))
  (sit-for 1))

Function: set-specifier specifier value &optional locale tag-set how-to-add

This function adds some specifications to specifier. value can be a single instantiator or tagged instantiator (added as a global specification), a list of tagged and/or untagged instantiators (added as a global specification), a cons of a locale and instantiator or locale and instantiator list, a list of such conses, or nearly any other reasonable form. More specifically, value can be anything accepted by canonicalize-spec-list (described below).

locale, tag-set, and how-to-add are the same as in add-spec-to-specifier.

Note that set-specifier is exactly complementary to specifier-specs except in the case where specifier has no specs at all in it but nil is a valid instantiator (in that case, specifier-specs will return nil (meaning no specs) and set-specifier will interpret the nil as meaning “I’m adding a global instantiator and its value is nil”), or in strange cases where there is an ambiguity between a spec-list and an inst-list, etc. (The built-in specifier types are designed in such a way as to avoid any such ambiguities.) For robust code, set-specifier should probably be avoided for specifier types which accept lists as instantiators (currently toolbar specifiers and generic specifiers).

If you want to work with spec-lists, you should probably not use these functions, but should use the lower-level functions specifier-spec-list and add-spec-list-to-specifier. These functions always work with fully-qualified spec-lists; thus, there is no ambiguity.

Function: canonicalize-inst-pair inst-pair specifier-type &optional noerror

This function canonicalizes the given inst-pair.

specifier-type specifies the type of specifier that this spec-list will be used for.

Canonicalizing means converting to the full form for an inst-pair, i.e. (tag-set . instantiator). A single, untagged instantiator is given a tag set of nil (the empty set), and a single tag is converted into a tag set consisting only of that tag.

If noerror is non-nil, signal an error if the inst-pair is invalid; otherwise return t.

Function: canonicalize-inst-list inst-list specifier-type &optional noerror

This function canonicalizes the given inst-list (a list of inst-pairs).

specifier-type specifies the type of specifier that this inst-list will be used for.

Canonicalizing means converting to the full form for an inst-list, i.e. ((tag-set . instantiator) ...). This function accepts a single inst-pair or any abbreviation thereof or a list of (possibly abbreviated) inst-pairs. (See canonicalize-inst-pair.)

If noerror is non-nil, signal an error if the inst-list is invalid; otherwise return t.

Function: canonicalize-spec spec specifier-type &optional noerror

This function canonicalizes the given spec (a specification).

specifier-type specifies the type of specifier that this spec-list will be used for.

Canonicalizing means converting to the full form for a spec, i.e. (locale (tag-set . instantiator) ...). This function accepts a possibly abbreviated inst-list or a cons of a locale and a possibly abbreviated inst-list. (See canonicalize-inst-list.)

If noerror is nil, signal an error if the specification is invalid; otherwise return t.

Function: canonicalize-spec-list spec-list specifier-type &optional noerror

This function canonicalizes the given spec-list (a list of specifications).

specifier-type specifies the type of specifier that this spec-list will be used for.

If noerror is nil, signal an error if the spec-list is invalid; otherwise return t for an invalid spec-list. (Note that this cannot be confused with a canonical spec-list.)

Canonicalizing means converting to the full form for a spec-list, i.e. ((locale (tag-set . instantiator) ...) ...). This function accepts a possibly abbreviated specification or a list of such things. (See canonicalize-spec.) This is the function used to convert spec-lists accepted by set-specifier and such into a form suitable for add-spec-list-to-specifier.

This function tries extremely hard to resolve any ambiguities, and the built-in specifier types (font, image, toolbar, etc.) are designed so that there won’t be any ambiguities.

The canonicalization algorithm is as follows:

1. Attempt to parse spec-list as a single, possibly abbreviated, specification.
2. If that fails, attempt to parse spec-list as a list of (abbreviated) specifications.
3. If that fails, spec-list is invalid.

A possibly abbreviated specification spec is parsed by

1. Attempt to parse spec as a possibly abbreviated inst-list.
2. If that fails, attempt to parse spec as a cons of a locale and an (abbreviated) inst-list.
3. If that fails, spec is invalid.

A possibly abbreviated inst-list inst-list is parsed by

1. Attempt to parse inst-list as a possibly abbreviated inst-pair.
2. If that fails, attempt to parse inst-list as a list of (abbreviated) inst-pairs.
3. If that fails, inst-list is invalid.

A possibly abbreviated inst-pair inst-pair is parsed by

1. Check if inst-pair is valid-instantiator-p.
2. If not, check if inst-pair is a cons of something that is a tag, ie, valid-specifier-tag-p, and something that is valid-instantiator-p.
3. If not, check if inst-pair is a cons of a list of tags and something that is valid-instantiator-p.
4. Otherwise, inst-pair is invalid.

In summary, this function generally prefers more abbreviated forms.