1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs
55 Looking Up and Expanding Abbreviations
56 ======================================
58 Abbrevs are usually expanded by commands for interactive use,
59 including `self-insert-command'. This section describes the
60 subroutines used in writing such functions, as well as the variables
61 they use for communication.
63 - Function: abbrev-symbol abbrev &optional table
64 This function returns the symbol representing the abbrev named
65 ABBREV. The value returned is `nil' if that abbrev is not
66 defined. The optional second argument TABLE is the abbrev table
67 to look it up in. If TABLE is `nil', this function tries first
68 the current buffer's local abbrev table, and second the global
71 - Function: abbrev-expansion abbrev &optional table
72 This function returns the string that ABBREV would expand into (as
73 defined by the abbrev tables used for the current buffer). The
74 optional argument TABLE specifies the abbrev table to use, as in
77 - Command: expand-abbrev
78 This command expands the abbrev before point, if any. If point
79 does not follow an abbrev, this command does nothing. The command
80 returns `t' if it did expansion, `nil' otherwise.
82 - Command: abbrev-prefix-mark &optional arg
83 Mark current point as the beginning of an abbrev. The next call to
84 `expand-abbrev' will use the text from here to point (where it is
85 then) as the abbrev to expand, rather than using the previous word
88 - User Option: abbrev-all-caps
89 When this is set non-`nil', an abbrev entered entirely in upper
90 case is expanded using all upper case. Otherwise, an abbrev
91 entered entirely in upper case is expanded by capitalizing each
92 word of the expansion.
94 - Variable: abbrev-start-location
95 This is the buffer position for `expand-abbrev' to use as the start
96 of the next abbrev to be expanded. (`nil' means use the word
97 before point instead.) `abbrev-start-location' is set to `nil'
98 each time `expand-abbrev' is called. This variable is also set by
101 - Variable: abbrev-start-location-buffer
102 The value of this variable is the buffer for which
103 `abbrev-start-location' has been set. Trying to expand an abbrev
104 in any other buffer clears `abbrev-start-location'. This variable
105 is set by `abbrev-prefix-mark'.
107 - Variable: last-abbrev
108 This is the `abbrev-symbol' of the last abbrev expanded. This
109 information is left by `expand-abbrev' for the sake of the
110 `unexpand-abbrev' command.
112 - Variable: last-abbrev-location
113 This is the location of the last abbrev expanded. This contains
114 information left by `expand-abbrev' for the sake of the
115 `unexpand-abbrev' command.
117 - Variable: last-abbrev-text
118 This is the exact expansion text of the last abbrev expanded,
119 after case conversion (if any). Its value is `nil' if the abbrev
120 has already been unexpanded. This contains information left by
121 `expand-abbrev' for the sake of the `unexpand-abbrev' command.
123 - Variable: pre-abbrev-expand-hook
124 This is a normal hook whose functions are executed, in sequence,
125 just before any expansion of an abbrev. *Note Hooks::. Since it
126 is a normal hook, the hook functions receive no arguments.
127 However, they can find the abbrev to be expanded by looking in the
130 The following sample code shows a simple use of
131 `pre-abbrev-expand-hook'. If the user terminates an abbrev with a
132 punctuation character, the hook function asks for confirmation. Thus,
133 this hook allows the user to decide whether to expand the abbrev, and
134 aborts expansion if it is not confirmed.
136 (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
138 ;; This is the function invoked by `pre-abbrev-expand-hook'.
140 ;; If the user terminated the abbrev with a space, the function does
141 ;; nothing (that is, it returns so that the abbrev can expand). If the
142 ;; user entered some other character, this function asks whether
143 ;; expansion should continue.
145 ;; If the user answers the prompt with `y', the function returns
146 ;; `nil' (because of the `not' function), but that is
147 ;; acceptable; the return value has no effect on expansion.
149 (defun query-if-not-space ()
150 (if (/= ?\ (preceding-char))
151 (if (not (y-or-n-p "Do you want to expand this abbrev? "))
152 (error "Not expanding this abbrev"))))
155 File: lispref.info, Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbrevs
157 Standard Abbrev Tables
158 ======================
160 Here we list the variables that hold the abbrev tables for the
161 preloaded major modes of XEmacs.
163 - Variable: global-abbrev-table
164 This is the abbrev table for mode-independent abbrevs. The abbrevs
165 defined in it apply to all buffers. Each buffer may also have a
166 local abbrev table, whose abbrev definitions take precedence over
167 those in the global table.
169 - Variable: local-abbrev-table
170 The value of this buffer-local variable is the (mode-specific)
171 abbreviation table of the current buffer.
173 - Variable: fundamental-mode-abbrev-table
174 This is the local abbrev table used in Fundamental mode; in other
175 words, it is the local abbrev table in all buffers in Fundamental
178 - Variable: text-mode-abbrev-table
179 This is the local abbrev table used in Text mode.
181 - Variable: c-mode-abbrev-table
182 This is the local abbrev table used in C mode.
184 - Variable: lisp-mode-abbrev-table
185 This is the local abbrev table used in Lisp mode and Emacs Lisp
189 File: lispref.info, Node: Extents, Next: Specifiers, Prev: Abbrevs, Up: Top
194 An "extent" is a region of text (a start position and an end
195 position) that is displayed in a particular face and can have certain
196 other properties such as being read-only. Extents can overlap each
197 other. XEmacs efficiently handles buffers with large numbers of
200 - Function: extentp object
201 This returns `t' if OBJECT is an extent.
205 * Intro to Extents:: Extents are regions over a buffer or string.
206 * Creating and Modifying Extents::
207 Basic extent functions.
208 * Extent Endpoints:: Accessing and setting the bounds of an extent.
209 * Finding Extents:: Determining which extents are in an object.
210 * Mapping Over Extents:: More sophisticated functions for extent scanning.
211 * Extent Properties:: Extents have built-in and user-definable properties.
212 * Detached Extents:: Extents that are not in a buffer.
213 * Extent Parents:: Inheriting properties from another extent.
214 * Duplicable Extents:: Extents can be marked to be copied into strings.
215 * Extents and Events:: Extents can interact with the keyboard and mouse.
216 * Atomic Extents:: Treating a block of text as a single entity.
219 File: lispref.info, Node: Intro to Extents, Next: Creating and Modifying Extents, Up: Extents
221 Introduction to Extents
222 =======================
224 An extent is a region of text within a buffer or string that has
225 certain properties associated with it. The properties of an extent
226 primarily affect the way the text contained in the extent is displayed.
227 Extents can freely overlap each other in a buffer or string. Extents
228 are invisible to functions that merely examine the text of a buffer or
231 _Please note:_ An alternative way to add properties to a buffer or
232 string is to use text properties. *Note Text Properties::.
234 An extent is logically a Lisp object consisting of a start position,
235 an end position, a buffer or string to which these positions refer, and
236 a property list. As text is inserted into a buffer, the start and end
237 positions of the extent are automatically adjusted as necessary to keep
238 the extent referring to the same text in the buffer. If text is
239 inserted at the boundary of an extent, the extent's `start-open' and
240 `end-open' properties control whether the text is included as part of
241 the extent. If the text bounded by an extent is deleted, the extent
242 becomes "detached"; its start and end positions are no longer
243 meaningful, but it maintains all its other properties and can later be
244 reinserted into a buffer. (None of these considerations apply to
245 strings, because text cannot be inserted into or deleted from a string.)
247 Each extent has a face or list of faces associated with it, which
248 controls the way in which the text bounded by the extent is displayed.
249 If an extent's face is `nil' or its properties are partially undefined,
250 the corresponding properties from the default face for the frame is
251 used. If two or more extents overlap, or if a list of more than one
252 face is specified for a particular extent, the corresponding faces are
253 merged to determine the text's displayed properties. Every extent has
254 a "priority" that determines which face takes precedence if the faces
255 conflict. (If two extents have the same priority, the one that comes
256 later in the display order takes precedence. *Note display order:
257 Extent Endpoints.) Higher-numbered priority values correspond to a
258 higher priority, and priority values can be negative. Every extent is
259 created with a priority of 0, but this can be changed with
260 `set-extent-priority'. Within a single extent with a list of faces,
261 faces earlier in the list have a higher priority than faces later in
264 Extents can be set to respond specially to key and mouse events
265 within the extent. An extent's `keymap' property controls the effect of
266 key and mouse strokes within the extent's text, and the `mouse-face'
267 property controls whether the extent is highlighted when the mouse moves
268 over it. *Note Extents and Events::.
270 An extent can optionally have a "begin-glyph" or "end-glyph"
271 associated with it. A begin-glyph or end-glyph is a pixmap or string
272 that will be displayed either at the start or end of an extent or in the
273 margin of the line that the start or end of the extent lies in,
274 depending on the extent's layout policy. Begin-glyphs and end-glyphs
275 are used to implement annotations, and you should use the annotation API
276 functions in preference to the lower-level extent functions. For more
277 information, *Note Annotations::.
279 If an extent has its `detachable' property set, it will become
280 "detached" (i.e. no longer in the buffer) when all its text is deleted.
281 Otherwise, it will simply shrink down to zero-length and sit in the
282 same place in the buffer. By default, the `detachable' property is set
283 on newly-created extents. *Note Detached Extents::.
285 If an extent has its `duplicable' property set, it will be
286 remembered when a string is created from text bounded by the extent.
287 When the string is re-inserted into a buffer, the extent will also be
288 re-inserted. This mechanism is used in the kill, yank, and undo
289 commands. *Note Duplicable Extents::.
292 File: lispref.info, Node: Creating and Modifying Extents, Next: Extent Endpoints, Prev: Intro to Extents, Up: Extents
294 Creating and Modifying Extents
295 ==============================
297 - Function: make-extent from to &optional buffer-or-string
298 This function makes an extent for the range [FROM, TO) in
299 BUFFER-OR-STRING (a buffer or string). BUFFER-OR-STRING defaults
300 to the current buffer. Insertions at point TO will be outside of
301 the extent; insertions at FROM will be inside the extent, causing
302 the extent to grow (*note Extent Endpoints::). This is the same
303 way that markers behave. The extent is initially detached if both
304 FROM and TO are `nil', and in this case BUFFER-OR-STRING defaults
305 to `nil', meaning the extent is in no buffer or string (*note
308 - Function: delete-extent extent
309 This function removes EXTENT from its buffer and destroys it.
310 This does not modify the buffer's text, only its display
311 properties. The extent cannot be used thereafter. To remove an
312 extent in such a way that it can be re-inserted later, use
313 `detach-extent'. *Note Detached Extents::.
315 - Function: extent-object extent
316 This function returns the buffer or string that EXTENT is in. If
317 the return value is `nil', this means that the extent is detached;
318 however, a detached extent will not necessarily return a value of
321 - Function: extent-live-p object
322 This function returns `t' if OBJECT is an extent that has not been
323 deleted, and `nil' otherwise.
326 File: lispref.info, Node: Extent Endpoints, Next: Finding Extents, Prev: Creating and Modifying Extents, Up: Extents
331 Every extent has a start position and an end position, and logically
332 affects the characters between those positions. Normally the start and
333 end positions must both be valid positions in the extent's buffer or
334 string. However, both endpoints can be `nil', meaning the extent is
335 detached. *Note Detached Extents::.
337 Whether the extent overlaps its endpoints is governed by its
338 `start-open' and `end-open' properties. Insertion of a character at a
339 closed endpoint will expand the extent to include that character;
340 insertion at an open endpoint will not. Similarly, functions such as
341 `extent-at' that scan over all extents overlapping a particular
342 position will include extents with a closed endpoint at that position,
343 but not extents with an open endpoint.
345 Note that the `start-closed' and `end-closed' properties are
346 equivalent to `start-open' and `end-open' with the opposite sense.
348 Both endpoints can be equal, in which case the extent includes no
349 characters but still exists in the buffer or string. Zero-length
350 extents are used to represent annotations (*note Annotations::) and can
351 be used as a more powerful form of a marker. Deletion of all the
352 characters in an extent may or may not result in a zero-length extent;
353 this depends on the `detachable' property (*note Detached Extents::).
354 Insertion at the position of a zero-length extent expands the extent if
355 both endpoints are closed; goes before the extent if it has the
356 `start-open' property; and goes after the extent if it has the
357 `end-open' property. Zero-length extents with both the `start-open'
358 and `end-open' properties are treated as if their starting point were
359 closed. Deletion of a character on a side of a zero-length extent
360 whose corresponding endpoint is closed causes the extent to be detached
361 if its `detachable' property is set; if the corresponding endpoint is
362 open, the extent remains in the buffer, moving as necessary.
364 Extents are ordered within a buffer or string by increasing start
365 position, and then by decreasing end position (this is called the
368 - Function: extent-start-position extent
369 This function returns the start position of EXTENT.
371 - Function: extent-end-position extent
372 This function returns the end position of EXTENT.
374 - Function: extent-length extent
375 This function returns the length of EXTENT in characters. If the
376 extent is detached, this returns `0'. If the extent is not
377 detached, this is equivalent to
378 (- (extent-end-position EXTENT) (extent-start-position EXTENT))
380 - Function: set-extent-endpoints extent start end &optional
382 This function sets the start and end position of EXTENT to START
383 and END. If both are `nil', this is equivalent to `detach-extent'.
385 BUFFER-OR-STRING specifies the new buffer or string that the
386 extent should be in, and defaults to EXTENT's buffer or string.
387 (If `nil', and EXTENT is in no buffer and no string, it defaults
388 to the current buffer.)
390 See documentation on `detach-extent' for a discussion of undo
394 File: lispref.info, Node: Finding Extents, Next: Mapping Over Extents, Prev: Extent Endpoints, Up: Extents
399 The following functions provide a simple way of determining the
400 extents in a buffer or string. A number of more sophisticated
401 primitives for mapping over the extents in a range of a buffer or string
402 are also provided (*note Mapping Over Extents::). When reading through
403 this section, keep in mind the way that extents are ordered (*note
406 - Function: extent-list &optional buffer-or-string from to flags
408 This function returns a list of the extents in BUFFER-OR-STRING.
409 BUFFER-OR-STRING defaults to the current buffer if omitted. FROM
410 and TO can be used to limit the range over which extents are
411 returned; if omitted, all extents in the buffer or string are
414 More specifically, if a range is specified using FROM and TO, only
415 extents that overlap the range (i.e. begin or end inside of the
416 range) are included in the list. FROM and TO default to the
417 beginning and end of BUFFER-OR-STRING, respectively.
419 FLAGS controls how end cases are treated. For a discussion of
420 this, and exactly what "overlap" means, see `map-extents'.
422 The optional arguments PROPERTY and VALUE can be used to further
423 restrict which extents are returned. They have the same meaning
424 as for `map-extents'.
426 If you want to map a function over the extents in a buffer or
427 string, consider using `map-extents' or `mapcar-extents' instead.
429 See also the function `extents-at'.
431 Functions that create extents must be prepared for the possibility
432 that there are other extents in the same area, created by other
433 functions. To deal with this, functions typically mark their own
434 extents by setting a particular property on them. The following
435 function makes it easier to locate those extents.
437 - Function: extent-at pos &optional object property before at-flag
438 This function finds the "smallest" extent (i.e., the last one in
439 the display order) at (i.e., overlapping) POS in OBJECT (a buffer
440 or string) having PROPERTY set. OBJECT defaults to the current
441 buffer. PROPERTY defaults to `nil', meaning that any extent will
442 do. Returns `nil' if there is no matching extent at POS. If the
443 fourth argument BEFORE is not `nil', it must be an extent; any
444 returned extent will precede that extent. This feature allows
445 `extent-at' to be used by a loop over extents.
447 AT-FLAG controls how end cases are handled (i.e. what "at" really
448 means), and should be one of:
453 An extent is at POS if it covers the character after POS.
454 This is consistent with the way that text properties work.
457 An extent is at POS if it covers the character before POS.
460 An extent is at POS if it overlaps or abuts POS. This
461 includes all zero-length extents at POS.
463 Note that in all cases, the start-openness and end-openness of the
464 extents considered is ignored. If you want to pay attention to
465 those properties, you should use `map-extents', which gives you
468 The following low-level functions are provided for explicitly
469 traversing the extents in a buffer according to the display order.
470 These functions are mostly intended for debugging--in normal operation,
471 you should probably use `mapcar-extents' or `map-extents', or loop
472 using the BEFORE argument to `extent-at', rather than creating a loop
475 - Function: next-extent extent
476 Given an extent EXTENT, this function returns the next extent in
477 the buffer or string's display order. If EXTENT is a buffer or
478 string, this returns the first extent in the buffer or string.
480 - Function: previous-extent extent
481 Given an extent EXTENT, this function returns the previous extent
482 in the buffer or string's display order. If EXTENT is a buffer or
483 string, this returns the last extent in the buffer or string.
486 File: lispref.info, Node: Mapping Over Extents, Next: Extent Properties, Prev: Finding Extents, Up: Extents
491 The most basic and general function for mapping over extents is
492 called `map-extents'. You should read through the definition of this
493 function to familiarize yourself with the concepts and optional
494 arguments involved. However, in practice you may find it more
495 convenient to use the function `mapcar-extents' or to create a loop
496 using the `before' argument to `extent-at' (*note Finding Extents::).
498 - Function: map-extents function &optional object from to maparg flags
500 This function maps FUNCTION over the extents which overlap a
501 region in OBJECT. OBJECT is normally a buffer or string but could
502 be an extent (see below). The region is normally bounded by
503 [FROM, TO) (i.e. the beginning of the region is closed and the end
504 of the region is open), but this can be changed with the FLAGS
505 argument (see below for a complete discussion).
507 FUNCTION is called with the arguments (extent, MAPARG). The
508 arguments OBJECT, FROM, TO, MAPARG, and FLAGS are all optional and
509 default to the current buffer, the beginning of OBJECT, the end of
510 OBJECT, `nil', and `nil', respectively. `map-extents' returns the
511 first non-`nil' result produced by FUNCTION, and no more calls to
512 FUNCTION are made after it returns non-`nil'.
514 If OBJECT is an extent, FROM and TO default to the extent's
515 endpoints, and the mapping omits that extent and its predecessors.
516 This feature supports restarting a loop based on `map-extents'.
517 Note: OBJECT must be attached to a buffer or string, and the
518 mapping is done over that buffer or string.
520 An extent overlaps the region if there is any point in the extent
521 that is also in the region. (For the purpose of overlap,
522 zero-length extents and regions are treated as closed on both ends
523 regardless of their endpoints' specified open/closedness.) Note
524 that the endpoints of an extent or region are considered to be in
525 that extent or region if and only if the corresponding end is
526 closed. For example, the extent [5,7] overlaps the region [2,5]
527 because 5 is in both the extent and the region. However, (5,7]
528 does not overlap [2,5] because 5 is not in the extent, and neither
529 [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the
532 The optional FLAGS can be a symbol or a list of one or more
533 symbols, modifying the behavior of `map-extents'. Allowed symbols
537 The region's end is closed.
540 The region's start is open.
543 Treat all extents as closed on both ends for the purpose of
544 determining whether they overlap the region, irrespective of
545 their actual open- or closedness.
548 Treat all extents as open on both ends.
550 `all-extents-closed-open'
551 Treat all extents as start-closed, end-open.
553 `all-extents-open-closed'
554 Treat all extents as start-open, end-closed.
557 In addition to the above conditions for extent overlap, the
558 extent's start position must lie within the specified region.
559 Note that, for this condition, open start positions are
560 treated as if 0.5 was added to the endpoint's value, and open
561 end positions are treated as if 0.5 was subtracted from the
565 The extent's end position must lie within the region.
567 `start-and-end-in-region'
568 Both the extent's start and end positions must lie within the
571 `start-or-end-in-region'
572 Either the extent's start or end position must lie within the
576 The condition specified by a `*-in-region' flag must _not_
577 hold for the extent to be considered.
579 At most one of `all-extents-closed', `all-extents-open',
580 `all-extents-closed-open', and `all-extents-open-closed' may be
583 At most one of `start-in-region', `end-in-region',
584 `start-and-end-in-region', and `start-or-end-in-region' may be
587 If optional arg PROPERTY is non-`nil', only extents with that
588 property set on them will be visited. If optional arg VALUE is
589 non-`nil', only extents whose value for that property is `eq' to
590 VALUE will be visited.
592 If you want to map over extents and accumulate a list of results,
593 the following function may be more convenient than `map-extents'.
595 - Function: mapcar-extents function &optional predicate
596 buffer-or-string from to flags property value
597 This function applies FUNCTION to all extents which overlap a
598 region in BUFFER-OR-STRING. The region is delimited by FROM and
599 TO. FUNCTION is called with one argument, the extent. A list of
600 the values returned by FUNCTION is returned. An optional
601 PREDICATE may be used to further limit the extents over which
602 FUNCTION is mapped. The optional arguments FLAGS, PROPERTY, and
603 VALUE may also be used to control the extents passed to PREDICATE
604 or FUNCTION, and have the same meaning as in `map-extents'.
606 - Function: map-extent-children function &optional object from to
607 maparg flags property value
608 This function is similar to `map-extents', but differs in that:
610 * It only visits extents which start in the given region.
612 * After visiting an extent E, it skips all other extents which
613 start inside E but end before E's end.
615 Thus, this function may be used to walk a tree of extents in a
617 (defun walk-extents (buffer &optional ignore)
618 (map-extent-children 'walk-extents buffer))
620 - Function: extent-in-region-p extent &optional from to flags
621 This function returns `t' if `map-extents' would visit EXTENT if
622 called with the given arguments.
625 File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents
627 Properties of Extents
628 =====================
630 Each extent has a property list associating property names with
631 values. Some property names have predefined meanings, and can usually
632 only assume particular values. Assigning other values to such a
633 property either cause the value to be converted into a legal value
634 (e.g., assigning anything but `nil' to a Boolean property will cause
635 the value of `t' to be assigned to the property) or will cause an
636 error. Property names without predefined meanings can be assigned any
637 value. An undefined property is equivalent to a property with a value
638 of `nil', or with a particular default value in the case of properties
639 with predefined meanings. Note that, when an extent is created, the
640 `end-open' and `detachable' properties are set on it.
642 If an extent has a parent, all of its properties actually derive
643 from that parent (or from the root ancestor if the parent in turn has a
644 parent), and setting a property of the extent actually sets that
645 property on the parent. *Note Extent Parents::.
647 - Function: extent-property extent property &optional default
648 This function returns EXTENT's value for PROPERTY, or DEFAULT if
649 no such property exists.
651 - Function: extent-properties extent
652 This function returns a list of all of EXTENT's properties that do
653 not have the value of `nil' (or the default value, for properties
654 with predefined meanings).
656 - Function: set-extent-property extent property value
657 This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a
658 predefined meaning, only certain values are allowed, and some
659 values may be converted to others before being stored.)
661 - Function: set-extent-properties extent plist
662 Change some properties of EXTENT. PLIST is a property list. This
663 is useful to change many extent properties at once.
665 The following table lists the properties with predefined meanings,
666 along with their allowable values.
669 (Boolean) Whether the extent is detached. Setting this is the
670 same as calling `detach-extent'. *Note Detached Extents::.
673 (Boolean) Whether the extent has been deleted. Setting this is
674 the same as calling `delete-extent'.
677 (integer) The extent's redisplay priority. Defaults to 0. *Note
678 priority: Intro to Extents. This property can also be set with
679 `set-extent-priority' and accessed with `extent-priority'.
682 (Boolean) Whether the start position of the extent is open,
683 meaning that characters inserted at that position go outside of
684 the extent. *Note Extent Endpoints::.
687 (Boolean) Same as `start-open' but with the opposite sense.
688 Setting this property clears `start-open' and vice-versa.
691 (Boolean) Whether the end position of the extent is open, meaning
692 that characters inserted at that position go outside of the
693 extent. This is `t' by default. *Note Extent Endpoints::.
696 (Boolean) Same as `end-open' but with the opposite sense. Setting
697 this property clears `end-open' and vice-versa.
700 (Boolean) Whether text within this extent will be unmodifiable.
703 (face, face name, list of faces or face names, or `nil') The face
704 in which to display the extent's text. This property can also be
705 set with `set-extent-face' and accessed with `extent-face'. Note
706 that if a list of faces is specified, the faces are merged
707 together, with faces earlier in the list having priority over
708 faces later in the list.
711 (face, face name, list of faces or face names, or `nil') The face
712 used to display the extent when the mouse moves over it. This
713 property can also be set with `set-extent-mouse-face' and accessed
714 with `extent-mouse-face'. Note that if a list of faces is
715 specified, the faces are merged together, with faces earlier in
716 the list having priority over faces later in the list. *Note
717 Extents and Events::.
720 (pointer glyph) The glyph used as the pointer when the mouse
721 moves over the extent. This takes precedence over the
722 `text-pointer-glyph' and `nontext-pointer-glyph' variables. If
723 for any reason this glyph is an invalid pointer, the standard
724 glyphs will be used as fallbacks. *Note Mouse Pointer::.
727 (Boolean) Whether this extent becomes detached when all of the
728 text it covers is deleted. This is `t' by default. *Note
732 (Boolean) Whether this extent should be copied into strings, so
733 that kill, yank, and undo commands will restore or copy it. *Note
734 Duplicable Extents::.
737 (Boolean) Meaningful only in conjunction with `duplicable'. When
738 this is set, there may be only one instance of this extent
739 attached at a time. *Note Duplicable Extents::.
742 (Boolean) If `t', text under this extent will not be displayed -
743 it will look as if the text is not there at all.
746 (keymap or `nil') This keymap is consulted for mouse clicks on this
747 extent or keypresses made while `point' is within the extent.
748 *Note Extents and Events::.
751 This is a hook that is run when a duplicable extent is about to be
752 copied from a buffer to a string (or the kill ring). *Note
753 Duplicable Extents::.
756 This is a hook that is run when a duplicable extent is about to be
757 copied from a string (or the kill ring) into a buffer. *Note
758 Duplicable Extents::.
761 (glyph or `nil') This extent's begin glyph. *Note Annotations::.
764 (glyph or `nil') This extent's end glyph. *Note Annotations::.
767 (`text', `whitespace', `inside-margin', or `outside-margin') The
768 layout policy for this extent's begin glyph. Defaults to `text'.
772 (`text', `whitespace', `inside-margin', or `outside-margin') The
773 layout policy for this extent's end glyph. Defaults to `text'.
776 `initial-redisplay-function'
777 (any funcallable object) The function to be called the first time
778 (a part of) the extent is redisplayed. It will be called with the
779 extent as its argument.
781 This is used by `lazy-shot' to implement lazy font-locking. The
782 functionality is still experimental, and may change without further
785 The following convenience functions are provided for accessing
786 particular properties of an extent.
788 - Function: extent-face extent
789 This function returns the `face' property of EXTENT. This might
790 also return a list of face names. Do not modify this list
791 directly! Instead, use `set-extent-face'.
793 Note that you can use `eq' to compare lists of faces as returned
794 by `extent-face'. In other words, if you set the face of two
795 different extents to two lists that are `equal' but not `eq', then
796 the return value of `extent-face' on the two extents will return
799 - Function: extent-mouse-face extent
800 This function returns the `mouse-face' property of EXTENT. This
801 might also return a list of face names. Do not modify this list
802 directly! Instead, use `set-extent-mouse-face'.
804 Note that you can use `eq' to compare lists of faces as returned
805 by `extent-mouse-face', just like for `extent-face'.
807 - Function: extent-priority extent
808 This function returns the `priority' property of EXTENT.
810 - Function: extent-keymap extent
811 This function returns the `keymap' property of EXTENT.
813 - Function: extent-begin-glyph-layout extent
814 This function returns the `begin-glyph-layout' property of EXTENT,
815 i.e. the layout policy associated with the EXTENT's begin glyph.
817 - Function: extent-end-glyph-layout extent
818 This function returns the `end-glyph-layout' property of EXTENT,
819 i.e. the layout policy associated with the EXTENT's end glyph.
821 - Function: extent-begin-glyph extent
822 This function returns the `begin-glyph' property of EXTENT, i.e.
823 the glyph object displayed at the beginning of EXTENT. If there
824 is none, `nil' is returned.
826 - Function: extent-end-glyph extent
827 This function returns the `end-glyph' property of EXTENT, i.e. the
828 glyph object displayed at the end of EXTENT. If there is none,
831 The following convenience functions are provided for setting
832 particular properties of an extent.
834 - Function: set-extent-priority extent priority
835 This function sets the `priority' property of EXTENT to PRIORITY.
837 - Function: set-extent-face extent face
838 This function sets the `face' property of EXTENT to FACE.
840 - Function: set-extent-mouse-face extent face
841 This function sets the `mouse-face' property of EXTENT to FACE.
843 - Function: set-extent-keymap extent keymap
844 This function sets the `keymap' property of EXTENT to KEYMAP.
845 KEYMAP must be either a keymap object, or `nil'.
847 - Function: set-extent-begin-glyph-layout extent layout
848 This function sets the `begin-glyph-layout' property of EXTENT to
851 - Function: set-extent-end-glyph-layout extent layout
852 This function sets the `end-glyph-layout' property of EXTENT to
855 - Function: set-extent-begin-glyph extent begin-glyph &optional layout
856 This function sets the `begin-glyph' and `glyph-layout' properties
857 of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT
858 defaults to `text' if not specified.)
860 - Function: set-extent-end-glyph extent end-glyph &optional layout
861 This function sets the `end-glyph' and `glyph-layout' properties
862 of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults
863 to `text' if not specified.)
865 - Function: set-extent-initial-redisplay-function extent function
866 This function sets the `initial-redisplay-function' property of the
870 File: lispref.info, Node: Detached Extents, Next: Extent Parents, Prev: Extent Properties, Up: Extents
875 A detached extent is an extent that is not attached to a buffer or
876 string but can be re-inserted. Detached extents have a start position
877 and end position of `nil'. Extents can be explicitly detached using
878 `detach-extent'. An extent is also detached when all of its characters
879 are all killed by a deletion, if its `detachable' property is set; if
880 this property is not set, the extent becomes a zero-length extent.
881 (Zero-length extents with the `detachable' property set behave
882 specially. *Note zero-length extents: Extent Endpoints.)
884 - Function: detach-extent extent
885 This function detaches EXTENT from its buffer or string. If
886 EXTENT has the `duplicable' property, its detachment is tracked by
887 the undo mechanism. *Note Duplicable Extents::.
889 - Function: extent-detached-p extent
890 This function returns `nil' if EXTENT is detached, and `t'
893 - Function: copy-extent extent &optional object
894 This function makes a copy of EXTENT. It is initially detached.
895 Optional argument OBJECT defaults to EXTENT's object (normally a
896 buffer or string, but could be `nil').
898 - Function: insert-extent extent &optional start end no-hooks object
899 This function inserts EXTENT from START to END in OBJECT (a buffer
900 or string). If EXTENT is detached from a different buffer or
901 string, or in most cases when EXTENT is already attached, the
902 extent will first be copied as if with `copy-extent'. This
903 function operates the same as if `insert' were called on a string
904 whose extent data calls for EXTENT to be inserted, except that if
905 NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be
906 invoked. *Note Duplicable Extents::.
909 File: lispref.info, Node: Extent Parents, Next: Duplicable Extents, Prev: Detached Extents, Up: Extents
914 An extent can have a parent extent set for it. If this is the case,
915 the extent derives all its properties from that extent and has no
916 properties of its own. The only "properties" that the extent keeps are
917 the buffer or string it refers to and the start and end points. (More
918 correctly, the extent's own properties are shadowed. If you later
919 change the extent to have no parent, its own properties will become
922 It is possible for an extent's parent to itself have a parent, and
923 so on. Through this, a whole tree of extents can be created, all
924 deriving their properties from one root extent. Note, however, that
925 you cannot create an inheritance loop--this is explicitly disallowed.
927 Parent extents are used to implement the extents over the modeline.
929 - Function: set-extent-parent extent parent
930 This function sets the parent of EXTENT to PARENT. If PARENT is
931 `nil', the extent is set to have no parent.
933 - Function: extent-parent extent
934 This function return the parents (if any) of EXTENT, or `nil'.
936 - Function: extent-children extent
937 This function returns a list of the children (if any) of EXTENT.
938 The children of an extent are all those extents whose parent is
939 that extent. This function does not recursively trace children of
942 - Function: extent-descendants extent
943 This function returns a list of all descendants of EXTENT,
944 including EXTENT. This recursively applies `extent-children' to
945 any children of EXTENT, until no more children can be found.
948 File: lispref.info, Node: Duplicable Extents, Next: Extents and Events, Prev: Extent Parents, Up: Extents
953 If an extent has the `duplicable' property, it will be copied into
954 strings, so that kill, yank, and undo commands will restore or copy it.
958 * When a string is created using `buffer-substring' or
959 `buffer-string', any duplicable extents in the region corresponding
960 to the string will be copied into the string (*note Buffer
961 Contents::). When the string is inserted into a buffer using
962 `insert', `insert-before-markers', `insert-buffer' or
963 `insert-buffer-substring', the extents in the string will be copied
964 back into the buffer (*note Insertion::). The extents in a string
965 can, of course, be retrieved explicitly using the standard extent
966 primitives over the string.
968 * Similarly, when text is copied or cut into the kill ring, any
969 duplicable extents will be remembered and reinserted later when
970 the text is pasted back into a buffer.
972 * When `concat' is called on strings, the extents in the strings are
973 copied into the resulting string.
975 * When `substring' is called on a string, the relevant extents are
976 copied into the resulting string.
978 * When a duplicable extent is detached by `detach-extent' or string
979 deletion, or inserted by `insert-extent' or string insertion, the
980 action is recorded by the undo mechanism so that it can be undone
981 later. Note that if an extent gets detached and then a later undo
982 causes the extent to get reinserted, the new extent will not be
983 `eq' to the original extent.
985 * Extent motion, face changes, and attachment via `make-extent' are
986 not recorded by the undo mechanism. This means that extent changes
987 which are to be undo-able must be performed by character editing,
988 or by insertion and detachment of duplicable extents.
990 * A duplicable extent's `copy-function' property, if non-`nil',
991 should be a function, and will be run when a duplicable extent is
992 about to be copied from a buffer to a string (or the kill ring).
993 It is called with three arguments: the extent and the buffer
994 positions within it which are being copied. If this function
995 returns `nil', then the extent will not be copied; otherwise it
998 * A duplicable extent's `paste-function' property, if non-`nil',
999 should be a function, and will be run when a duplicable extent is
1000 about to be copied from a string (or the kill ring) into a buffer.
1001 It is called with three arguments: the original extent and the
1002 buffer positions which the copied extent will occupy. (This hook
1003 is run after the corresponding text has already been inserted into
1004 the buffer.) Note that the extent argument may be detached when
1005 this function is run. If this function returns `nil', no extent
1006 will be inserted. Otherwise, there will be an extent covering the
1009 Note: if the extent to be copied is already attached to the buffer
1010 and overlaps the new range, the extent will simply be extended and
1011 the `paste-function' will not be called.
1014 File: lispref.info, Node: Extents and Events, Next: Atomic Extents, Prev: Duplicable Extents, Up: Extents
1016 Interaction of Extents with Keyboard and Mouse Events
1017 =====================================================
1019 If an extent has the `mouse-face' property set, it will be
1020 highlighted when the mouse passes over it. Highlighting is accomplished
1021 by merging the extent's face with the face or faces specified by the
1022 `mouse-face' property. The effect is as if a pseudo-extent with the
1023 `mouse-face' face were inserted after the extent in the display order
1024 (*note Extent Endpoints::, display order).
1026 - Variable: mouse-highlight-priority
1027 This variable holds the priority to use when merging in the
1028 highlighting pseudo-extent. The default is 1000. This is
1029 purposely set very high so that the highlighting pseudo-extent
1030 shows up even if there are other extents with various priorities
1031 at the same location.
1033 You can also explicitly cause an extent to be highlighted. Only one
1034 extent at a time can be highlighted in this fashion, and any other
1035 highlighted extent will be de-highlighted.
1037 - Function: highlight-extent extent &optional highlight-p
1038 This function highlights (if HIGHLIGHT-P is non-`nil') or
1039 de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the
1040 `mouse-face' property. (Nothing happens if EXTENT does not have
1041 the `mouse-face' property.)
1043 - Function: force-highlight-extent extent &optional highlight-p
1044 This function is similar to `highlight-extent' but highlights or
1045 de-highlights the extent regardless of whether it has the
1046 `mouse-face' property.
1048 If an extent has a `keymap' property, this keymap will be consulted
1049 for mouse clicks on the extent and keypresses made while `point' is
1050 within the extent. The behavior of mouse clicks and keystrokes not
1051 defined in the keymap is as normal for the buffer.
1054 File: lispref.info, Node: Atomic Extents, Prev: Extents and Events, Up: Extents
1059 If the Lisp file `atomic-extents' is loaded, then the atomic extent
1060 facility is available. An "atomic extent" is an extent for which
1061 `point' cannot be positioned anywhere within it. This ensures that
1062 when selecting text, either all or none of the extent is selected.
1064 To make an extent atomic, set its `atomic' property.
1067 File: lispref.info, Node: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top
1072 A specifier is an object used to keep track of a property whose value
1073 may vary depending on the particular situation (e.g. particular buffer
1074 displayed in a particular window) that it is used in. The value of many
1075 built-in properties, such as the font, foreground, background, and such
1076 properties of a face and variables such as `modeline-shadow-thickness'
1077 and `top-toolbar-height', is actually a specifier object. The
1078 specifier object, in turn, is "instanced" in a particular situation to
1079 yield the real value of the property in that situation.
1081 - Function: specifierp object
1082 This function returns non-`nil' if OBJECT is a specifier.
1086 * Introduction to Specifiers:: Specifiers provide a clean way for
1087 display and other properties to vary
1088 (under user control) in a wide variety
1090 * Specifiers In-Depth:: Gory details about specifier innards.
1091 * Specifier Instancing:: Instancing means obtaining the ``value'' of
1092 a specifier in a particular context.
1093 * Specifier Types:: Specifiers come in different flavors.
1094 * Adding Specifications:: Specifications control a specifier's ``value''
1095 by giving conditions under which a
1096 particular value is valid.
1097 * Retrieving Specifications:: Querying a specifier's specifications.
1098 * Specifier Tag Functions:: Working with specifier tags.
1099 * Specifier Instancing Functions::
1100 Functions to instance a specifier.
1101 * Specifier Example:: Making all this stuff clearer.
1102 * Creating Specifiers:: Creating specifiers for your own use.
1103 * Specifier Validation Functions::
1104 Validating the components of a specifier.
1105 * Other Specification Functions::
1106 Other ways of working with specifications.
1109 File: lispref.info, Node: Introduction to Specifiers, Next: Specifiers In-Depth, Up: Specifiers
1111 Introduction to Specifiers
1112 ==========================
1114 Sometimes you may want the value of a property to vary depending on
1115 the context the property is used in. A simple example of this in XEmacs
1116 is buffer-local variables. For example, the variable
1117 `modeline-format', which controls the format of the modeline, can have
1118 different values depending on the particular buffer being edited. The
1119 variable has a default value which most modes will use, but a
1120 specialized package such as Calendar might change the variable so as to
1121 tailor the modeline to its own purposes.
1123 Other properties (such as those that can be changed by the
1124 `modify-frame-parameters' function, for example the color of the text
1125 cursor) can have frame-local values, although it might also make sense
1126 for them to have buffer-local values. In other cases, you might want
1127 the property to vary depending on the particular window within the
1128 frame that applies (e.g. the top or bottom window in a split frame), the
1129 device type that that frame appears on (X or tty), etc. Perhaps you can
1130 envision some more complicated scenario where you want a particular
1131 value in a specified buffer, another value in all other buffers
1132 displayed on a particular frame, another value in all other buffers
1133 displayed in all other frames on any mono (two-color, e.g. black and
1134 white only) displays, and a default value in all other circumstances.
1136 A "specifier" is a generalization of this, allowing a great deal of
1137 flexibility in controlling exactly what value a property has in which
1138 circumstances. It is most commonly used for display properties, such as
1139 an image or the foreground color of a face. As a simple example, you
1140 can specify that the foreground of the default face be
1142 * blue for a particular buffer
1144 * green for all other buffers
1146 As a more complicated example, you could specify that the foreground
1147 of the default face be
1149 * forest green for all buffers displayed in a particular Emacs
1150 window, or green if the X server doesn't recognize the color
1153 * blue for all buffers displayed in a particular frame
1155 * red for all other buffers displayed on a color device
1157 * white for all other buffers