48. Specifiers

A specifier is an object used to keep track of a property whose value should vary according to display context, a window, a frame, or device, or a Mule character set. The value of many built-in properties, such as the font, foreground, background, and such properties of a face and variables such as modeline-shadow-thickness and top-toolbar-height, is actually a specifier object. The specifier object, in turn, is “instantiated” in a particular situation to yield the real value of the property in the current context.

Function: specifierp object

This function returns non-nil if object is a specifier.

48.1 Introduction to Specifiers

Perhaps the most useful way to explain specifiers is via an analogy. Emacs Lisp programmers are used to buffer-local variables Buffer-Local Variables. For example, the variable modeline-format, which controls the format of the modeline, can have different values depending on the particular buffer being edited. The variable has a default value which most modes will use, but a specialized package such as Calendar might change the variable so as to tailor the modeline to its own purposes. Other variables are perhaps best thought of as “mode local,” such as font-lock keywords, but they are implemented as buffer locals.

Other properties (such as those that can be changed by the modify-frame-parameters function, for example the color of the text cursor) can have frame-local values, although it might also make sense for them to have buffer-local values. In other cases, you might want the property to vary depending on the particular window within the frame that applies (e.g. the top or bottom window in a split frame), the device type that that frame appears on (X or tty), etc. Perhaps you can envision some more complicated scenario where you want a particular value in a specified buffer, another value in all other buffers displayed on a particular frame, another value in all other buffers displayed in all other frames on any mono (two-color, e.g. black and white only) displays, and a default value in all other circumstances.

Specifiers generalize both buffer- and frame-local properties. Specifiers vary according to the display context. Font-lock keywords in a buffer will be the same no matter which window the buffer is displayed in, but windows on TTY devices will simply not be capable of the flexibility that windows on modern GUI devices are. Specifiers provide a way for the programmer to declare that an emphasized text should be italic on GUI devices and inverse video on TTYs. They also provide a way for the programmer to declare fallbacks, so that a color specified as “chartreuse” where possible can fall back to “yellow” on devices where only ANSI (4-bit) color is available. The complex calculations and device querying are transparent to both user and programmer. You ask for what you want; it’s up to XEmacs to provide it, or a reasonable approximation.

We call such a declaration a specification. A specification applies in a particular locale, which is a window, buffer, frame, device, or the global locale. The value part of the specification is called an instantiator. The process of determining the value in a particular context, or domain, is called instantiation. A domain is a window, frame, or device.

The difference between locale and domain is somewhat subtle. You may think of a locale as a class of domains, which may span different devices. Since the specification is abstract (a Lisp form), you can state it without reference to a device. On the other hand, when you instantiate a specification, you must know the type of the device. It is useless to specify that “blue means emphasis” on a monochrome device. Thus instantiation requires specification of the device on which it will be rendered.

Thus a specifier allows a great deal of flexibility in controlling exactly what value a property has in which circumstances. Specifiers are most commonly used for display properties, such as an image or the foreground color of a face. As a simple example, you can specify that the foreground of the default face be

• blue for a particular buffer
• green for all other buffers

As a more complicated example, you could specify that the foreground of the default face be

• forest green for all buffers displayed in a particular Emacs window, or green if the X server doesn’t recognize the color ‘forest green’
• blue for all buffers displayed in a particular frame
• red for all other buffers displayed on a color device
• white for all other buffers

48.2 Simple Specifier Usage

A useful specifier application is adding a button to a toolbar. XEmacs provides several toolbars, one along each edge of the frame. Normally only one is used at a time, the default. The default toolbar is actually a specifier object which is the value of default-toolbar. See section Toolbar Intro.

The specification of a toolbar is simple: it is a list of buttons. Each button is a vector with four elements: an icon, a command, the enabled flag, and a help string. Let’s retrieve the instance of the toolbar you see in the selected frame.

(specifier-instance default-toolbar)

The value returned is, as promised, a list of vectors. Now let’s build up a button, and add it to the toolbar. Our button will invoke the last defined keyboard macro. This is an alternative to name-last-kbd-macro for creating a persistent macro, rather than an alias for C-x e.

A toolbar button icon can be quite sophisticated, with different images for button up, button down, and disabled states, and a similar set with captions. We’ll use a very simple icon, but we have to jump through a few non-obvious hoops designed to support the sophisticated applications. The rest of the button descriptor is straightforward.

