-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Parsing Expressions, Next: Standard Syntax Tables, Prev: Motion and Syntax, Up: Syntax Tables
+
+Parsing Balanced Expressions
+============================
+
+ Here are several functions for parsing and scanning balanced
+expressions, also known as "sexps", in which parentheses match in
+pairs. The syntax table controls the interpretation of characters, so
+these functions can be used for Lisp expressions when in Lisp mode and
+for C expressions when in C mode. *Note List Motion::, for convenient
+higher-level functions for moving over balanced expressions.
+
+ - Function: parse-partial-sexp start limit &optional target-depth
+ stop-before state stop-comment buffer
+ This function parses a sexp in the current buffer starting at
+ START, not scanning past LIMIT. It stops at position LIMIT or
+ when certain criteria described below are met, and sets point to
+ the location where parsing stops. It returns a value describing
+ the status of the parse at the point where it stops.
+
+ If STATE is `nil', START is assumed to be at the top level of
+ parenthesis structure, such as the beginning of a function
+ definition. Alternatively, you might wish to resume parsing in the
+ middle of the structure. To do this, you must provide a STATE
+ argument that describes the initial status of parsing.
+
+ If the third argument TARGET-DEPTH is non-`nil', parsing stops if
+ the depth in parentheses becomes equal to TARGET-DEPTH. The depth
+ starts at 0, or at whatever is given in STATE.
+
+ If the fourth argument STOP-BEFORE is non-`nil', parsing stops
+ when it comes to any character that starts a sexp. If
+ STOP-COMMENT is non-`nil', parsing stops when it comes to the
+ start of a comment.
+
+ The fifth argument STATE is an eight-element list of the same form
+ as the value of this function, described below. The return value
+ of one call may be used to initialize the state of the parse on
+ another call to `parse-partial-sexp'.
+
+ The result is a list of eight elements describing the final state
+ of the parse:
+
+ 0. The depth in parentheses, counting from 0.
+
+ 1. The character position of the start of the innermost
+ parenthetical grouping containing the stopping point; `nil'
+ if none.
+
+ 2. The character position of the start of the last complete
+ subexpression terminated; `nil' if none.
+
+ 3. Non-`nil' if inside a string. More precisely, this is the
+ character that will terminate the string.
+
+ 4. `t' if inside a comment (of either style).
+
+ 5. `t' if point is just after a quote character.
+
+ 6. The minimum parenthesis depth encountered during this scan.
+
+ 7. `t' if inside a comment of style "b".
+
+ Elements 0, 3, 4, 5 and 7 are significant in the argument STATE.
+
+ This function is most often used to compute indentation for
+ languages that have nested parentheses.
+
+ - Function: scan-lists from count depth &optional buffer noerror
+ This function scans forward COUNT balanced parenthetical groupings
+ from character number FROM. It returns the character position
+ where the scan stops.
+
+ If DEPTH is nonzero, parenthesis depth counting begins from that
+ value. The only candidates for stopping are places where the
+ depth in parentheses becomes zero; `scan-lists' counts COUNT such
+ places and then stops. Thus, a positive value for DEPTH means go
+ out DEPTH levels of parenthesis.
+
+ Scanning ignores comments if `parse-sexp-ignore-comments' is
+ non-`nil'.
+
+ If the scan reaches the beginning or end of the buffer (or its
+ accessible portion), and the depth is not zero, an error is
+ signaled. If the depth is zero but the count is not used up,
+ `nil' is returned.
+
+ If optional arg BUFFER is non-`nil', scanning occurs in that
+ buffer instead of in the current buffer.
+
+ If optional arg NOERROR is non-`nil', `scan-lists' will return
+ `nil' instead of signalling an error.
+
+ - Function: scan-sexps from count &optional buffer noerror
+ This function scans forward COUNT sexps from character position
+ FROM. It returns the character position where the scan stops.
+
+ Scanning ignores comments if `parse-sexp-ignore-comments' is
+ non-`nil'.
+
+ If the scan reaches the beginning or end of (the accessible part
+ of) the buffer in the middle of a parenthetical grouping, an error
+ is signaled. If it reaches the beginning or end between groupings
+ but before count is used up, `nil' is returned.
+
+ If optional arg BUFFER is non-`nil', scanning occurs in that
+ buffer instead of in the current buffer.
+
+ If optional arg NOERROR is non-`nil', `scan-sexps' will return nil
+ instead of signalling an error.
+
+ - Variable: parse-sexp-ignore-comments
+ If the value is non-`nil', then comments are treated as whitespace
+ by the functions in this section and by `forward-sexp'.
+
+ In older Emacs versions, this feature worked only when the comment
+ terminator is something like `*/', and appears only to end a
+ comment. In languages where newlines terminate comments, it was
+ necessary make this variable `nil', since not every newline is the
+ end of a comment. This limitation no longer exists.
+
+ You can use `forward-comment' to move forward or backward over one
+comment or several comments.
+
+ - Function: forward-comment count &optional buffer
+ This function moves point forward across COUNT comments (backward,
+ if COUNT is negative). If it finds anything other than a comment
+ or whitespace, it stops, leaving point at the place where it
+ stopped. It also stops after satisfying COUNT.
+
+ Optional argument BUFFER defaults to the current buffer.
+
+ To move forward over all comments and whitespace following point, use
+`(forward-comment (buffer-size))'. `(buffer-size)' is a good argument
+to use, because the number of comments in the buffer cannot exceed that
+many.
+
+\1f
+File: lispref.info, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables
+
+Some Standard Syntax Tables
+===========================
+
+ Most of the major modes in XEmacs have their own syntax tables. Here
+are several of them:
+
+ - Function: standard-syntax-table
+ This function returns the standard syntax table, which is the
+ syntax table used in Fundamental mode.
+
+ - Variable: text-mode-syntax-table
+ The value of this variable is the syntax table used in Text mode.
+
+ - Variable: c-mode-syntax-table
+ The value of this variable is the syntax table for C-mode buffers.
+
+ - Variable: emacs-lisp-mode-syntax-table
+ The value of this variable is the syntax table used in Emacs Lisp
+ mode by editing commands. (It has no effect on the Lisp `read'
+ function.)
+
+\1f
+File: lispref.info, Node: Syntax Table Internals, Prev: Standard Syntax Tables, Up: Syntax Tables
+
+Syntax Table Internals
+======================
+
+ Each element of a syntax table is an integer that encodes the syntax
+of one character: the syntax class, possible matching character, and
+flags. Lisp programs don't usually work with the elements directly; the
+Lisp-level syntax table functions usually work with syntax descriptors
+(*note Syntax Descriptors::).
+
+ The low 8 bits of each element of a syntax table indicate the syntax
+class.
+
+Integer
+ Class
+
+0
+ whitespace
+
+1
+ punctuation
+
+2
+ word
+
+3
+ symbol
+
+4
+ open parenthesis
+
+5
+ close parenthesis
+
+6
+ expression prefix
+
+7
+ string quote
+
+8
+ paired delimiter
+
+9
+ escape
+
+10
+ character quote
+
+11
+ comment-start
+
+12
+ comment-end
+
+13
+ inherit
+
+ The next 8 bits are the matching opposite parenthesis (if the
+character has parenthesis syntax); otherwise, they are not meaningful.
+The next 6 bits are the flags.
+
+\1f
+File: lispref.info, Node: Abbrevs, Next: Extents, Prev: Syntax Tables, Up: Top
+
+Abbrevs And Abbrev Expansion
+****************************
+
+ An abbreviation or "abbrev" is a string of characters that may be
+expanded to a longer string. The user can insert the abbrev string and
+find it replaced automatically with the expansion of the abbrev. This
+saves typing.
+
+ The set of abbrevs currently in effect is recorded in an "abbrev
+table". Each buffer has a local abbrev table, but normally all buffers
+in the same major mode share one abbrev table. There is also a global
+abbrev table. Normally both are used.
+
+ An abbrev table is represented as an obarray containing a symbol for
+each abbreviation. The symbol's name is the abbreviation; its value is
+the expansion; its function definition is the hook function to do the
+expansion (*note Defining Abbrevs::); its property list cell contains
+the use count, the number of times the abbreviation has been expanded.
+Because these symbols are not interned in the usual obarray, they will
+never appear as the result of reading a Lisp expression; in fact,
+normally they are never used except by the code that handles abbrevs.
+Therefore, it is safe to use them in an extremely nonstandard way.
+*Note Creating Symbols::.
+
+ For the user-level commands for abbrevs, see *Note Abbrev Mode:
+(emacs)Abbrevs.
+
+* Menu:
+
+* Abbrev Mode:: Setting up XEmacs for abbreviation.
+* Tables: Abbrev Tables. Creating and working with abbrev tables.
+* Defining Abbrevs:: Specifying abbreviations and their expansions.
+* Files: Abbrev Files. Saving abbrevs in files.
+* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
+* Standard Abbrev Tables:: Abbrev tables used by various major modes.
+
+\1f
+File: lispref.info, Node: Abbrev Mode, Next: Abbrev Tables, Up: Abbrevs
+
+Setting Up Abbrev Mode
+======================
+
+ Abbrev mode is a minor mode controlled by the value of the variable
+`abbrev-mode'.
+
+ - Variable: abbrev-mode
+ A non-`nil' value of this variable turns on the automatic expansion
+ of abbrevs when their abbreviations are inserted into a buffer.
+ If the value is `nil', abbrevs may be defined, but they are not
+ expanded automatically.
+
+ This variable automatically becomes local when set in any fashion.
+
+ - Variable: default-abbrev-mode
+ This is the value of `abbrev-mode' for buffers that do not
+ override it. This is the same as `(default-value 'abbrev-mode)'.
+
+\1f
+File: lispref.info, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs
+
+Abbrev Tables
+=============
+
+ This section describes how to create and manipulate abbrev tables.
+
+ - Function: make-abbrev-table
+ This function creates and returns a new, empty abbrev table--an
+ obarray containing no symbols. It is a vector filled with zeros.
+
+ - Function: clear-abbrev-table table
+ This function undefines all the abbrevs in abbrev table TABLE,
+ leaving it empty. The function returns `nil'.
+
+ - Function: define-abbrev-table tabname definitions
+ This function defines TABNAME (a symbol) as an abbrev table name,
+ i.e., as a variable whose value is an abbrev table. It defines
+ abbrevs in the table according to DEFINITIONS, a list of elements
+ of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'. The value is
+ always `nil'.
+
+ - Variable: abbrev-table-name-list
+ This is a list of symbols whose values are abbrev tables.
+ `define-abbrev-table' adds the new abbrev table name to this list.
+
+ - Function: insert-abbrev-table-description name &optional human
+ This function inserts before point a description of the abbrev
+ table named NAME. The argument NAME is a symbol whose value is an
+ abbrev table. The value is always `nil'.
+
+ If HUMAN is non-`nil', the description is human-oriented.
+ Otherwise the description is a Lisp expression--a call to
+ `define-abbrev-table' that would define NAME exactly as it is
+ currently defined.
+
+\1f
+File: lispref.info, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs
+
+Defining Abbrevs
+================
+
+ These functions define an abbrev in a specified abbrev table.
+`define-abbrev' is the low-level basic function, while `add-abbrev' is
+used by commands that ask for information from the user.
+
+ - Function: add-abbrev table type arg
+ This function adds an abbreviation to abbrev table TABLE based on
+ information from the user. The argument TYPE is a string
+ describing in English the kind of abbrev this will be (typically,
+ `"global"' or `"mode-specific"'); this is used in prompting the
+ user. The argument ARG is the number of words in the expansion.
+
+ The return value is the symbol that internally represents the new
+ abbrev, or `nil' if the user declines to confirm redefining an
+ existing abbrev.
+
+ - Function: define-abbrev table name expansion hook
+ This function defines an abbrev in TABLE named NAME, to expand to
+ EXPANSION, and call HOOK. The return value is an uninterned
+ symbol that represents the abbrev inside XEmacs; its name is NAME.
+
+ The argument NAME should be a string. The argument EXPANSION
+ should be a string, or `nil' to undefine the abbrev.
+
+ The argument HOOK is a function or `nil'. If HOOK is non-`nil',
+ then it is called with no arguments after the abbrev is replaced
+ with EXPANSION; point is located at the end of EXPANSION when HOOK
+ is called.
+
+ The use count of the abbrev is initialized to zero.
+
+ - User Option: only-global-abbrevs
+ If this variable is non-`nil', it means that the user plans to use
+ global abbrevs only. This tells the commands that define
+ mode-specific abbrevs to define global ones instead. This
+ variable does not alter the behavior of the functions in this
+ section; it is examined by their callers.
+
+\1f
+File: lispref.info, Node: Abbrev Files, Next: Abbrev Expansion, Prev: Defining Abbrevs, Up: Abbrevs
+
+Saving Abbrevs in Files
+=======================
+
+ A file of saved abbrev definitions is actually a file of Lisp code.
+The abbrevs are saved in the form of a Lisp program to define the same
+abbrev tables with the same contents. Therefore, you can load the file
+with `load' (*note How Programs Do Loading::). However, the function
+`quietly-read-abbrev-file' is provided as a more convenient interface.
+
+ User-level facilities such as `save-some-buffers' can save abbrevs
+in a file automatically, under the control of variables described here.
+
+ - User Option: abbrev-file-name
+ This is the default file name for reading and saving abbrevs.
+
+ - Function: quietly-read-abbrev-file filename
+ This function reads abbrev definitions from a file named FILENAME,
+ previously written with `write-abbrev-file'. If FILENAME is
+ `nil', the file specified in `abbrev-file-name' is used.
+ `save-abbrevs' is set to `t' so that changes will be saved.
+
+ This function does not display any messages. It returns `nil'.
+
+ - User Option: save-abbrevs
+ A non-`nil' value for `save-abbrev' means that XEmacs should save
+ abbrevs when files are saved. `abbrev-file-name' specifies the
+ file to save the abbrevs in.
+
+ - Variable: abbrevs-changed
+ This variable is set non-`nil' by defining or altering any
+ abbrevs. This serves as a flag for various XEmacs commands to
+ offer to save your abbrevs.
+
+ - Command: write-abbrev-file filename
+ Save all abbrev definitions, in all abbrev tables, in the file
+ FILENAME, in the form of a Lisp program that when loaded will
+ define the same abbrevs. This function returns `nil'.
+
+\1f
+File: lispref.info, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs
+
+Looking Up and Expanding Abbreviations
+======================================
+
+ Abbrevs are usually expanded by commands for interactive use,
+including `self-insert-command'. This section describes the
+subroutines used in writing such functions, as well as the variables
+they use for communication.
+
+ - Function: abbrev-symbol abbrev &optional table
+ This function returns the symbol representing the abbrev named
+ ABBREV. The value returned is `nil' if that abbrev is not
+ defined. The optional second argument TABLE is the abbrev table
+ to look it up in. If TABLE is `nil', this function tries first
+ the current buffer's local abbrev table, and second the global
+ abbrev table.
+
+ - Function: abbrev-expansion abbrev &optional table
+ This function returns the string that ABBREV would expand into (as
+ defined by the abbrev tables used for the current buffer). The
+ optional argument TABLE specifies the abbrev table to use, as in
+ `abbrev-symbol'.
+
+ - Command: expand-abbrev
+ This command expands the abbrev before point, if any. If point
+ does not follow an abbrev, this command does nothing. The command
+ returns `t' if it did expansion, `nil' otherwise.
+
+ - Command: abbrev-prefix-mark &optional arg
+ Mark current point as the beginning of an abbrev. The next call to
+ `expand-abbrev' will use the text from here to point (where it is
+ then) as the abbrev to expand, rather than using the previous word
+ as usual.
+
+ - User Option: abbrev-all-caps
+ When this is set non-`nil', an abbrev entered entirely in upper
+ case is expanded using all upper case. Otherwise, an abbrev
+ entered entirely in upper case is expanded by capitalizing each
+ word of the expansion.
+
+ - Variable: abbrev-start-location
+ This is the buffer position for `expand-abbrev' to use as the start
+ of the next abbrev to be expanded. (`nil' means use the word
+ before point instead.) `abbrev-start-location' is set to `nil'
+ each time `expand-abbrev' is called. This variable is also set by
+ `abbrev-prefix-mark'.
+
+ - Variable: abbrev-start-location-buffer
+ The value of this variable is the buffer for which
+ `abbrev-start-location' has been set. Trying to expand an abbrev
+ in any other buffer clears `abbrev-start-location'. This variable
+ is set by `abbrev-prefix-mark'.
+
+ - Variable: last-abbrev
+ This is the `abbrev-symbol' of the last abbrev expanded. This
+ information is left by `expand-abbrev' for the sake of the
+ `unexpand-abbrev' command.
+
+ - Variable: last-abbrev-location
+ This is the location of the last abbrev expanded. This contains
+ information left by `expand-abbrev' for the sake of the
+ `unexpand-abbrev' command.
+
+ - Variable: last-abbrev-text
+ This is the exact expansion text of the last abbrev expanded,
+ after case conversion (if any). Its value is `nil' if the abbrev
+ has already been unexpanded. This contains information left by
+ `expand-abbrev' for the sake of the `unexpand-abbrev' command.
+
+ - Variable: pre-abbrev-expand-hook
+ This is a normal hook whose functions are executed, in sequence,
+ just before any expansion of an abbrev. *Note Hooks::. Since it
+ is a normal hook, the hook functions receive no arguments.
+ However, they can find the abbrev to be expanded by looking in the
+ buffer before point.
+
+ The following sample code shows a simple use of
+`pre-abbrev-expand-hook'. If the user terminates an abbrev with a
+punctuation character, the hook function asks for confirmation. Thus,
+this hook allows the user to decide whether to expand the abbrev, and
+aborts expansion if it is not confirmed.
+
+ (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
+
+ ;; This is the function invoked by `pre-abbrev-expand-hook'.
+
+ ;; If the user terminated the abbrev with a space, the function does
+ ;; nothing (that is, it returns so that the abbrev can expand). If the
+ ;; user entered some other character, this function asks whether
+ ;; expansion should continue.
+
+ ;; If the user answers the prompt with `y', the function returns
+ ;; `nil' (because of the `not' function), but that is
+ ;; acceptable; the return value has no effect on expansion.
+
+ (defun query-if-not-space ()
+ (if (/= ?\ (preceding-char))
+ (if (not (y-or-n-p "Do you want to expand this abbrev? "))
+ (error "Not expanding this abbrev"))))
+
+\1f
+File: lispref.info, Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbrevs
+
+Standard Abbrev Tables
+======================
+
+ Here we list the variables that hold the abbrev tables for the
+preloaded major modes of XEmacs.
+
+ - Variable: global-abbrev-table
+ This is the abbrev table for mode-independent abbrevs. The abbrevs
+ defined in it apply to all buffers. Each buffer may also have a
+ local abbrev table, whose abbrev definitions take precedence over
+ those in the global table.
+
+ - Variable: local-abbrev-table
+ The value of this buffer-local variable is the (mode-specific)
+ abbreviation table of the current buffer.
+
+ - Variable: fundamental-mode-abbrev-table
+ This is the local abbrev table used in Fundamental mode; in other
+ words, it is the local abbrev table in all buffers in Fundamental
+ mode.
+
+ - Variable: text-mode-abbrev-table
+ This is the local abbrev table used in Text mode.
+
+ - Variable: c-mode-abbrev-table
+ This is the local abbrev table used in C mode.
+
+ - Variable: lisp-mode-abbrev-table
+ This is the local abbrev table used in Lisp mode and Emacs Lisp
+ mode.
+
+\1f
File: lispref.info, Node: Extents, Next: Specifiers, Prev: Abbrevs, Up: Top
Extents
other. XEmacs efficiently handles buffers with large numbers of
extents in them.
- - Function: extentp OBJECT
+ - Function: extentp object
This returns `t' if OBJECT is an extent.
* Menu:
are invisible to functions that merely examine the text of a buffer or
string.
- *Please note:* An alternative way to add properties to a buffer or
+ _Please note:_ An alternative way to add properties to a buffer or
string is to use text properties. *Note Text Properties::.
An extent is logically a Lisp object consisting of a start position,
information, *Note Annotations::.
If an extent has its `detachable' property set, it will become
-"detached" (i.e. no longer in the buffer) when all its text its
-deleted. Otherwise, it will simply shrink down to zero-length and sit
-it the same place in the buffer. By default, the `detachable' property
-is set on newly-created extents. *Note Detached Extents::.
+"detached" (i.e. no longer in the buffer) when all its text is deleted.
+Otherwise, it will simply shrink down to zero-length and sit in the
+same place in the buffer. By default, the `detachable' property is set
+on newly-created extents. *Note Detached Extents::.
If an extent has its `duplicable' property set, it will be
remembered when a string is created from text bounded by the extent.
Creating and Modifying Extents
==============================
- - Function: make-extent FROM TO &optional OBJECT
+ - Function: make-extent from to &optional object
This function makes an extent for the range [FROM, TO) in OBJECT
(a buffer or string). OBJECT defaults to the current buffer.
Insertions at point TO will be outside of the extent; insertions
at FROM will be inside the extent, causing the extent to grow
- (*note Extent Endpoints::.). This is the same way that markers
+ (*note Extent Endpoints::). This is the same way that markers
behave. The extent is initially detached if both FROM and TO are
`nil', and in this case OBJECT defaults to `nil', meaning the
- extent is in no buffer or string (*note Detached Extents::.).
+ extent is in no buffer or string (*note Detached Extents::).
- - Function: delete-extent EXTENT
+ - Function: delete-extent extent
This function removes EXTENT from its buffer and destroys it.
This does not modify the buffer's text, only its display
properties. The extent cannot be used thereafter. To remove an
extent in such a way that it can be re-inserted later, use
`detach-extent'. *Note Detached Extents::.
- - Function: extent-object EXTENT
+ - Function: extent-object extent
This function returns the buffer or string that EXTENT is in. If
the return value is `nil', this means that the extent is detached;
however, a detached extent will not necessarily return a value of
`nil'.
- - Function: extent-live-p EXTENT
+ - Function: extent-live-p extent
This function returns `nil' if EXTENT is deleted, and `t'
otherwise.
Both endpoints can be equal, in which case the extent includes no
characters but still exists in the buffer or string. Zero-length
-extents are used to represent annotations (*note Annotations::.) and can
+extents are used to represent annotations (*note Annotations::) and can
be used as a more powerful form of a marker. Deletion of all the
characters in an extent may or may not result in a zero-length extent;
-this depends on the `detachable' property (*note Detached Extents::.).
+this depends on the `detachable' property (*note Detached Extents::).
Insertion at the position of a zero-length extent expands the extent if
both endpoints are closed; goes before the extent if it has the
`start-open' property; and goes after the extent if it has the
position, and then by decreasing end position (this is called the
"display order").
- - Function: extent-start-position EXTENT
+ - Function: extent-start-position extent
This function returns the start position of EXTENT.
- - Function: extent-end-position EXTENT
+ - Function: extent-end-position extent
This function returns the end position of EXTENT.
- - Function: extent-length EXTENT
+ - Function: extent-length extent
This function returns the length of EXTENT in characters. If the
extent is detached, this returns `0'. If the extent is not
detached, this is equivalent to
(- (extent-end-position EXTENT) (extent-start-position EXTENT))
- - Function: set-extent-endpoints EXTENT START END &optional
- BUFFER-OR-STRING
+ - Function: set-extent-endpoints extent start end &optional
+ buffer-or-string
This function sets the start and end position of EXTENT to START
and END. If both are `nil', this is equivalent to `detach-extent'.
The following functions provide a simple way of determining the
extents in a buffer or string. A number of more sophisticated
primitives for mapping over the extents in a range of a buffer or string
-are also provided (*note Mapping Over Extents::.). When reading through
+are also provided (*note Mapping Over Extents::). When reading through
this section, keep in mind the way that extents are ordered (*note
-Extent Endpoints::.).
+Extent Endpoints::).
- - Function: extent-list &optional BUFFER-OR-STRING FROM TO FLAGS
+ - Function: extent-list &optional buffer-or-string from to flags
This function returns a list of the extents in BUFFER-OR-STRING.
BUFFER-OR-STRING defaults to the current buffer if omitted. FROM
and TO can be used to limit the range over which extents are
extents by setting a particular property on them. The following
function makes it easier to locate those extents.
- - Function: extent-at POS &optional OBJECT PROPERTY BEFORE AT-FLAG
+ - Function: extent-at pos &optional object property before at-flag
This function finds the "smallest" extent (i.e., the last one in
the display order) at (i.e., overlapping) POS in OBJECT (a buffer
or string) having PROPERTY set. OBJECT defaults to the current
The following low-level functions are provided for explicitly
traversing the extents in a buffer according to the display order.
-These functions are mostly intended for debugging - in normal
-operation, you should probably use `mapcar-extents' or `map-extents',
-or loop using the BEFORE argument to `extent-at', rather than creating
-a loop using `next-extent'.
+These functions are mostly intended for debugging--in normal operation,
+you should probably use `mapcar-extents' or `map-extents', or loop
+using the BEFORE argument to `extent-at', rather than creating a loop
+using `next-extent'.
- - Function: next-extent EXTENT
+ - Function: next-extent extent
Given an extent EXTENT, this function returns the next extent in
the buffer or string's display order. If EXTENT is a buffer or
string, this returns the first extent in the buffer or string.
- - Function: previous-extent EXTENT
+ - Function: previous-extent extent
Given an extent EXTENT, this function returns the previous extent
in the buffer or string's display order. If EXTENT is a buffer or
string, this returns the last extent in the buffer or string.
function to familiarize yourself with the concepts and optional
arguments involved. However, in practice you may find it more
convenient to use the function `mapcar-extents' or to create a loop
-using the `before' argument to `extent-at' (*note Finding Extents::.).
+using the `before' argument to `extent-at' (*note Finding Extents::).
- - Function: map-extents FUNCTION &optional OBJECT FROM TO MAPARG FLAGS
- PROPERTY VALUE
+ - Function: map-extents function &optional object from to maparg flags
+ property value
This function maps FUNCTION over the extents which overlap a
region in OBJECT. OBJECT is normally a buffer or string but could
be an extent (see below). The region is normally bounded by
region.
`negate-in-region'
- The condition specified by a `*-in-region' flag must *not*
+ The condition specified by a `*-in-region' flag must _not_
hold for the extent to be considered.
At most one of `all-extents-closed', `all-extents-open',
If you want to map over extents and accumulate a list of results,
the following function may be more convenient than `map-extents'.
- - Function: mapcar-extents FUNCTION &optional PREDICATE
- BUFFER-OR-STRING FROM TO FLAGS PROPERTY VALUE
+ - Function: mapcar-extents function &optional predicate
+ buffer-or-string from to flags property value
This function applies FUNCTION to all extents which overlap a
region in BUFFER-OR-STRING. The region is delimited by FROM and
TO. FUNCTION is called with one argument, the extent. A list of
VALUE may also be used to control the extents passed to PREDICATE
or FUNCTION, and have the same meaning as in `map-extents'.
- - Function: map-extent-children FUNCTION &optional OBJECT FROM TO
- MAPARG FLAGS PROPERTY VALUE
+ - Function: map-extent-children function &optional object from to
+ maparg flags property value
This function is similar to `map-extents', but differs in that:
* It only visits extents which start in the given region.
(defun walk-extents (buffer &optional ignore)
(map-extent-children 'walk-extents buffer))
- - Function: extent-in-region-p EXTENT &optional FROM TO FLAGS
+ - Function: extent-in-region-p extent &optional from to flags
This function returns T if `map-extents' would visit EXTENT if
called with the given arguments.
-\1f
-File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents
-
-Properties of Extents
-=====================
-
- Each extent has a property list associating property names with
-values. Some property names have predefined meanings, and can usually
-only assume particular values. Assigning other values to such a
-property either cause the value to be converted into a legal value
-(e.g., assigning anything but `nil' to a Boolean property will cause
-the value of `t' to be assigned to the property) or will cause an
-error. Property names without predefined meanings can be assigned any
-value. An undefined property is equivalent to a property with a value
-of `nil', or with a particular default value in the case of properties
-with predefined meanings. Note that, when an extent is created, the
-`end-open' and `detachable' properties are set on it.
-
- If an extent has a parent, all of its properties actually derive
-from that parent (or from the root ancestor if the parent in turn has a
-parent), and setting a property of the extent actually sets that
-property on the parent. *Note Extent Parents::.
-
- - Function: extent-property EXTENT PROPERTY
- This function returns the value of PROPERTY in EXTENT. If
- PROPERTY is undefined, `nil' is returned.
-
- - Function: extent-properties EXTENT
- This function returns a list of all of EXTENT's properties that do
- not have the value of `nil' (or the default value, for properties
- with predefined meanings).
-
- - Function: set-extent-property EXTENT PROPERTY VALUE
- This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a
- predefined meaning, only certain values are allowed, and some
- values may be converted to others before being stored.)
-
- - Function: set-extent-properties EXTENT PLIST
- Change some properties of EXTENT. PLIST is a property list. This
- is useful to change many extent properties at once.
-
- The following table lists the properties with predefined meanings,
-along with their allowable values.
-
-`detached'
- (Boolean) Whether the extent is detached. Setting this is the
- same as calling `detach-extent'. *Note Detached Extents::.
-
-`destroyed'
- (Boolean) Whether the extent has been deleted. Setting this is
- the same as calling `delete-extent'.
-
-`priority'
- (integer) The extent's redisplay priority. Defaults to 0. *Note
- priority: Intro to Extents. This property can also be set with
- `set-extent-priority' and accessed with `extent-priority'.
-
-`start-open'
- (Boolean) Whether the start position of the extent is open,
- meaning that characters inserted at that position go outside of
- the extent. *Note Extent Endpoints::.
-
-`start-closed'
- (Boolean) Same as `start-open' but with the opposite sense.
- Setting this property clears `start-open' and vice-versa.
-
-`end-open'
- (Boolean) Whether the end position of the extent is open, meaning
- that characters inserted at that position go outside of the
- extent. This is `t' by default. *Note Extent Endpoints::.
-
-`end-closed'
- (Boolean) Same as `end-open' but with the opposite sense. Setting
- this property clears `end-open' and vice-versa.
-
-`read-only'
- (Boolean) Whether text within this extent will be unmodifiable.
-
-`face'
- (face, face name, list of faces or face names, or `nil') The face
- in which to display the extent's text. This property can also be
- set with `set-extent-face' and accessed with `extent-face'. Note
- that if a list of faces is specified, the faces are merged
- together, with faces earlier in the list having priority over
- faces later in the list.
-
-`mouse-face'
- (face, face name, list of faces or face names, or `nil') The face
- used to display the extent when the mouse moves over it. This
- property can also be set with `set-extent-mouse-face' and accessed
- with `extent-mouse-face'. Note that if a list of faces is
- specified, the faces are merged together, with faces earlier in
- the list having priority over faces later in the list. *Note
- Extents and Events::.
-
-`pointer'
- (pointer glyph) The glyph used as the pointer when the mouse
- moves over the extent. This takes precedence over the
- `text-pointer-glyph' and `nontext-pointer-glyph' variables. If
- for any reason this glyph is an invalid pointer, the standard
- glyphs will be used as fallbacks. *Note Mouse Pointer::.
-
-`detachable'
- (Boolean) Whether this extent becomes detached when all of the
- text it covers is deleted. This is `t' by default. *Note
- Detached Extents::.
-
-`duplicable'
- (Boolean) Whether this extent should be copied into strings, so
- that kill, yank, and undo commands will restore or copy it. *Note
- Duplicable Extents::.
-
-`unique'
- (Boolean) Meaningful only in conjunction with `duplicable'. When
- this is set, there may be only one instance of this extent
- attached at a time. *Note Duplicable Extents::.
-
-`invisible'
- (Boolean) If `t', text under this extent will not be displayed -
- it will look as if the text is not there at all.
-
-`keymap'
- (keymap or `nil') This keymap is consulted for mouse clicks on this
- extent or keypresses made while `point' is within the extent.
- *Note Extents and Events::.
-
-`copy-function'
- This is a hook that is run when a duplicable extent is about to be
- copied from a buffer to a string (or the kill ring). *Note
- Duplicable Extents::.
-
-`paste-function'
- This is a hook that is run when a duplicable extent is about to be
- copied from a string (or the kill ring) into a buffer. *Note
- Duplicable Extents::.
-
-`begin-glyph'
- (glyph or `nil') This extent's begin glyph. *Note Annotations::.
-
-`end-glyph'
- (glyph or `nil') This extent's end glyph. *Note Annotations::.
-
-`begin-glyph-layout'
- (`text', `whitespace', `inside-margin', or `outside-margin') The
- layout policy for this extent's begin glyph. Defaults to `text'.
- *Note Annotations::.
-
-`end-glyph-layout'
- (`text', `whitespace', `inside-margin', or `outside-margin') The
- layout policy for this extent's end glyph. Defaults to `text'.
- *Note Annotations::.
-
-`initial-redisplay-function'
- (any funcallable object) The function to be called the first time
- (a part of) the extent is redisplayed. It will be called with the
- extent as its argument.
-
- This is used by `lazy-shot' to implement lazy font-locking. The
- functionality is still experimental, and may change without further
- notice.
-
- The following convenience functions are provided for accessing
-particular properties of an extent.
-
- - Function: extent-face EXTENT
- This function returns the `face' property of EXTENT. This might
- also return a list of face names. Do not modify this list
- directly! Instead, use `set-extent-face'.
-
- Note that you can use `eq' to compare lists of faces as returned
- by `extent-face'. In other words, if you set the face of two
- different extents to two lists that are `equal' but not `eq', then
- the return value of `extent-face' on the two extents will return
- the identical list.
-
- - Function: extent-mouse-face EXTENT
- This function returns the `mouse-face' property of EXTENT. This
- might also return a list of face names. Do not modify this list
- directly! Instead, use `set-extent-mouse-face'.
-
- Note that you can use `eq' to compare lists of faces as returned
- by `extent-mouse-face', just like for `extent-face'.
-
- - Function: extent-priority EXTENT
- This function returns the `priority' property of EXTENT.
-
- - Function: extent-keymap EXTENT
- This function returns the `keymap' property of EXTENT.
-
- - Function: extent-begin-glyph-layout EXTENT
- This function returns the `begin-glyph-layout' property of EXTENT,
- i.e. the layout policy associated with the EXTENT's begin glyph.
-
- - Function: extent-end-glyph-layout EXTENT
- This function returns the `end-glyph-layout' property of EXTENT,
- i.e. the layout policy associated with the EXTENT's end glyph.
-
- - Function: extent-begin-glyph EXTENT
- This function returns the `begin-glyph' property of EXTENT, i.e.
- the glyph object displayed at the beginning of EXTENT. If there
- is none, `nil' is returned.
-
- - Function: extent-end-glyph EXTENT
- This function returns the `end-glyph' property of EXTENT, i.e. the
- glyph object displayed at the end of EXTENT. If there is none,
- `nil' is returned.
-
- The following convenience functions are provided for setting
-particular properties of an extent.
-
- - Function: set-extent-priority EXTENT PRI
- This function sets the `priority' property of EXTENT to PRI.
-
- - Function: set-extent-face EXTENT FACE
- This function sets the `face' property of EXTENT to FACE.
-
- - Function: set-extent-mouse-face EXTENT FACE
- This function sets the `mouse-face' property of EXTENT to FACE.
-
- - Function: set-extent-keymap EXTENT KEYMAP
- This function sets the `keymap' property of EXTENT to KEYMAP.
- KEYMAP must be either a keymap object, or `nil'.
-
- - Function: set-extent-begin-glyph-layout EXTENT LAYOUT
- This function sets the `begin-glyph-layout' property of EXTENT to
- LAYOUT.
-
- - Function: set-extent-end-glyph-layout EXTENT LAYOUT
- This function sets the `end-glyph-layout' property of EXTENT to
- LAYOUT.
-
- - Function: set-extent-begin-glyph EXTENT BEGIN-GLYPH &optional LAYOUT
- This function sets the `begin-glyph' and `glyph-layout' properties
- of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT
- defaults to `text' if not specified.)
-
- - Function: set-extent-end-glyph EXTENT END-GLYPH &optional LAYOUT
- This function sets the `end-glyph' and `glyph-layout' properties
- of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults
- to `text' if not specified.)
-
- - Function: set-extent-initial-redisplay-function EXTENT FUNCTION
- This function sets the `initial-redisplay-function' property of the
- extent to FUNCTION.
-
-\1f
-File: lispref.info, Node: Detached Extents, Next: Extent Parents, Prev: Extent Properties, Up: Extents
-
-Detached Extents
-================
-
- A detached extent is an extent that is not attached to a buffer or
-string but can be re-inserted. Detached extents have a start position
-and end position of `nil'. Extents can be explicitly detached using
-`detach-extent'. An extent is also detached when all of its characters
-are all killed by a deletion, if its `detachable' property is set; if
-this property is not set, the extent becomes a zero-length extent.
-(Zero-length extents with the `detachable' property set behave
-specially. *Note zero-length extents: Extent Endpoints.)
-
- - Function: detach-extent EXTENT
- This function detaches EXTENT from its buffer or string. If
- EXTENT has the `duplicable' property, its detachment is tracked by
- the undo mechanism. *Note Duplicable Extents::.
-
- - Function: extent-detached-p EXTENT
- This function returns `nil' if EXTENT is detached, and `t'
- otherwise.
-
- - Function: copy-extent EXTENT &optional OBJECT
- This function makes a copy of EXTENT. It is initially detached.
- Optional argument OBJECT defaults to EXTENT's object (normally a
- buffer or string, but could be `nil').
-
- - Function: insert-extent EXTENT &optional START END NO-HOOKS OBJECT
- This function inserts EXTENT from START to END in OBJECT (a buffer
- or string). If EXTENT is detached from a different buffer or
- string, or in most cases when EXTENT is already attached, the
- extent will first be copied as if with `copy-extent'. This
- function operates the same as if `insert' were called on a string
- whose extent data calls for EXTENT to be inserted, except that if
- NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be
- invoked. *Note Duplicable Extents::.
-
-\1f
-File: lispref.info, Node: Extent Parents, Next: Duplicable Extents, Prev: Detached Extents, Up: Extents
-
-Extent Parents
-==============
-
- An extent can have a parent extent set for it. If this is the case,
-the extent derives all its properties from that extent and has no
-properties of its own. The only "properties" that the extent keeps are
-the buffer or string it refers to and the start and end points. (More
-correctly, the extent's own properties are shadowed. If you later
-change the extent to have no parent, its own properties will become
-visible again.)
-
- It is possible for an extent's parent to itself have a parent, and
-so on. Through this, a whole tree of extents can be created, all
-deriving their properties from one root extent. Note, however, that
-you cannot create an inheritance loop - this is explicitly disallowed.
-
- Parent extents are used to implement the extents over the modeline.
-
- - Function: set-extent-parent EXTENT PARENT
- This function sets the parent of EXTENT to PARENT. If PARENT is
- `nil', the extent is set to have no parent.
-
- - Function: extent-parent EXTENT
- This function return the parents (if any) of EXTENT, or `nil'.
-
- - Function: extent-children EXTENT
- This function returns a list of the children (if any) of EXTENT.
- The children of an extent are all those extents whose parent is
- that extent. This function does not recursively trace children of
- children.
-
- - Function: extent-descendants EXTENT
- This function returns a list of all descendants of EXTENT,
- including EXTENT. This recursively applies `extent-children' to
- any children of EXTENT, until no more children can be found.
-
-\1f
-File: lispref.info, Node: Duplicable Extents, Next: Extents and Events, Prev: Extent Parents, Up: Extents
-
-Duplicable Extents
-==================
-
- If an extent has the `duplicable' property, it will be copied into
-strings, so that kill, yank, and undo commands will restore or copy it.
-
- Specifically:
-
- * When a string is created using `buffer-substring' or
- `buffer-string', any duplicable extents in the region corresponding
- to the string will be copied into the string (*note Buffer
- Contents::.). When the string in inserted into a buffer using
- `insert', `insert-before-markers', `insert-buffer' or
- `insert-buffer-substring', the extents in the string will be copied
- back into the buffer (*note Insertion::.). The extents in a
- string can, of course, be retrieved explicitly using the standard
- extent primitives over the string.
-
- * Similarly, when text is copied or cut into the kill ring, any
- duplicable extents will be remembered and reinserted later when
- the text is pasted back into a buffer.
-
- * When `concat' is called on strings, the extents in the strings are
- copied into the resulting string.
-
- * When `substring' is called on a string, the relevant extents are
- copied into the resulting string.
-
- * When a duplicable extent is detached by `detach-extent' or string
- deletion, or inserted by `insert-extent' or string insertion, the
- action is recorded by the undo mechanism so that it can be undone
- later. Note that if an extent gets detached and then a later undo
- causes the extent to get reinserted, the new extent will not be
- `eq' to the original extent.
-
- * Extent motion, face changes, and attachment via `make-extent' are
- not recorded by the undo mechanism. This means that extent changes
- which are to be undo-able must be performed by character editing,
- or by insertion and detachment of duplicable extents.
-
- * A duplicable extent's `copy-function' property, if non-`nil',
- should be a function, and will be run when a duplicable extent is
- about to be copied from a buffer to a string (or the kill ring).
- It is called with three arguments: the extent and the buffer
- positions within it which are being copied. If this function
- returns `nil', then the extent will not be copied; otherwise it
- will.
-
- * A duplicable extent's `paste-function' property, if non-`nil',
- should be a function, and will be run when a duplicable extent is
- about to be copied from a string (or the kill ring) into a buffer.
- It is called with three arguments: the original extent and the
- buffer positions which the copied extent will occupy. (This hook
- is run after the corresponding text has already been inserted into
- the buffer.) Note that the extent argument may be detached when
- this function is run. If this function returns `nil', no extent
- will be inserted. Otherwise, there will be an extent covering the
- range in question.
-
- Note: if the extent to be copied is already attached to the buffer
- and overlaps the new range, the extent will simply be extended and
- the `paste-function' will not be called.
-
-\1f
-File: lispref.info, Node: Extents and Events, Next: Atomic Extents, Prev: Duplicable Extents, Up: Extents
-
-Interaction of Extents with Keyboard and Mouse Events
-=====================================================
-
- If an extent has the `mouse-face' property set, it will be
-highlighted when the mouse passes over it. Highlighting is accomplished
-by merging the extent's face with the face or faces specified by the
-`mouse-face' property. The effect is as if a pseudo-extent with the
-`mouse-face' face were inserted after the extent in the display order
-(*note Extent Endpoints::., display order).
-
- - Variable: mouse-highlight-priority
- This variable holds the priority to use when merging in the
- highlighting pseudo-extent. The default is 1000. This is
- purposely set very high so that the highlighting pseudo-extent
- shows up even if there are other extents with various priorities
- at the same location.
-
- You can also explicitly cause an extent to be highlighted. Only one
-extent at a time can be highlighted in this fashion, and any other
-highlighted extent will be de-highlighted.
-
- - Function: highlight-extent EXTENT &optional HIGHLIGHT-P
- This function highlights (if HIGHLIGHT-P is non-`nil') or
- de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the
- `mouse-face' property. (Nothing happens if EXTENT does not have
- the `mouse-face' property.)
-
- - Function: force-highlight-extent EXTENT &optional HIGHLIGHT-P
- This function is similar to `highlight-extent' but highlights or
- de-highlights the extent regardless of whether it has the
- `mouse-face' property.
-
- If an extent has a `keymap' property, this keymap will be consulted
-for mouse clicks on the extent and keypresses made while `point' is
-within the extent. The behavior of mouse clicks and keystrokes not
-defined in the keymap is as normal for the buffer.
-
-\1f
-File: lispref.info, Node: Atomic Extents, Prev: Extents and Events, Up: Extents
-
-Atomic Extents
-==============
-
- If the Lisp file `atomic-extents' is loaded, then the atomic extent
-facility is available. An "atomic extent" is an extent for which
-`point' cannot be positioned anywhere within it. This ensures that
-when selecting text, either all or none of the extent is selected.
-
- To make an extent atomic, set its `atomic' property.
-
-\1f
-File: lispref.info, Node: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top
-
-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.
-
-* 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.
-
-\1f
-File: lispref.info, Node: Introduction to Specifiers, Next: Specifiers In-Depth, Up: Specifiers
-
-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
-
-\1f
-File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Introduction to Specifiers, Up: Specifiers
-
-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
-(*note 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.
-
projects / chise / xemacs-chise.git- / blobdiff