(JX1-7437): Unify JC3-4CEF.

[chise/xemacs-chise.git] / man / lispref / specifiers.texi

@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
@c Copyright (C) 1995, 1996 Ben Wing.
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/specifiers.info
@node Specifiers, Faces and Window-System Objects, Extents, top
@chapter Specifiers
@cindex specifier

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
@code{modeline-shadow-thickness} and @code{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.

@defun specifierp object
This function returns non-@code{nil} if @var{object} is a specifier.
@end defun

@menu
* Introduction to Specifiers::  Specifiers provide a clean way for
                                display and other properties to vary
                                (under user control) in a wide variety
                                of contexts.
* Specifiers In-Depth::         Gory details about specifier innards.
* Specifier Instancing::        Instancing means obtaining the ``value'' of
                                a specifier in a particular context.
* Specifier Types::             Specifiers come in different flavors.
* Adding Specifications::       Specifications control a specifier's ``value''
                                by giving conditions under which a
                                particular value is valid.
* Retrieving Specifications::   Querying a specifier's specifications.
* Specifier Tag Functions::     Working with specifier tags.
* Specifier Instancing Functions::
                                Functions to instance a specifier.
* Specifier Example::           Making all this stuff clearer.
* Creating Specifiers::         Creating specifiers for your own use.
* Specifier Validation Functions::
                                Validating the components of a specifier.
* Other Specification Functions::
                                Other ways of working with specifications.
@end menu

@node Introduction to Specifiers
@section 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
@code{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
@code{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 @dfn{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

@itemize @bullet
@item
blue for a particular buffer
@item
green for all other buffers
@end itemize

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

@itemize @bullet
@item
forest green for all buffers displayed in a particular Emacs window, or
green if the X server doesn't recognize the color @samp{forest green}
@item
blue for all buffers displayed in a particular frame
@item
red for all other buffers displayed on a color device
@item
white for all other buffers
@end itemize

@node Specifiers In-Depth
@section In-Depth Overview of a Specifier
@cindex specification (in a specifier)
@cindex domain (in a specifier)
@cindex locale (in a specifier)
@cindex instantiator (in a specifier)
@cindex instancing (in a specifier)
@cindex instance (in a specifier)
@cindex inst-list (in a specifier)
@cindex inst-pair (in a specifier)
@cindex tag (in a specifier)
@cindex tag set (in a specifier)
@cindex specifier, specification
@cindex specifier, domain
@cindex specifier, locale
@cindex specifier, instantiator
@cindex specifier, instancing
@cindex specifier, instance
@cindex specifier, inst-list
@cindex specifier, inst-pair
@cindex specifier, tag
@cindex specifier, tag set

A specifier object encapsulates a set of @dfn{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 @dfn{locales} and the values are called @dfn{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 @dfn{domain}, and
determining its value in a particular domain is called @dfn{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 @dfn{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 @dfn{specifications},
each of which associates a @dfn{locale} (a window object, a buffer
object, a frame object, a device object, or the symbol @code{global})
with an @dfn{inst-list}, which is a list of one or more
@dfn{inst-pairs}. (For each possible locale, there can be at most one
specification containing that locale.) Each inst-pair is a cons of a
@dfn{tag set} (an unordered list of zero or more symbols, or @dfn{tags})
and an @dfn{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
@dfn{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 @code{x}, @code{tty}, and
@code{stream}) and device classes (normally @code{color},
@code{grayscale}, and @code{mono}) can always be used as tags, and match
devices of the associated type or class (@pxref{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 @dfn{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 @dfn{instantiation})
might fail---a font or color might not exist on a particular device,
for example.

@node Specifier Instancing
@section How a Specifier Is Instanced
@cindex fallback (in a specifier)
@cindex specifier, fallback

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

@itemize @bullet
@item
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 @code{global}
(if there is such a specification) is considered.
@item
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.)
@item
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.
@item
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.
@item
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 @dfn{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 @code{default} face.)
@end itemize

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 @code{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 @code{global} locale.  Instancing
over a device domain looks only for device locales and the @code{global}
locale.

@node Specifier Types
@section 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:

@table @code
@item boolean
The valid instantiators are the symbols @code{t} and @code{nil}.
Instance objects are the same as instantiators so no special
instantiation function is needed.

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

@item 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 @code{top-toolbar-height}.

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

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

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

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

@item face-boolean
The valid instantiators are the symbols @code{t} and @code{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 @code{t}
or the symbol @code{nil}.

@item 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).  @xref{Toolbar}, for more information.
@end table

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.

@xref{Faces and Window-System Objects}, for more information on fonts,
colors, and face-boolean specifiers.  @xref{Glyphs}, for more information
about image specifiers.  @xref{Toolbar}, for more information on toolbar
specifiers.

@defun specifier-type specifier
This function returns the type of @var{specifier}.  The returned value
will be a symbol: one of @code{integer}, @code{boolean}, etc., as
listed in the above table.
@end defun

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

@defun boolean-specifier-p object
This function returns non-@code{nil} if @var{object} is a boolean
specifier.
@end defun

@defun integer-specifier-p object
This function returns non-@code{nil} if @var{object} is an integer
specifier.
@end defun

@defun natnum-specifier-p object
This function returns non-@code{nil} if @var{object} is a natnum
specifier.
@end defun

@defun generic-specifier-p object
This function returns non-@code{nil} if @var{object} is a generic
specifier.
@end defun

@defun face-boolean-specifier-p object
This function returns non-@code{nil} if @var{object} is a face-boolean
specifier.
@end defun

@defun toolbar-specifier-p object
This function returns non-@code{nil} if @var{object} is a toolbar
specifier.
@end defun

@defun font-specifier-p object
This function returns non-@code{nil} if @var{object} is a font
specifier.
@end defun

@defun color-specifier-p object
This function returns non-@code{nil} if @var{object} is a color
specifier.
@end defun

@defun image-specifier-p object
This function returns non-@code{nil} if @var{object} is an image
specifier.
@end defun

@node Adding Specifications
@section Adding specifications to a Specifier

@defun add-spec-to-specifier specifier instantiator &optional locale tag-set how-to-add
This function adds a specification to @var{specifier}.  The
specification maps from @var{locale} (which should be a window, buffer,
frame, device, or the symbol @code{global}, and defaults to
@code{global}) to @var{instantiator}, whose allowed values depend on the
type of the specifier.  Optional argument @var{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
@code{define-specifier-tag}).  Specifying a single symbol for
@var{tag-set} is equivalent to specifying a one-element list containing
that symbol.  Optional argument @var{how-to-add} specifies what to do if
there are already specifications in the specifier.  It should be one of

@table @code
@item prepend
Put at the beginning of the current list of instantiators for @var{locale}.
@item append
Add to the end of the current list of instantiators for @var{locale}.
@item remove-tag-set-prepend
This is the default.  Remove any existing instantiators whose tag set is
the same as @var{tag-set}; then put the new instantiator at the
beginning of the current list.
@item remove-tag-set-append
Remove any existing instantiators whose tag set is the same as
@var{tag-set}; then put the new instantiator at the end of the current
list.
@item remove-locale
Remove all previous instantiators for this locale before adding the new
spec.
@item remove-locale-type
Remove all specifications for all locales of the same type as
@var{locale} (this includes @var{locale} itself) before adding the new
spec.
@item remove-all
Remove all specifications from the specifier before adding the new spec.
@end table

@code{remove-tag-set-prepend} is the default.

You can retrieve the specifications for a particular locale or locale type
with the function @code{specifier-spec-list} or @code{specifier-specs}.
@end defun

@defun add-spec-list-to-specifier specifier spec-list &optional how-to-add
This function adds a @dfn{spec-list} (a list of specifications) to
@var{specifier}.  The format of a spec-list is

@example
  @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}
@end example

where

@itemize @bullet
@item
@var{locale} := a window, a buffer, a frame, a device, or @code{global}
@item
@var{tag-set} := an unordered list of zero or more @var{tags}, each of
which is a symbol
@item
@var{tag} := a device class (@pxref{Consoles and Devices}), a device type,
or a tag defined with @code{define-specifier-tag}
@item
@var{instantiator} := format determined by the type of specifier
@end itemize

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

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

In many circumstances, the higher-level function @code{set-specifier} is
more convenient and should be used instead.
@end defun

@defspec let-specifier specifier-list &rest body
This special form temporarily adds specifications to specifiers,
evaluates forms in @var{body} and restores the specifiers to their
previous states.  The specifiers and their temporary specifications are
listed in @var{specifier-list}.

The format of @var{specifier-list} is

@example
((@var{specifier} @var{value} &optional @var{locale} @var{tag-set} @var{how-to-add}) ...)
@end example

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

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

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

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

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

@example
(let-specifier ((modeline-shadow-thickness 0 (selected-window)))
  (sit-for 1))
@end example
@end defspec

@defun set-specifier specifier value &optional locale tag-set how-to-add
This function adds some specifications to @var{specifier}.  @var{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, @var{value} can be anything
accepted by @code{canonicalize-spec-list}.

@var{locale}, @var{tag-set}, and @var{how-to-add} are the same as in
@code{add-spec-to-specifier}.

Note that @code{set-specifier} is exactly complementary to
@code{specifier-specs} except in the case where @var{specifier} has no
specs at all in it but @code{nil} is a valid instantiator (in that case,
@code{specifier-specs} will return @code{nil} (meaning no specs) and
@code{set-specifier} will interpret the @code{nil} as meaning ``I'm
adding a global instantiator and its value is @code{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
@code{specifier-spec-list} and @code{add-spec-list-to-specifier}.  These
functions always work with fully-qualified spec-lists; thus, there is no
ambiguity.
@end defun

@defun canonicalize-inst-pair inst-pair specifier-type &optional noerror
This function canonicalizes the given @var{inst-pair}.

@var{specifier-type} specifies the type of specifier that this
@var{spec-list} will be used for.

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

If @var{noerror} is non-@code{nil}, signal an error if the inst-pair is
invalid; otherwise return @code{t}.
@end defun

@defun canonicalize-inst-list inst-list specifier-type &optional noerror
This function canonicalizes the given @var{inst-list} (a list of
inst-pairs).

@var{specifier-type} specifies the type of specifier that this @var{inst-list}
will be used for.

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

If @var{noerror} is non-@code{nil}, signal an error if the inst-list is
invalid; otherwise return @code{t}.
@end defun

@defun canonicalize-spec spec specifier-type &optional noerror
This function canonicalizes the given @var{spec} (a specification).

@var{specifier-type} specifies the type of specifier that this
@var{spec-list} will be used for.

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

If @var{noerror} is @code{nil}, signal an error if the specification is
invalid; otherwise return @code{t}.
@end defun

@defun canonicalize-spec-list spec-list specifier-type &optional noerror
This function canonicalizes the given @var{spec-list} (a list of
specifications).

@var{specifier-type} specifies the type of specifier that this
@var{spec-list} will be used for.

Canonicalizing means converting to the full form for a spec-list, i.e.
@code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}.
This function accepts a possibly abbreviated specification or a list of
such things. (See @code{canonicalize-spec}.) This is the function used
to convert spec-lists accepted by @code{set-specifier} and such into a
form suitable for @code{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 @var{noerror} is @code{nil}, signal an error if the spec-list is
invalid; otherwise return @code{t}.
@end defun

@node Retrieving Specifications
@section Retrieving the Specifications from a Specifier

@defun specifier-spec-list specifier &optional locale tag-set exact-p
This function returns the spec-list of specifications for
@var{specifier} in @var{locale}.

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

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

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

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

Only instantiators where @var{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 @code{nil} is a subset of all tag sets,
so in this case no instantiators will be screened out.) If @var{exact-p}
is non-@code{nil}, however, @var{tag-set} must be equal to an
instantiator's tag set for the instantiator to be returned.
@end defun

@defun specifier-specs specifier &optional locale tag-set exact-p
This function returns the specification(s) for @var{specifier} in
@var{locale}.

If @var{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 @code{specifier-spec-list}.

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

@enumerate
@item
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.
@item
For each inst-pair returned, if the instantiator's tag is @code{any},
the tag will be removed and the instantiator itself will be returned
instead of the inst-pair.
@item
If there is only one instantiator, its value is @code{nil}, and its tag
is @code{any}, a one-element list containing @code{nil} will be returned
rather than just @code{nil}, to distinguish this case from there being
no instantiators at all.
@end enumerate

@end defun

@defun specifier-fallback specifier
This function returns the fallback value for @var{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 @code{default} inherit
their attributes from @code{default}).  By design, you cannot change the
fallback value, and specifiers created with @code{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 @var{specifier}
(results in inheritance), or @code{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 @code{specifier-instance}.
@end defun

@node Specifier Tag Functions
@section 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 @code{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.

@defun valid-specifier-tag-p tag
This function returns non-@code{nil} if @var{tag} is a valid specifier
tag.
@end defun

@defun valid-specifier-tag-set-p tag-set
This function returns non-@code{nil} if @var{tag-set} is a valid
specifier tag set.
@end defun

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

@defun device-matches-specifier-tag-set-p device tag-set
This function returns non-@code{nil} if @var{device} matches specifier
tag set @var{tag-set}.  This means that @var{device} matches each tag in
the tag set.
@end defun

@defun define-specifier-tag tag &optional predicate
This function defines a new specifier tag.  If @var{predicate} is
specified, it should be a function of one argument (a device) that
specifies whether the tag matches that particular device.  If
@var{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 @code{nil}, @code{t}, @code{all}, or
@code{global}.
@end defun

@defun device-matching-specifier-tag-list &optional device
This function returns a list of all specifier tags matching
@var{device}.  @var{device} defaults to the selected device if omitted.
@end defun

@defun 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).
@end defun

@defun specifier-tag-predicate tag
This function returns the predicate for the given specifier tag.
@end defun

@node Specifier Instancing Functions
@section Functions for Instancing a Specifier

@defun specifier-instance specifier &optional domain default no-fallback
This function instantiates @var{specifier} (return its value) in
@var{domain}.  If no instance can be generated for this domain, return
@var{default}.

@var{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 @code{valid-specifier-domain-p}).  @var{domain} defaults to the
selected window if omitted.

@dfn{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:

@enumerate
@item
A specification whose locale is the window itself;
@item
A specification whose locale is the window's buffer;
@item
A specification whose locale is the window's frame;
@item
A specification whose locale is the window's frame's device;
@item
A specification whose locale is the symbol @code{global}.
@end enumerate

If all of those fail, then the C-code-provided fallback value for this
specifier is consulted (see @code{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, @code{specifier-instance} is called recursively
on this specifier and the return value used.  Note, however, that if the
optional argument @var{no-fallback} is non-@code{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. @code{color}) or device type (e.g. @code{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 @code{face-font} function), the
returned value will be a font-instance object.  For images, the returned
value will be a string, pixmap, or subwindow.
@end defun

@defun 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 @var{inst-list} in the given
@var{domain}, as if @var{inst-list} existed in a specification in
@var{specifier}.  If the instantiation fails, @var{default} is returned.
In most circumstances, you should not use this function; use
@code{specifier-instance} instead.
@end defun

@node Specifier Example
@section 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:

@example
(setq sp (face-property 'default 'background))
    @result{}   #<color-specifier 0x3da>
@end example

@example
(specifier-specs sp)
    @result{}   ((#<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"))
                )
@end example

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

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

Note that we passed a window to @code{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:

@enumerate
@item
First, we look for a specification matching the buffer displayed in the
window, i.e. @samp{*scratch*}.  There are none, so we proceed.
@item
Then, we look for a specification matching the window itself.  Again, there
are none.
@item
Then, we look for a specification matching the window's frame.  The
specification @code{(#<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 (@samp{"puke orange"}).  However, the particular device
which this window is on (let's say it's an X connection) doesn't
recognize the color @samp{"puke orange"}, so the specification is
rejected.
@item
So we continue looking for a specification matching the window's frame.
We find @samp{(#<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 @samp{moccasin}, and so the
instantiation method succeeds and returns a color instance.
@end enumerate

@node Creating Specifiers
@section Creating New Specifier Objects

@defun 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 @code{specifier-instance},
@code{specifier-specs}, and @code{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.

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

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

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

This is a front-end onto @code{make-specifier} that allows you to create
a specifier and add specs to it at the same time.  @var{type} specifies
the specifier type.  @var{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 @var{dont-canonicalize} is non-@code{nil},
this conversion is not performed, and the @var{spec-list} must already
be in full form.  See @code{canonicalize-spec-list}.
@end defun

@defun make-integer-specifier spec-list

Return a new @code{integer} specifier object with the given
specification list.  @var{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.
@end defun

@defun make-boolean-specifier spec-list

Return a new @code{boolean} specifier object with the given
specification list.  @var{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 @code{t} and @code{nil}.
@end defun

@defun make-natnum-specifier spec-list

Return a new @code{natnum} specifier object with the given specification
list.  @var{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.
@end defun

@defun make-generic-specifier spec-list

Return a new @code{generic} specifier object with the given
specification list.  @var{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.
@end defun

@defun make-display-table-specifier spec-list

Return a new @code{display-table} specifier object with the given spec
list.  @var{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 @code{current-display-table} (@pxref{Active
Display Table}).
@end defun

@node Specifier Validation Functions
@section Functions for Checking the Validity of Specifier Components

@defun valid-specifier-domain-p domain
This function returns non-@code{nil} if @var{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.  (@code{nil} is not valid.)
@end defun

@defun valid-specifier-locale-p locale
This function returns non-@code{nil} if @var{locale} is a valid
specifier locale.  Valid locales are a device, a frame, a window, a
buffer, and @code{global}.  (@code{nil} is not valid.)
@end defun

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

@defun valid-specifier-type-p specifier-type
Given a @var{specifier-type}, this function returns non-@code{nil} if it
is valid.  Valid types are @code{generic}, @code{integer},
@code{boolean}, @code{color}, @code{font}, @code{image},
@code{face-boolean}, and @code{toolbar}.
@end defun

@defun valid-specifier-tag-p tag
This function returns non-@code{nil} if @var{tag} is a valid specifier
tag.
@end defun

@defun valid-instantiator-p instantiator specifier-type
This function returns non-@code{nil} if @var{instantiator} is valid for
@var{specifier-type}.
@end defun

@defun valid-inst-list-p inst-list type
This function returns non-@code{nil} if @var{inst-list} is valid for
specifier type @var{type}.
@end defun

@defun valid-spec-list-p spec-list type
This function returns non-@code{nil} if @var{spec-list} is valid for
specifier type @var{type}.
@end defun

@defun check-valid-instantiator instantiator specifier-type
This function signals an error if @var{instantiator} is invalid for
@var{specifier-type}.
@end defun

@defun check-valid-inst-list inst-list type
This function signals an error if @var{inst-list} is invalid for
specifier type @var{type}.
@end defun

@defun check-valid-spec-list spec-list type
This function signals an error if @var{spec-list} is invalid for
specifier type @var{type}.
@end defun

@node Other Specification Functions
@section Other Functions for Working with Specifications in a Specifier

@defun copy-specifier specifier &optional dest locale tag-set exact-p how-to-add
This function copies @var{specifier} to @var{dest}, or creates a new one
if @var{dest} is @code{nil}.

If @var{dest} is @code{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 @var{dest}.

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

Only instantiators where @var{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 @code{nil} is a subset of all tag sets,
so in this case no instantiators will be screened out.) If @var{exact-p}
is non-@code{nil}, however, @var{tag-set} must be equal to an
instantiator's tag set for the instantiator to be copied.

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

@defun remove-specifier specifier &optional locale tag-set exact-p
This function removes specification(s) for @var{specifier}.

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

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

If @var{locale} is @code{nil} or the symbol @code{all}, all
specifications will be removed.

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

Only instantiators where @var{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 @code{nil} is a subset of all tag sets,
so in this case no instantiators will be screened out.) If @var{exact-p}
is non-@code{nil}, however, @var{tag-set} must be equal to an
instantiator's tag set for the instantiator to be removed.
@end defun

@defun map-specifier specifier func &optional locale maparg
This function applies @var{func} to the specification(s) for
@var{locale} in @var{specifier}.

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

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

@defun specifier-locale-type-from-locale locale
Given a specifier @var{locale}, this function returns its type.
@end defun