(setq toolbar-my-kbd-macro-button
  `[ (list (make-glyph "MyKbdMac"))
     (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
     t
     "Execute a previously defined keyboard macro." ])

(set-specifier default-toolbar
               (cons toolbar-my-kbd-macro-button
                     (specifier-specs default-toolbar 'global))
               'global)

To remove the button, just substitute the function delete for the cons above.

What is the difference between specifier-instance, which we used in the example of retrieving the toolbar descriptor, and specifier-specs, which was used in the toolbar manipulating code? specifier-specs retrieves a copy of the instantiator, which is abstract and does not depend on context. specifier-instance, on the other hand, actually instantiates the specification, and returns the result for the given context. Another way to express this is: specifier-specs takes a locale as an argument, while specifier-instance takes a domain. The reason for providing specifier-instance is that sometimes you wish to see the object that XEmacs will actually use. specifier-specs, on the other hand, shows you what the programmer (or user) requested. When a program manipulates specifications, clearly it’s the latter that is desirable.

In the case of the toolbar descriptor, it turns out that these are the same: the instantiation process is trivial. However, many specifications have non-trivial instantiation. Compare the results of the following forms on my system. (The ‘(cdr (first ...))’ form is due to my use of Mule. On non-Mule XEmacsen, just use specifier-specs.)

(cdr (first (specifier-specs (face-font 'default) 'global)))
=> "-*--14-*jisx0208*-0"

(specifier-instance (face-font 'default))
#<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 0xe0028b 0x176b>

In this case, specifier-instance returns an opaque object; Lisp programs can’t work on it, they can only pass it around. Worse, in some environments the instantiation will fail, resulting in a different value (when another instantiation succeeds), or worse yet, an error, if all attempts to instantiate the specifier fail. specifier-instance is context-dependent, even for the exact same specification. specifier-specs is deterministic, and only depends on the specifications.

Note that in the toolbar-changing code we operate in the global locale. This means that narrower locales, if they have specifications, will shadow our changes. (Specifier instantiation does not merge specifications. It selects the "highest-priority successful specification" and instantiates that.)

In fact, in our example, it seems pretty likely that different buffers should have different buttons. (The icon can be the same, but the keyboard macro you create in a Dired buffer is highly unlikely to be useful in a LaTeX buffer!) Here’s one way to implement this:

(setq toolbar-my-kbd-macro-button
  `[ (list (make-glyph "MyKbdMac"))
     (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
     t
     "Execute a previously defined keyboard macro." ])

(set-specifier default-toolbar
               (cons toolbar-my-kbd-macro-button
                     (cond ((specifier-specs default-toolbar
                                             (current-buffer)))
                           ((specifier-specs default-toolbar
                                             'global)))
               (current-buffer))

Finally, a cautionary note: the use of specifier-specs in the code above is for expository purposes. Don’t use it in production code. In fact, the set-specifier form above is likely to fail occasionally, because you can add many specifications for the same locale.

In these cases, specifier-specs will return a list. A further refinement is that a specification may be associated with a set of specifier tags. If the list of specifier tags is non-nil, then specifier-specs will return a cons of the tag set and the instantiator. Evidently specifier-specs is a bit unreliable. (For toolbars, the code above should work 99% of the time, because toolbars are rarely changed. Since instantiation is trivial, multiple specs are not useful—the first one always succeeds.)

In fact, specifier-specs is intended to be used to display specs to humans with a minimum of clutter. The robust way to access specifications is via specifier-spec-list. See section Adding specifications to a Specifier, for the definition of spec-list. See section Retrieving the Specifications from a Specifier, for documentation of specifier-specs and specifier-spec-list. To get the desired effect, replace the form (specifier-spec default-toolbar 'global) with

(cdr (second (first (specifier-spec-list default-toolbar 'global))))

(It should be obvious why the example uses the lazy unreliable method!)

48.3 In-Depth Overview of a Specifier

Having variables vary according the editing context is very useful, and the buffer is the natural “atomic” unit of editing context. In a GUI environment, it can be similarly useful to have variables whose values vary according to display context. The atomic unit of display context is the Emacs window. Buffers are cleanly grouped by modes, but windows are not so easily pigeonholed. On the one hand, a window displays a buffer, and thus one possible hierarchy is window, buffer, mode. On the other, a window is a component of a frame. This generates the window, frame, device hierarchy. Finally, there are objects such as toolbars whose properties are described by specifiers. These do not fit naturally into either hierarchy. This problem is as yet not cleanly solved.

Another potential source of conceptual confusion is the instantiation process. Instantiating a buffer-local variable is simple: at any given point in time there is a current buffer, and its local values are used and set whenever the variable is accessed, unless the programmer goes to some special effort (uses default-value and set-default. However, a specifier object encapsulates a set of specifications, each of which says what its value should be if a particular condition applies. Several such conditions might apply simultaneously in a given window.

For example, one specification might be “The value should be darkseagreen2 on X devices” another might be “The value should be blue in the *Help* buffer”. So what do we do for "the *Help* buffer on an X device"? The answer is simple: give each type of locale a priority and check them in priority order, returning the first instantiator that successfully instantiates a value.

Given a specifier, a logical question is “What is its value in a particular situation?” This involves looking through the specifications to see which ones apply to this particular situation, and perhaps preferring one over another if more than one applies. In specifier terminology, a “particular situation” is called a domain, and determining its value in a particular domain is called instantiation. Most of the time, a domain is identified by a particular window. For example, if the redisplay engine is drawing text in the default face in a particular window, it retrieves the specifier for the foreground color of the default face and instantiates it in the domain given by that window; in other words, it asks the specifier, “What is your value in this window?”.

Note that the redisplay example is in a sense canonical. That is, specifiers are designed to present a uniform and efficient API to redisplay. It is the efficiency constraint that motivates the introduction of specifier tags, and many restrictions on access (for example, a buffer is not a domain, and you cannot instantiate a specifier over a buffer).

More specifically, a specifier contains a set of specifications, each of which associates a locale (a window object, a buffer object, a frame object, a device object, or the symbol global) with an inst-list, which is a list of one or more inst-pairs. (For each possible locale, there can be at most one specification containing that locale.) Each inst-pair is a cons of a tag set (an unordered list of zero or more symbols, or tags) and an instantiator (the allowed form of this varies depending on the type of specifier). In a given specification, there may be more than one inst-pair with the same tag set; this is unlike for locales.

The tag set is used to restrict the sorts of devices and character sets over which the instantiator is valid and to uniquely identify instantiators added by a particular application, so that different applications can work on the same specifier and not interfere with each other.

Each tag can have a device-predicate associated with it, which is a function of one argument (a device) that specifies whether the tag matches that particular device. (If a tag does not have a predicate, it matches all devices.) All tags in a tag set must match a device for the associated inst-pair to be instantiable over that device. (A null tag set is perfectly valid, and trivially matches all devices.)

Each tag can also have a charset-predicate associated with it; this is a function that takes one charset argument, and specifies whether that tag matches that particular charset. When instantiating a face over a given domain with a given charset, the charset-predicate attribute of a tag is consulted(5) to decide whether this inst-pair matches the charset. If the charset-predicate function of a tag is unspecified, that tag defaults to matching all charsets.

When charset-predicates are being taken into account, the matching process becomes two-stage. The first stage pays attention to the charset predicates and the device predicates; only if there is no match does the second stage take place, in which charset predicates are ignored, and only the device predicates are relevant.

The valid device types in a build (normally x, tty, stream, mswindows, msprinter, and possibly carbon) and device classes (normally color, grayscale, and mono) can always be used as tags, and match devices of the associated type or class (see section Consoles and Devices). There are also built-in tags related to font instantiation and translation to Unicode; they are identical to the symbols used with specifier-matching-instance, see the documentation of that function for their names.

User-defined tags may be defined, with optional device and charset predicates specified. An application can create its own tag, use it to mark all its instantiators, and be fairly confident that it will not interfere with other applications that modify the same specifier—functions that add a specification to a specifier usually only overwrite existing inst-pairs with the same tag set as was given, and a particular tag or tag set can be specified when removing instantiators.

When a specifier is instantiated in a domain, both the locale and the tag set can be viewed as specifying necessary conditions that must apply in that domain for an instantiator to be considered as a possible result of the instantiation. More specific locales always override more general locales (thus, there is no particular ordering of the specifications in a specifier); however, the tag sets are simply considered in the order that the inst-pairs occur in the specification’s inst-list.

Note also that the actual object that results from the instantiation (called an instance object) may not be the same as the instantiator from which it was derived. For some specifier types (such as integer specifiers and boolean specifiers), the instantiator will be returned directly as the instance object. For other types, however, this is not the case. For example, for font specifiers, the instantiator is a font-description string and the instance object is a font-instance object, which describes how the font is displayed on a particular device. A font-instance object encapsulates such things as the actual font name used to display the font on that device (a font-description string under X is usually a wildcard specification that may resolve to different font names, with possibly different foundries, widths, etc., on different devices), the extra properties of that font on that device, etc. Furthermore, this conversion (called instantiation) might fail—a font or color might not exist on a particular device, for example.

48.4 How a Specifier Is Instantiated

Instantiation of a specifier in a particular window domain proceeds as follows:

• First, XEmacs searches for a specification whose locale is the same as the window. If that fails, the search is repeated, looking for a locale that is the same as the window’s buffer. If that fails, the search is repeated using the window’s frame, then using the device that frame is on. Finally, the specification whose locale is the symbol global (if there is such a specification) is considered.
• The inst-pairs contained in the specification that was found are considered in their order in the inst-list, looking for one whose tag set matches the device that is derived from the window domain. (The tag set is an unordered list of zero or more tag symbols. For all tags that have predicates associated with them, the predicate must match the device.)
• If a matching tag set is found, the corresponding instantiator is passed to the specifier’s instantiation method, which is specific to the type of the specifier. If it succeeds, the resulting instance object is returned as the result of the instantiation and the instantiation is done. Otherwise, the operation continues, looking for another matching inst-pair in the current specification.
• When there are no more inst-pairs to be considered in the current specification, the search starts over, looking for another specification as in the first step above.
• If all specifications are exhausted and no instance object can be derived, the instantiation fails. (Actually, this is not completely true. Some specifier objects for built-in properties have a fallback value, which is either an inst-list or another specifier object, that is consulted if the instantiation is about to fail. If it is an inst-list, the searching proceeds using the inst-pairs in that list. If it is a specifier, the entire instantiation starts over using that specifier instead of the given one. Fallback values are set by the C code and cannot be modified, except perhaps indirectly, using any Lisp functions. The purpose of them is to supply some values to make sure that instantiation of built-in properties can’t fail and to implement some basic specifier inheritance, such as the fact that faces inherit their properties from the default face.)

It is also possible to instantiate a specifier over a frame domain or device domain instead of over a window domain. The C code, for example, instantiates the top-toolbar-height variable over a frame domain in order to determine the height of a frame’s top toolbar. Instantiation over a frame or device is similar to instantiation over a window except that specifications for locales that cannot be derived from the domain are ignored. Specifically, instantiation over a frame looks first for frame locales, then device locales, then the global locale. Instantiation over a device domain looks only for device locales and the global locale.

Note that specifiers are instantiated on every redisplay. (This is the concept; of course the implementation keeps track of changes and doesn’t reinstantiate unchanged specifiers.) That means that changes in specifiers controlling appearance are reflected immediately in the UI. Also, since specifiers are instantiated completely, removing a specification can be just as effective as adding one.

E.g., Giacomo Boffi wanted a modeline that indicates whether the frame containing it is selected or not. The first proposed implementation is natural in a world of “local” variables. The later implementations apply the power of specifiers.

(The copyright notice and permission statement below apply to the code in example format, up to the “;;; end of neon-modeline.el” comment.)

;;; neon-modeline.el

;; Copyright (c) 2004  Stephen J. Turnbull <stephen@xemacs.org>

;; Based on a suggestion by Giacomo Boffi

;; This code may be used and redistributed under the GNU GPL, v.2 or any
;; later version as published by the FSF, or under the license used for
;; XEmacs Texinfo manuals, at your option.

A few customizations:

;; Placate the specifier and Customize gods.

(unless (valid-specifier-tag-p 'modeline-background)
  (define-specifier-tag 'modeline-background))

(defgroup lisp-demos nil "Demos for Lisp programming techniques.")

(defgroup neon-modeline nil "Neon modeline identifies selected frame."
  :group 'lisp-demos)

(defcustom neon-modeline-selected-background "LemonChiffon"
  "Background color for modeline in selected frames."
  :type 'color
  :group 'neon-modeline)

(defcustom neon-modeline-deselected-background "Wheat"
  "Background color for modeline in unselected frames."
  :type 'color
  :group 'neon-modeline)

Our first try uses three functions, a setup and two hook functions. Separate hooks are defined for entry into a frame and exit from it. Since we’re using hooks, it’s a fairly natural approach: we operate on the background on each event corresponding to an appearance change we want to make. This doesn’t depend on the specifier API, “frame-local” variables would serve as well.

(defun select-modeline ()
  (set-face-background 'modeline neon-modeline-selected-background
		       (selected-frame)))

(defun deselect-modeline ()
  (set-face-background 'modeline neon-modeline-deselected-background
		       (selected-frame)))

Note that the initialization removes no specifications, and therefore is not idempotent. Cruft will accumulate in the specifier if the ‘-setup’ function is called repeatedly. This shouldn’t cause a performance problem; specifiers are quite efficient for their purpose. But it’s ugly, and wastes a small amount of space.

(defun neon-modeline-setup ()
  (interactive)
  (set-face-background 'modeline neon-modeline-deselected-background)
  ;; Add the distinguished background on pointer entry to the frame;
  (add-hook 'select-frame-hook 'select-modeline)
  ;; restore the ordinary background on pointer exit from the frame.
  (add-hook 'deselect-frame-hook 'deselect-modeline)

This approach causes a decided flicker on Boffi’s platform, because the two hook functions are executed in response to separate GUI events.

The following code should be an improvement. First, the hook function.

(defun neon-modeline-reselect ()
  (set-face-background 'modeline neon-modeline-deselected-background
		       (selected-frame) '(modeline-background)
		       'remove-locale-type))

Only one event triggers the configuration change, which should reduce flicker. Because this is implemented as a specifier, we can use the specifier API to reset all frame-local specifications (the remove-locale-type argument). This leaves the global specification alone, but removes all existing frame-local specifications. Then it adds the selected-frame background specification for the newly selected frame. I.e., this effectively implements a “move specification from frame to frame” operation.

Why does it give the desired result? By ensuring that only one frame has the selected-frame modeline background. Frame-local specifications have precedence over global ones, so when the modeline background is instantiated in the selected frame, it matches the specification set up for it and gets the right color. On the other hand, in any other frame, it does not match the selected frame, so it falls through the frame-local specifications and picks up the global specification. Again we get the desired color, in this case for unselected frames.

Here the modeline-background tag is simply good practice (identifying an application’s specifications allows it to avoid interfering with other applications, and other well-behaved applications and Customize should not munge specifications with our tag on them). However, an alternative implementation of this functionality would be

(defun neon-modeline-reselect-2 ()
  (set-face-background 'modeline neon-modeline-deselected-background
		       (selected-frame) '(modeline-background)
		       'remove-tag-set-prepend))

neon-modeline-reselect may be a preferable implementation here, if we really want only one frame to have a local specification. The neon-modeline-reselect-2 style would be useful if we had groups of frames which have different modeline backgrounds when deselected.

Here’s the initialization function, with different semantics from above. Note that it is destructive, unless the user saves off the state of the modeline face before invoking the function. This is only a problem if you remove specifications and expect the older ones to persist. In this example it should not be an issue. We use the customizations defined above.

(defun neon-modeline-modified-setup ()
  (interactive)
  (set-face-background 'modeline neon-modeline-selected-background
		       'global nil 'remove-all)
  (add-hook 'select-frame-hook 'neon-modeline-reselect)

;;; end of neon-modeline.el

Note the use of 'remove-all to clear out stale specifications. Thus it will be idempotent.

48.5 Specifier Types

There are various different types of specifiers. The type of a specifier controls what sorts of instantiators are valid, how an instantiator is instantiated, etc. Here is a list of built-in specifier types:

boolean

The valid instantiators are the symbols t and nil. Instance objects are the same as instantiators so no special instantiation function is needed.

integer

The valid instantiators are integers. Instance objects are the same as instantiators so no special instantiation function is needed. modeline-shadow-thickness is an example of an integer specifier (negative thicknesses indicate that the shadow is drawn recessed instead of raised).

natnum

The valid instantiators are natnums (non-negative integers). Instance objects are the same as instantiators so no special instantiation function is needed. Natnum specifiers are used for dimension variables such as top-toolbar-height.

generic

All Lisp objects are valid instantiators. Instance objects are the same as instantiators so no special instantiation function is needed.

font

The valid instantiators are strings describing fonts or vectors indicating inheritance from the font of some face. Instance objects are font-instance objects, which are specific to a particular device. The instantiation method for font specifiers can fail, unlike for integer, natnum, boolean, and generic specifiers.

color

The valid instantiators are strings describing colors or vectors indicating inheritance from the foreground or background of some face. Instance objects are color-instance objects, which are specific to a particular device. The instantiation method for color specifiers can fail, as for font specifiers.

image

Images are perhaps the most complicated type of built-in specifier. The valid instantiators are strings (a filename, inline data for a pixmap, or text to be displayed in a text glyph) or vectors describing inline data of various sorts or indicating inheritance from the background-pixmap property of some face. Instance objects are either strings (for text images), image-instance objects (for pixmap images), or subwindow objects (for subwindow images). The instantiation method for image specifiers can fail, as for font and color specifiers.

face-boolean

The valid instantiators are the symbols t and nil and vectors indicating inheritance from a boolean property of some face. Specifiers of this sort are used for all of the built-in boolean properties of faces. Instance objects are either the symbol t or the symbol nil.

toolbar

The valid instantiators are toolbar descriptors, which are lists of toolbar-button descriptors (each of which is a vector of two or four elements). See section Toolbar, for more information.

Color and font instance objects can also be used in turn as instantiators for a new color or font instance object. Since these instance objects are device-specific, the instantiator can be used directly as the new instance object, but only if they are of the same device. If the devices differ, the base color or font of the instantiating object is effectively used instead as the instantiator.

See section Faces and Window-System Objects, for more information on fonts, colors, and face-boolean specifiers. See section Glyphs, for more information about image specifiers. See section Toolbar, for more information on toolbar specifiers.

Function: specifier-type specifier

This function returns the type of specifier. The returned value will be a symbol: one of integer, boolean, etc., as listed in the above table.

Functions are also provided to query whether an object is a particular kind of specifier:

Function: boolean-specifier-p object

This function returns non-nil if object is a boolean specifier.

Function: integer-specifier-p object

This function returns non-nil if object is an integer specifier.

Function: natnum-specifier-p object

This function returns non-nil if object is a natnum specifier.

Function: generic-specifier-p object

This function returns non-nil if object is a generic specifier.

Function: face-boolean-specifier-p object

This function returns non-nil if object is a face-boolean specifier.

Function: toolbar-specifier-p object

This function returns non-nil if object is a toolbar specifier.

Function: font-specifier-p object

This function returns non-nil if object is a font specifier.

Function: color-specifier-p object

This function returns non-nil if object is a color specifier.

Function: image-specifier-p object

This function returns non-nil if object is an image specifier.

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

Macro: let-specifier specifier-list &rest body

This macro 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.

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.

48.7 Retrieving the Specifications from a Specifier

Function: specifier-spec-list specifier &optional locale tag-set exact-p

This function returns the spec-list of specifications for specifier in locale.

If locale is a particular locale (a window, buffer, frame, device, or the symbol global), a spec-list consisting of the specification for that locale will be returned.

If locale is a locale type (i.e. one of the symbols window, buffer, frame, or device), a spec-list of the specifications for all locales of that type will be returned.

If locale is nil or the symbol all, a spec-list of all specifications in specifier will be returned.

locale can also be a list of locales, locale types, and/or all; the result is as if specifier-spec-list were called on each element of the list and the results concatenated together.

Only instantiators where tag-set (a list of zero or more tags) is a subset of (or possibly equal to) the instantiator’s tag set are returned. (The default value of nil is a subset of all tag sets, so in this case no instantiators will be screened out.) If exact-p is non-nil, however, tag-set must be equal to an instantiator’s tag set for the instantiator to be returned.

Function: specifier-specs specifier &optional locale tag-set exact-p

This function returns the specification(s) for specifier in locale.

If locale is a single locale or is a list of one element containing a single locale, then a “short form” of the instantiators for that locale will be returned. Otherwise, this function is identical to specifier-spec-list.

The “short form” is designed for readability and not for ease of use in Lisp programs, and is as follows:

1. If there is only one instantiator, then an inst-pair (i.e. cons of tag and instantiator) will be returned; otherwise a list of inst-pairs will be returned.
2. For each inst-pair returned, if the instantiator’s tag is any, the tag will be removed and the instantiator itself will be returned instead of the inst-pair.
3. If there is only one instantiator, its value is nil, and its tag is any, a one-element list containing nil will be returned rather than just nil, to distinguish this case from there being no instantiators at all.

Function: specifier-fallback specifier

This function returns the fallback value for specifier. Fallback values are provided by the C code for certain built-in specifiers to make sure that instantiation won’t fail even if all specs are removed from the specifier, or to implement simple inheritance behavior (e.g. this method is used to ensure that faces other than default inherit their attributes from default). By design, you cannot change the fallback value, and specifiers created with make-specifier will never have a fallback (although a similar, Lisp-accessible capability may be provided in the future to allow for inheritance).

The fallback value will be an inst-list that is instantiated like any other inst-list, a specifier of the same type as specifier (results in inheritance), or nil for no fallback.

When you instantiate a specifier, you can explicitly request that the fallback not be consulted. (The C code does this, for example, when merging faces.) See specifier-instance.

48.8 Working With Specifier Tags

A specifier tag set is an entity that is attached to an instantiator and can be used to restrict the scope of that instantiator to a particular device class or device type and/or to mark instantiators added by a particular package so that they can be later removed.

A specifier tag set consists of a list of zero or more specifier tags, each of which is a symbol that is recognized by XEmacs as a tag. (The valid device types and device classes are always tags, as are any tags defined by define-specifier-tag.) It is called a “tag set” (as opposed to a list) because the order of the tags or the number of times a particular tag occurs does not matter.

Each tag has a device predicate associated with it, which specifies whether that tag applies to a particular device. The tags which are device types and classes match devices of that type or class. User-defined tags can have any device predicate, or none (meaning that all devices match). When attempting to instantiate a specifier, a particular instantiator is only considered if the device of the domain being instantiated over matches all tags in the tag set attached to that instantiator.

Each tag can also have a charset predicate, specifying whether that tag applies to a particular charset. There are a few tags with predefined charset predicates created to allow sensible fallbacks in the face code—see the output of (specifier-fallback (face-font 'default)) for these.

Most of the time, a tag set is not specified, and the instantiator gets a null tag set, which matches all devices and all character sets (when possible; fonts with an inappropriate repertoire will not match, for example).

Function: valid-specifier-tag-p tag

This function returns non-nil if tag is a valid specifier tag.

Function: valid-specifier-tag-set-p tag-set

This function returns non-nil if tag-set is a valid specifier tag set.

Function: canonicalize-tag-set tag-set

This function canonicalizes the given tag set. Two canonicalized tag sets can be compared with equal to see if they represent the same tag set. (Specifically, canonicalizing involves sorting by symbol name and removing duplicates.)

Function: device-matches-specifier-tag-set-p device tag-set

This function returns non-nil if device matches specifier tag set tag-set. This means that device matches each tag in the tag set.

Function: define-specifier-tag tag &optional device-predicate charset-predicate

This function defines a new specifier tag. If device-predicate is specified, it should be a function of one argument (a device) that specifies whether the tag matches that particular device. If device-predicate is omitted, the tag matches all devices.

If charset-predicate is specified, it should be a function taking one character set argument that specifies whether the tag matches that particular character set.

You can redefine an existing user-defined specifier tag. However, you cannot redefine the built-in specifier tags (the device types and classes) or the symbols nil, t, all, or global.

Function: device-matching-specifier-tag-list &optional device

This function returns a list of all specifier tags matching device. device defaults to the selected device if omitted.

Function: specifier-tag-list

This function returns a list of all currently-defined specifier tags. This includes the built-in ones (the device types and classes).

Function: specifier-tag-device-predicate tag

This function returns the device predicate for the given specifier tag.

Function: specifier-tag-charset-predicate tag

This function returns the charset predicate for the given specifier tag.

48.9 Functions for Instantiating a Specifier

Function: specifier-instance specifier &optional domain default no-fallback

This function instantiates specifier (returns its value) in domain. If no instance can be generated for this domain, return default.

domain should be a window, frame, or device. Other values that are legal as a locale (e.g. a buffer) are not valid as a domain because they do not provide enough information to identify a particular device (see valid-specifier-domain-p). domain defaults to the selected window if omitted.

Instantiating a specifier in a particular domain means determining the specifier’s “value” in that domain. This is accomplished by searching through the specifications in the specifier that correspond to all locales that can be derived from the given domain, from specific to general. In most cases, the domain is an Emacs window. In that case specifications are searched for as follows:

1. A specification whose locale is the window itself;
2. A specification whose locale is the window’s buffer;
3. A specification whose locale is the window’s frame;
4. A specification whose locale is the window’s frame’s device;
5. A specification whose locale is the symbol global.

If all of those fail, then the C-code-provided fallback value for this specifier is consulted (see specifier-fallback). If it is an inst-list, then this function attempts to instantiate that list just as when a specification is located in the first five steps above. If the fallback is a specifier, specifier-instance is called recursively on this specifier and the return value used. Note, however, that if the optional argument no-fallback is non-nil, the fallback value will not be consulted.

Note that there may be more than one specification matching a particular locale; all such specifications are considered before looking for any specifications for more general locales. Any particular specification that is found may be rejected because it is tagged to a particular device class (e.g. color) or device type (e.g. x) or both and the device for the given domain does not match this, or because the specification is not valid for the device of the given domain (e.g. the font or color name does not exist for this particular X server).

The returned value is dependent on the type of specifier. For example, for a font specifier (as returned by the face-font function), the returned value will be a font-instance object. For images, the returned value will be a string, pixmap, or subwindow.

Function: specifier-matching-instance specifier matchspec &optional domain default no-fallback

This function returns an instance for specifier in domain that matches matchspec. If no instance can be generated for domain, return default. See section Specifier Compatibility Notes.

This function is identical to specifier-instance except that a specification will only be considered if it matches matchspec. The definition of “match,” and allowed values for matchspec, are dependent on the particular type of specifier. Here are some examples:

• For chartable (e.g. display table) specifiers, matchspec should be a character, and the specification (a chartable) must give a value for that character in order to be considered. This allows you to specify, e.g., a buffer-local display table that only gives values for particular characters. All other characters are handled as if the buffer-local display table is not there. (Chartable specifiers are not yet implemented.)
• For font specifiers, matchspec should be a list (charset . stage). On X11 the specification (a font string) should, for clarity, have a registry that matches the charset’s registry, but the redisplay code will specify the XLFD CHARSET_REGISTRY and CHARSET_ENCODING fields itself. This makes minimal sense without Mule support. stage can be one of the symbols 'initial and 'final; on X11, 'initial means “search for fonts using the charset registry of this charset” and 'final means “search for fonts using ‘iso10646-1’ as their charset registries, with the expectation that characters will be translated to Unicode at redisplay.” Their meanings are similar on MS Windows, with the difference that the actual repertoire of the font is checked when deciding if a matchspec with 'final matches.

  For example, the following code emulates what redisplay does when deciding what font to use for ethiopic with the default face (ignoring, for the moment, fallbacks):

  (or (specifier-matching-instance (face-font 'default) (cons 'ethiopic 'initial)) (specifier-matching-instance (face-font 'default) (cons 'ethiopic 'final)))

Function: specifier-instance-from-inst-list specifier domain inst-list &optional default

This function attempts to convert a particular inst-list into an instance. This attempts to instantiate inst-list in the given domain, as if inst-list existed in a specification in specifier. If the instantiation fails, default is returned. In most circumstances, you should not use this function; use specifier-instance instead.

48.10 Examples of Specifier Usage

Now let us present an example to clarify the theoretical discussions we have been through. In this example, we will use the general specifier functions for clarity. Keep in mind that many types of specifiers, and some other types of objects that are associated with specifiers (e.g. faces), provide convenience functions making it easier to work with objects of that type.

Let us consider the background color of the default face. A specifier is used to specify how that color will appear in different domains. First, let’s retrieve the specifier:

(setq sp (face-property 'default 'background))
    ⇒   #<color-specifier 0x3da>

(specifier-specs sp)
    ⇒   ((#<buffer "device.c"> (nil . "forest green"))
                 (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
                 (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
                                           (nil . "moccasin"))
                 (#<x-frame "VM" 0x4ac> (nil . "magenta"))
                 (global ((tty) . "cyan") (nil . "white"))
                )

Then, say we want to determine what the background color of the default face is for the window currently displaying the buffer ‘*scratch*’. We call

(get-buffer-window "*scratch*")
    ⇒ #<window on "*scratch*" 0x4ad>
(window-frame (get-buffer-window "*scratch*"))
    ⇒ #<x-frame "emacs" 0x4ac>
(specifier-instance sp (get-buffer-window "*scratch*"))
    ⇒ #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>

Note that we passed a window to specifier-instance, not a buffer. We cannot pass a buffer because a buffer by itself does not provide enough information. The buffer might not be displayed anywhere at all, or could be displayed in many different frames on different devices.

The result is arrived at like this:

1. First, we look for a specification matching the buffer displayed in the window, i.e. ‘*scratch*’. There are none, so we proceed.
2. Then, we look for a specification matching the window itself. Again, there are none.
3. Then, we look for a specification matching the window’s frame. The specification (#<x-frame "emacs" 0x4ac> . "puke orange") is found. We call the instantiation method for colors, passing it the locale we were searching over (i.e. the window, in this case) and the instantiator (‘"puke orange"’). However, the particular device which this window is on (let’s say it’s an X connection) doesn’t recognize the color ‘"puke orange"’, so the specification is rejected.
4. So we continue looking for a specification matching the window’s frame. We find ‘(#<x-frame "emacs" 0x4ac> . "moccasin")’. Again, we call the instantiation method for colors. This time, the X server our window is on recognizes the color ‘moccasin’, and so the instantiation method succeeds and returns a color instance.

Here’s another example, which implements something like GNU Emacs’s “frame-local” variables.

;; Implementation

;; There are probably better ways to write this macro
;; Heaven help you if VAR is a buffer-local; you will become very
;; confused.  Probably should error on that.
(defmacro define-frame-local-variable (var)
  "Make the unbound symbol VAR become a frame-local variable."
  (let ((val (if (boundp var) (symbol-value var) nil)))
    `(progn
      (setq ,var (make-specifier 'generic))
      (add-spec-to-specifier ,var ',val 'global))))

;; I'm not real happy about this terminology, how can `setq' be a defun?
;; But `frame-set' would have people writing "(frame-set 'foo value)".
(defun frame-setq (var value &optional frame)
  "Set the local value of VAR to VALUE in FRAME.

FRAME defaults to the selected frame."
  (and frame (not (framep frame))
       (error 'invalid-argument "FRAME must be a frame", frame))
  (add-spec-to-specifier var value (or frame (selected-frame))))

(defun frame-value (var &optional frame)
  "Get the local value of VAR in FRAME.

FRAME defaults to the selected frame."
  (and frame (not (framep frame))
       (error 'invalid-argument "FRAME must be a frame", frame))
  ;; this is not just a map from frames to values; it also falls back
  ;; to the global value
  (specifier-instance var (or frame (selected-frame))))

;; for completeness
(defun frame-set-default (var value)
  "Set the default value of frame-local variable VAR to VALUE."
  (add-spec-to-specifier var value 'global))

(defun frame-get-default (var)
  "Get the default value of frame-local variable VAR."
  (car (specifier-specs var 'global)))

Now you can execute the above definitions (eg, with eval-last-sexp) and switch to ‘*scratch*’ to play. Things will work differently if you already have a variable named foo.

;; Usage

foo
error--> Symbol's value as variable is void: foo

(define-frame-local-variable foo)
⇒ nil

;; the value of foo is a specifier, which is an opaque object;
;; you must use accessor functions to get values

foo
⇒ #<generic-specifier global=(nil) 0x4f5cb>

;; since no frame-local value is set, the global value (which is the
;; constant `nil') is returned
(frame-value foo)
⇒ nil

;; get the default explicitly
(frame-get-default foo)
⇒ nil

;; get the whole specification list
(specifier-specs foo 'global)
⇒ (nil)

;; give foo a frame-local value

(frame-setq foo 'bar)
⇒ nil

;; access foo in several ways

;; Note that the print function for this kind of specifier only
;; gives you the global setting.  To get the full list of specs for
;; debugging or study purposes, you must use specifier-specs or
;; specifier-spec-list.
foo
⇒ #<generic-specifier global=(nil) 0x4f5cb>

;; get the whole specification list
(specifier-specs foo)
⇒ ((#<x-frame "Message" 0x1bd66> (nil . bar)) (global (nil)))

;; get the frame-local value
(frame-value foo)
⇒ bar

;; get the default explicitly
(frame-get-default foo)
⇒ nil

;; Switch to another frame and evaluate:
;; C-x 5 o M-: (frame-setq foo 'baz) RET M-: (frame-value foo) RET
⇒ baz

;; Switch back.
;; C-x 5 o
(specifier-specs foo)
⇒ ((#<x-frame "emacs" 0x28ec> (nil . baz))
    (#<x-frame "Message" 0x1bd66> (nil . bar))
    (global (nil)))

(frame-value foo)
⇒ bar

(frame-get-default foo)
⇒ nil

Note that since specifiers generalize both frame-local and buffer-local variables in a sensible way, XEmacs is not likely to put a high priority on implementing frame-local variables Specifier Compatibility Notes.

48.11 Creating New Specifier Objects

Function: make-specifier type

This function creates a new specifier.

A specifier is an object that can be used to keep track of a property whose value can be per-buffer, per-window, per-frame, or per-device, and can further be restricted to a particular device-type or device-class. Specifiers are used, for example, for the various built-in properties of a face; this allows a face to have different values in different frames, buffers, etc. For more information, see specifier-instance, specifier-specs, and add-spec-to-specifier; or, for a detailed description of specifiers, including how they are instantiated over a particular domain (i.e. how their value in that domain is determined), see the chapter on specifiers in the XEmacs Lisp Reference Manual.

type specifies the particular type of specifier, and should be one of the symbols generic, integer, natnum, boolean, color, font, image, face-boolean, or toolbar.

For more information on particular types of specifiers, see the functions make-generic-specifier, make-integer-specifier, make-natnum-specifier, make-boolean-specifier, make-color-specifier, make-font-specifier, make-image-specifier, make-face-boolean-specifier, and make-toolbar-specifier.

Function: make-specifier-and-init type spec-list &optional dont-canonicalize

This function creates and initializes a new specifier.

This is a convenience API combining make-specifier and set-specifier that allows you to create a specifier and add specs to it at the same time. type specifies the specifier type. Allowed types are as for make-specifier.

spec-list supplies the specification(s) to be added to the specifier. Any abbreviation of the full spec-list form accepted by canonicalize-spec-list may be used. However, if the optional argument dont-canonicalize is non-nil, canonicalization is not performed, and the spec-list must already be in full form.

Function: make-integer-specifier spec-list

Return a new integer specifier object with the given specification list. spec-list can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators.

Valid instantiators for integer specifiers are integers.

Function: make-boolean-specifier spec-list

Return a new boolean specifier object with the given specification list. spec-list can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators.

Valid instantiators for boolean specifiers are t and nil.

Function: make-natnum-specifier spec-list

Return a new natnum specifier object with the given specification list. spec-list can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators.

Valid instantiators for natnum specifiers are non-negative integers.

Function: make-generic-specifier spec-list

Return a new generic specifier object with the given specification list. spec-list can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators.

Valid instantiators for generic specifiers are all Lisp values. They are returned back unchanged when a specifier is instantiated.

Function: make-display-table-specifier spec-list

Return a new display-table specifier object with the given spec list. spec-list can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators.

Valid instantiators for display-table specifiers are described in detail in the doc string for current-display-table (see section Active Display Table).

48.12 Functions for Checking the Validity of Specifier Components

Function: valid-specifier-domain-p domain

This function returns non-nil if domain is a valid specifier domain. A domain is used to instantiate a specifier (i.e. determine the specifier’s value in that domain). Valid domains are a window, frame, or device. (nil is not valid.)

Function: valid-specifier-locale-p locale

This function returns non-nil if locale is a valid specifier locale. Valid locales are a device, a frame, a window, a buffer, and global. (nil is not valid.)

Function: valid-specifier-locale-type-p locale-type

Given a specifier locale-type, this function returns non-nil if it is valid. Valid locale types are the symbols global, device, frame, window, and buffer. (Note, however, that in functions that accept either a locale or a locale type, global is considered an individual locale.)

Function: valid-specifier-type-p specifier-type

Given a specifier-type, this function returns non-nil if it is valid. Valid types are generic, integer, boolean, color, font, image, face-boolean, and toolbar.

Function: valid-specifier-tag-p tag

This function returns non-nil if tag is a valid specifier tag.

Function: valid-instantiator-p instantiator specifier-type

This function returns non-nil if instantiator is valid for specifier-type.

Function: valid-inst-list-p inst-list type

This function returns non-nil if inst-list is valid for specifier type type.

Function: valid-spec-list-p spec-list type

This function returns non-nil if spec-list is valid for specifier type type.

Function: check-valid-instantiator instantiator specifier-type

This function signals an error if instantiator is invalid for specifier-type.

Function: check-valid-inst-list inst-list type

This function signals an error if inst-list is invalid for specifier type type.

Function: check-valid-spec-list spec-list type

This function signals an error if spec-list is invalid for specifier type type.

48.13 Other Functions for Working with Specifications in a Specifier

Function: copy-specifier specifier &optional dest locale tag-set exact-p how-to-add

This function copies specifier to dest, or creates a new one if dest is nil.

If dest is nil or omitted, a new specifier will be created and the specifications copied into it. Otherwise, the specifications will be copied into the existing specifier in dest.

If locale is nil or the symbol all, all specifications will be copied. If locale is a particular locale, the specification for that particular locale will be copied. If locale is a locale type, the specifications for all locales of that type will be copied. locale can also be a list of locales, locale types, and/or all; this is equivalent to calling copy-specifier for each of the elements of the list. See specifier-spec-list for more information about locale.

Only instantiators where tag-set (a list of zero or more tags) is a subset of (or possibly equal to) the instantiator’s tag set are copied. (The default value of nil is a subset of all tag sets, so in this case no instantiators will be screened out.) If exact-p is non-nil, however, tag-set must be equal to an instantiator’s tag set for the instantiator to be copied.

Optional argument how-to-add specifies what to do with existing specifications in dest. If nil, then whichever locales or locale types are copied will first be completely erased in dest. Otherwise, it is the same as in add-spec-to-specifier.

Function: remove-specifier specifier &optional locale tag-set exact-p

This function removes specification(s) for specifier.

If locale is a particular locale (a buffer, window, frame, device, or the symbol global), the specification for that locale will be removed.

If instead, locale is a locale type (i.e. a symbol buffer, window, frame, or device), the specifications for all locales of that type will be removed.

If locale is nil or the symbol all, all specifications will be removed.

locale can also be a list of locales, locale types, and/or all; this is equivalent to calling remove-specifier for each of the elements in the list.

Only instantiators where tag-set (a list of zero or more tags) is a subset of (or possibly equal to) the instantiator’s tag set are removed. (The default value of nil is a subset of all tag sets, so in this case no instantiators will be screened out.) If exact-p is non-nil, however, tag-set must be equal to an instantiator’s tag set for the instantiator to be removed.

Function: map-specifier specifier func &optional locale maparg

This function applies func to the specification(s) for locale in specifier.

If optional locale is a locale, func will be called for that locale. If locale is a locale type, func will be mapped over all locales of that type. If locale is nil or the symbol all, func will be mapped over all locales in specifier.

Optional ms-tag-set and ms-exact-p are as in specifier-spec-list'. Optional ms-maparg will be passed to ms-func.

func is called with four arguments: the specifier, the locale being mapped over, the inst-list for that locale, and the optional maparg. If any invocation of func returns non-nil, the mapping will stop and the returned value becomes the value returned from map-specifier. Otherwise, map-specifier returns nil.

Function: specifier-locale-type-from-locale locale

Given a specifier locale, this function returns its type.

48.14 Specifier Compatibility Notes

This node describes compatibility issues in the use of specifiers known as of 2004-01-22. The main text refers to XEmacs 21.5.16.

Effort will be made to describe changes in the API or semantics between XEmacs versions accurately. Any inaccuracy or missing information about backward and forward compatibility is a bug, and we greatly appreciate your reports, whether you can provide a patch or not.

A change is reported as changed when we believe that the new or changed API will cause old code to malfunction. When old code is believed to be upward compatible with the changed API, the change is reported as added.

We would like to also describe compatibility with GNU Emacs, but this is not so high a priority. Inaccuracies or omissions will be addressed at the priority of a feature request, and as such processing will be greatly expedited if you can provide a patch.

48.14.1 Compatibility with GNU Emacs

Specifiers are not used in GNU Emacs. If your program depends on specifers, you will probably have to rewrite the functionality completely for GNU Emacs. If you wish to maximize portability, you should plan to encapsulate use of specifiers.

GNU Emacs provides two features for context-sensitive variables, buffer-local variables and frame-local variables. XEmacs implements buffer-local variables 100%-compatibly with GNU Emacs. If buffer-local variables will server your purpose and portability is a major concern, consider using them instead of specifiers.

XEmacs does not implement frame-local variables at all. In this case specifiers must be used to provide equivalent functionality.

It is not clear whether XEmacs will provide this feature in the future. In fact, some core XEmacs developers think that both frame-local variables and buffer-local variables are evil, because the declaration is both global and invisible. That is, you cannot tell whether a variable is “normal,” buffer-local, or frame-local just by looking at it. So if you have namespace management problems, and some other Lisp package happens to use a variable name that you already declared frame- or buffer-local, weird stuff happens, and it is extremely hard to track down.

Added by 21.5.16: new convenience APIs: instance-to-instantiator, device-type-matches-spec, add-tag-to-inst-list, derive-domain-from-locale, derive-device-type-from-tag-set, derive-device-type-from-locale-and-tag-set, and derive-specifier-specs-from-locale.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.