Specifiers
**********

A specifier is an object used to keep track of a property whose value may vary depending on the particular situation (e.g. particular buffer displayed in a particular window) that it is used in.  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 ``instanced'' in a particular situation to yield the real value of the property in that situation.

 -- Function: specifierp object
     This function returns non-nil if OBJECT is a specifier.

Introduction to Specifiers
==========================

Sometimes you may want the value of a property to vary depending on the context the property is used in.  A simple example of this in XEmacs is 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 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.

A specifier is a generalization of this, allowing a great deal of flexibility in controlling exactly what value a property has in which circumstances.  It is 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

In-Depth Overview of a Specifier
================================

A specifier object encapsulates a set of specifications, each of which says what its value should be if a particular condition applies. 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''.  In specifier terminology, these conditions are called locales and the values are called instantiators. 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 instancing. 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 instances it in the domain given by that window; in other words, it asks the specifier, ``What is your value in this window?''.

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

The valid device types (normally x, tty, and stream) and device classes (normally color, grayscale, and mono) can always be used as tags, and match devices of the associated type or class (see Consoles and Devices). User-defined tags may be defined, with an optional predicate 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 instanced 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 instancing.  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 instancing (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.

How a Specifier Is Instanced
============================

Instancing 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 instancing and the instancing 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 instancing 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 instancing 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 instancing 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 instancing 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 instance a specifier over a frame domain or device domain instead of over a window domain.  The C code, for example, instances the top-toolbar-height variable over a frame domain in order to determine the height of a frame's top toolbar.  Instancing over a frame or device is similar to instancing over a window except that specifications for locales that cannot be derived from the domain are ignored.  Specifically, instancing over a frame looks first for frame locales, then device locales, then the global locale.  Instancing over a device domain looks only for device locales and the global locale.

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 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 Faces and Window-System Objects for more information on fonts, colors, and face-boolean specifiers.  See Glyphs for more information about image specifiers.  See 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.

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.

     In many circumstances, the higher-level function set-specifier is more convenient and should be used instead.

 -- Macro: 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 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.

     HOW-TO-ADD is 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.)

     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.

     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.

     If NOERROR is nil, signal an error if the spec-list is invalid; otherwise return t.

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. a symbol 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 instancing 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 instanced like any other inst-list, a specifier of the same type as SPECIFIER (results in inheritance), or nil for no fallback.

     When you instance 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.

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 of 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 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 predicate, or none (meaning that all devices match). When attempting to instance a specifier, a particular instantiator is only considered if the device of the domain being instanced over matches all tags in the tag set attached to that instantiator.

Most of the time, a tag set is not specified, and the instantiator gets a null tag set, which matches all devices.

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

     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-predicate tag
     This function returns the predicate for the given specifier tag.

Functions for Instancing a Specifier
====================================

 -- Function: specifier-instance specifier &optional domain default no-fallback
     This function instantiates SPECIFIER (return 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-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.

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

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 generic-specifier-p, integer-specifier-p, natnum-specifier-p, boolean-specifier-p, color-specifier-p, font-specifier-p, image-specifier-p, face-boolean-specifier-p, and toolbar-specifier-p.

 -- Function: make-specifier-and-init type spec-list &optional dont-canonicalize
     This function creates and initialize a new specifier.

     This is a front-end onto make-specifier that allows you to create a specifier and add specs to it at the same time.  TYPE specifies the specifier type.  SPEC-LIST supplies the specification(s) to be added to the specifier. Normally, almost any reasonable abbreviation of the full spec-list form is accepted, and is converted to the full form; however, if optional argument DONT-CANONICALIZE is non-nil, this conversion is not performed, and the SPEC-LIST must already be in full form.  See canonicalize-spec-list.

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

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

     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.