Mercurial > hg > xemacs-beta
annotate man/lispref/extents.texi @ 5630:f5315ccbf005
Cons less, be more careful about always using the environment, #'macroexpand
2011-12-30 Aidan Kehoe <kehoea@parhasard.net>
* eval.c (Fmacroexpand):
Don't cons if ENVIRONMENT is the same object as
byte-compile-macro-environment.
Always look up symbol- and other macros in the (possibly modified)
byte-compile-macro-environment, not the supplied ENVIRONMENT.
byte-compile-macro-environment reflects ENVIRONMENT, so that's OK
and preferred.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Fri, 30 Dec 2011 12:43:52 +0000 |
| parents | 99f8ebc082d9 |
| children | 9fae6227ede5 |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. |
| 428 | 4 @c Copyright (C) 1996 Ben Wing. |
| 5 @c See the file lispref.texi for copying conditions. | |
| 6 @setfilename ../../info/extents.info | |
| 7 @node Extents, Specifiers, Abbrevs, top | |
| 8 @chapter Extents | |
| 9 @cindex extent | |
| 10 | |
| 11 An @dfn{extent} is a region of text (a start position and an end | |
| 12 position) that is displayed in a particular face and can have certain | |
| 13 other properties such as being read-only. Extents can overlap each | |
| 14 other. XEmacs efficiently handles buffers with large numbers of | |
| 15 extents in them. | |
| 16 | |
| 17 @defun extentp object | |
| 18 This returns @code{t} if @var{object} is an extent. | |
| 19 @end defun | |
| 20 | |
| 21 @menu | |
| 22 * Intro to Extents:: Extents are regions over a buffer or string. | |
| 23 * Creating and Modifying Extents:: | |
| 24 Basic extent functions. | |
| 25 * Extent Endpoints:: Accessing and setting the bounds of an extent. | |
| 26 * Finding Extents:: Determining which extents are in an object. | |
| 27 * Mapping Over Extents:: More sophisticated functions for extent scanning. | |
| 28 * Extent Properties:: Extents have built-in and user-definable properties. | |
| 29 * Detached Extents:: Extents that are not in a buffer. | |
| 30 * Extent Parents:: Inheriting properties from another extent. | |
| 31 * Duplicable Extents:: Extents can be marked to be copied into strings. | |
| 32 * Extents and Events:: Extents can interact with the keyboard and mouse. | |
| 33 * Atomic Extents:: Treating a block of text as a single entity. | |
| 34 @end menu | |
| 35 | |
| 36 @node Intro to Extents | |
| 37 @section Introduction to Extents | |
| 38 @cindex extent priority | |
| 39 @cindex priority of an extent | |
| 40 | |
| 41 An extent is a region of text within a buffer or string that has | |
| 42 certain properties associated with it. The properties of an extent | |
| 43 primarily affect the way the text contained in the extent is displayed. | |
| 44 Extents can freely overlap each other in a buffer or string. Extents | |
| 45 are invisible to functions that merely examine the text of a buffer or | |
| 46 string. | |
| 47 | |
| 48 @emph{Please note:} An alternative way to add properties to a buffer or | |
| 49 string is to use text properties. @xref{Text Properties}. | |
| 50 | |
| 51 An extent is logically a Lisp object consisting of a start position, | |
| 52 an end position, a buffer or string to which these positions refer, and | |
| 53 a property list. As text is inserted into a buffer, the start and end | |
| 54 positions of the extent are automatically adjusted as necessary to keep | |
| 55 the extent referring to the same text in the buffer. If text is | |
| 56 inserted at the boundary of an extent, the extent's @code{start-open} | |
| 57 and @code{end-open} properties control whether the text is included as | |
| 58 part of the extent. If the text bounded by an extent is deleted, the | |
| 59 extent becomes @dfn{detached}; its start and end positions are no longer | |
| 60 meaningful, but it maintains all its other properties and can later be | |
| 61 reinserted into a buffer. (None of these considerations apply to strings, | |
| 62 because text cannot be inserted into or deleted from a string.) | |
| 63 | |
| 64 Each extent has a face or list of faces associated with it, which | |
| 65 controls the way in which the text bounded by the extent is displayed. | |
| 66 If an extent's face is @code{nil} or its properties are partially | |
| 67 undefined, the corresponding properties from the default face for the | |
| 68 frame is used. If two or more extents overlap, or if a list of more | |
| 69 than one face is specified for a particular extent, the corresponding | |
| 70 faces are merged to determine the text's displayed properties. Every | |
| 71 extent has a @dfn{priority} that determines which face takes precedence | |
| 72 if the faces conflict. (If two extents have the same priority, the one | |
| 73 that comes later in the display order takes precedence. @xref{Extent | |
| 74 Endpoints, display order}.) Higher-numbered priority values correspond | |
| 75 to a higher priority, and priority values can be negative. Every extent | |
| 76 is created with a priority of 0, but this can be changed with | |
| 77 @code{set-extent-priority}. Within a single extent with a list of faces, | |
| 78 faces earlier in the list have a higher priority than faces later in | |
| 79 the list. | |
| 80 | |
| 81 Extents can be set to respond specially to key and mouse events within | |
| 82 the extent. An extent's @code{keymap} property controls the effect of | |
| 83 key and mouse strokes within the extent's text, and the @code{mouse-face} | |
| 84 property controls whether the extent is highlighted when the mouse moves | |
| 85 over it. @xref{Extents and Events}. | |
| 86 | |
| 87 An extent can optionally have a @dfn{begin-glyph} or @dfn{end-glyph} | |
| 88 associated with it. A begin-glyph or end-glyph is a pixmap or string | |
| 89 that will be displayed either at the start or end of an extent or in the | |
| 90 margin of the line that the start or end of the extent lies in, | |
| 91 depending on the extent's layout policy. Begin-glyphs and end-glyphs | |
| 92 are used to implement annotations, and you should use the annotation API | |
| 93 functions in preference to the lower-level extent functions. For more | |
| 94 information, @xref{Annotations}. | |
| 95 | |
| 96 If an extent has its @code{detachable} property set, it will become | |
| 442 | 97 @dfn{detached} (i.e. no longer in the buffer) when all its text is |
| 428 | 98 deleted. Otherwise, it will simply shrink down to zero-length and |
| 442 | 99 sit in the same place in the buffer. By default, the @code{detachable} |
| 428 | 100 property is set on newly-created extents. @xref{Detached Extents}. |
| 101 | |
| 102 If an extent has its @code{duplicable} property set, it will be | |
| 103 remembered when a string is created from text bounded by the extent. | |
| 104 When the string is re-inserted into a buffer, the extent will also | |
| 105 be re-inserted. This mechanism is used in the kill, yank, and undo | |
| 106 commands. @xref{Duplicable Extents}. | |
| 107 | |
| 108 @node Creating and Modifying Extents | |
| 109 @section Creating and Modifying Extents | |
| 110 | |
| 444 | 111 @defun make-extent from to &optional buffer-or-string |
| 428 | 112 This function makes an extent for the range [@var{from}, @var{to}) in |
| 444 | 113 @var{buffer-or-string} (a buffer or string). @var{buffer-or-string} |
| 114 defaults to the current buffer. Insertions at point @var{to} will be | |
| 115 outside of the extent; insertions at @var{from} will be inside the | |
| 116 extent, causing the extent to grow (@pxref{Extent Endpoints}). This is | |
| 117 the same way that markers behave. The extent is initially detached if | |
| 118 both @var{from} and @var{to} are @code{nil}, and in this case | |
| 119 @var{buffer-or-string} defaults to @code{nil}, meaning the extent is in | |
| 120 no buffer or string (@pxref{Detached Extents}). | |
| 428 | 121 @end defun |
| 122 | |
| 123 @defun delete-extent extent | |
| 124 This function removes @var{extent} from its buffer and destroys it. | |
| 125 This does not modify the buffer's text, only its display properties. | |
| 126 The extent cannot be used thereafter. To remove an extent in such | |
| 127 a way that it can be re-inserted later, use @code{detach-extent}. | |
| 128 @xref{Detached Extents}. | |
| 129 @end defun | |
| 130 | |
| 131 @defun extent-object extent | |
| 132 This function returns the buffer or string that @var{extent} is in. If | |
| 133 the return value is @code{nil}, this means that the extent is detached; | |
| 134 however, a detached extent will not necessarily return a value of | |
| 135 @code{nil}. | |
| 136 @end defun | |
| 137 | |
| 444 | 138 @defun extent-live-p object |
| 139 This function returns @code{t} if @var{object} is an extent that has not | |
| 140 been deleted, and @code{nil} otherwise. | |
| 428 | 141 @end defun |
| 142 | |
| 143 @node Extent Endpoints | |
| 144 @section Extent Endpoints | |
| 145 @cindex extent endpoint | |
| 146 @cindex extent start position | |
| 147 @cindex extent end position | |
| 148 @cindex zero-length extent | |
| 149 @cindex display order | |
| 150 @cindex extent order | |
| 151 @cindex order of extents | |
| 152 | |
| 153 Every extent has a start position and an end position, and logically | |
| 154 affects the characters between those positions. Normally the start and | |
| 155 end positions must both be valid positions in the extent's buffer or | |
| 156 string. However, both endpoints can be @code{nil}, meaning the extent | |
| 157 is detached. @xref{Detached Extents}. | |
| 158 | |
| 159 Whether the extent overlaps its endpoints is governed by its | |
| 160 @code{start-open} and @code{end-open} properties. Insertion of a | |
| 161 character at a closed endpoint will expand the extent to include that | |
| 162 character; insertion at an open endpoint will not. Similarly, functions | |
| 163 such as @code{extent-at} that scan over all extents overlapping a | |
| 164 particular position will include extents with a closed endpoint at that | |
| 165 position, but not extents with an open endpoint. | |
| 166 | |
| 167 Note that the @code{start-closed} and @code{end-closed} properties are | |
| 168 equivalent to @code{start-open} and @code{end-open} with the opposite | |
| 169 sense. | |
| 170 | |
| 171 Both endpoints can be equal, in which case the extent includes no | |
| 172 characters but still exists in the buffer or string. Zero-length | |
| 173 extents are used to represent annotations (@pxref{Annotations}) and can | |
| 174 be used as a more powerful form of a marker. Deletion of all the | |
| 175 characters in an extent may or may not result in a zero-length extent; | |
| 176 this depends on the @code{detachable} property (@pxref{Detached | |
| 177 Extents}). Insertion at the position of a zero-length extent expands | |
| 178 the extent if both endpoints are closed; goes before the extent if it | |
| 179 has the @code{start-open} property; and goes after the extent if it has | |
| 180 the @code{end-open} property. Zero-length extents with both the | |
| 181 @code{start-open} and @code{end-open} properties are treated as if their | |
| 182 starting point were closed. Deletion of a character on a side of a | |
| 183 zero-length extent whose corresponding endpoint is closed causes the | |
| 184 extent to be detached if its @code{detachable} property is set; if the | |
| 185 corresponding endpoint is open, the extent remains in the buffer, moving | |
| 186 as necessary. | |
| 187 | |
| 188 Extents are ordered within a buffer or string by increasing start | |
| 189 position, and then by decreasing end position (this is called the | |
| 190 @dfn{display order}). | |
| 191 | |
| 192 @defun extent-start-position extent | |
| 193 This function returns the start position of @var{extent}. | |
| 194 @end defun | |
| 195 | |
| 196 @defun extent-end-position extent | |
| 197 This function returns the end position of @var{extent}. | |
| 198 @end defun | |
| 199 | |
| 200 @defun extent-length extent | |
| 201 This function returns the length of @var{extent} in characters. If | |
| 202 the extent is detached, this returns @code{0}. If the extent is not | |
| 203 detached, this is equivalent to | |
| 204 @example | |
| 205 (- (extent-end-position @var{extent}) (extent-start-position @var{extent})) | |
| 206 @end example | |
| 207 @end defun | |
| 208 | |
| 209 @defun set-extent-endpoints extent start end &optional buffer-or-string | |
| 210 This function sets the start and end position of @var{extent} to | |
| 211 @var{start} and @var{end}. If both are @code{nil}, this is equivalent | |
| 212 to @code{detach-extent}. | |
| 213 | |
| 214 @var{buffer-or-string} specifies the new buffer or string that the | |
| 215 extent should be in, and defaults to @var{extent}'s buffer or | |
| 216 string. (If @code{nil}, and @var{extent} is in no buffer and no string, | |
| 217 it defaults to the current buffer.) | |
| 218 | |
| 219 See documentation on @code{detach-extent} for a discussion of undo | |
| 220 recording. | |
| 221 @end defun | |
| 222 | |
| 223 @node Finding Extents | |
| 224 @section Finding Extents | |
| 225 @cindex extents, locating | |
| 226 | |
| 227 The following functions provide a simple way of determining the | |
| 228 extents in a buffer or string. A number of more sophisticated | |
| 229 primitives for mapping over the extents in a range of a buffer or string | |
| 230 are also provided (@pxref{Mapping Over Extents}). When reading through | |
| 231 this section, keep in mind the way that extents are ordered | |
| 232 (@pxref{Extent Endpoints}). | |
| 233 | |
| 444 | 234 @defun extent-list &optional buffer-or-string from to flags property value |
| 428 | 235 This function returns a list of the extents in @var{buffer-or-string}. |
| 236 @var{buffer-or-string} defaults to the current buffer if omitted. | |
| 237 @var{from} and @var{to} can be used to limit the range over which | |
| 238 extents are returned; if omitted, all extents in the buffer or string | |
| 239 are returned. | |
| 240 | |
| 241 More specifically, if a range is specified using @var{from} and | |
| 242 @var{to}, only extents that overlap the range (i.e. begin or end inside | |
| 243 of the range) are included in the list. @var{from} and @var{to} default | |
| 244 to the beginning and end of @var{buffer-or-string}, respectively. | |
| 245 | |
| 246 @var{flags} controls how end cases are treated. For a discussion of | |
| 247 this, and exactly what ``overlap'' means, see @code{map-extents}. | |
| 444 | 248 |
| 249 The optional arguments @var{property} and @var{value} can be used to | |
| 250 further restrict which extents are returned. They have the same meaning | |
| 251 as for @code{map-extents}. | |
| 252 | |
| 253 If you want to map a function over the extents in a buffer or string, | |
| 254 consider using @code{map-extents} or @code{mapcar-extents} instead. | |
| 255 | |
| 256 See also the function @code{extents-at}. | |
| 428 | 257 @end defun |
| 258 | |
| 259 Functions that create extents must be prepared for the possibility | |
| 444 | 260 that there are other extents in the same area, created by other |
| 428 | 261 functions. To deal with this, functions typically mark their own |
| 262 extents by setting a particular property on them. The following | |
| 263 function makes it easier to locate those extents. | |
| 264 | |
| 265 @defun extent-at pos &optional object property before at-flag | |
| 266 This function finds the ``smallest'' extent (i.e., the last one in the | |
| 267 display order) at (i.e., overlapping) @var{pos} in @var{object} (a | |
| 268 buffer or string) having @var{property} set. @var{object} defaults to | |
| 269 the current buffer. @var{property} defaults to @code{nil}, meaning that | |
| 270 any extent will do. Returns @code{nil} if there is no matching extent | |
| 271 at @var{pos}. If the fourth argument @var{before} is not @code{nil}, it | |
| 272 must be an extent; any returned extent will precede that extent. This | |
| 273 feature allows @code{extent-at} to be used by a loop over extents. | |
| 274 | |
| 275 @var{at-flag} controls how end cases are handled (i.e. what ``at'' | |
| 276 really means), and should be one of: | |
| 277 | |
| 278 @table @code | |
| 279 @item nil | |
| 280 @item after | |
| 281 An extent is at @var{pos} if it covers the character after @var{pos}. | |
| 282 This is consistent with the way that text properties work. | |
| 283 @item before | |
| 284 An extent is at @var{pos} if it covers the character before @var{pos}. | |
| 285 @item at | |
| 286 An extent is at @var{pos} if it overlaps or abuts @var{pos}. This | |
| 287 includes all zero-length extents at @var{pos}. | |
| 288 @end table | |
| 289 | |
| 290 Note that in all cases, the start-openness and end-openness of the | |
| 291 extents considered is ignored. If you want to pay attention to those | |
| 292 properties, you should use @code{map-extents}, which gives you more | |
| 293 control. | |
| 294 @end defun | |
| 295 | |
| 296 The following low-level functions are provided for explicitly | |
| 297 traversing the extents in a buffer according to the display order. | |
| 440 | 298 These functions are mostly intended for debugging---in normal |
| 428 | 299 operation, you should probably use @code{mapcar-extents} or |
| 300 @code{map-extents}, or loop using the @var{before} argument to | |
| 301 @code{extent-at}, rather than creating a loop using @code{next-extent}. | |
| 302 | |
| 303 @defun next-extent extent | |
| 304 Given an extent @var{extent}, this function returns the next extent in | |
| 305 the buffer or string's display order. If @var{extent} is a buffer or | |
| 306 string, this returns the first extent in the buffer or string. | |
| 307 @end defun | |
| 308 | |
| 309 @defun previous-extent extent | |
| 310 Given an extent @var{extent}, this function returns the previous extent | |
| 311 in the buffer or string's display order. If @var{extent} is a buffer or | |
| 312 string, this returns the last extent in the buffer or string. | |
| 313 @end defun | |
| 314 | |
| 315 @node Mapping Over Extents | |
| 316 @section Mapping Over Extents | |
| 317 @cindex extents, mapping | |
| 318 | |
| 319 The most basic and general function for mapping over extents is called | |
| 320 @code{map-extents}. You should read through the definition of this | |
| 321 function to familiarize yourself with the concepts and optional | |
| 322 arguments involved. However, in practice you may find it more | |
| 323 convenient to use the function @code{mapcar-extents} or to create a loop | |
| 324 using the @code{before} argument to @code{extent-at} (@pxref{Finding | |
| 325 Extents}). | |
| 326 | |
| 327 @defun map-extents function &optional object from to maparg flags property value | |
| 328 This function maps @var{function} over the extents which overlap a | |
| 329 region in @var{object}. @var{object} is normally a buffer or string but | |
| 330 could be an extent (see below). The region is normally bounded by | |
| 331 [@var{from}, @var{to}) (i.e. the beginning of the region is closed and | |
| 332 the end of the region is open), but this can be changed with the | |
| 333 @var{flags} argument (see below for a complete discussion). | |
| 334 | |
| 335 @var{function} is called with the arguments (extent, @var{maparg}). | |
| 336 The arguments @var{object}, @var{from}, @var{to}, @var{maparg}, and | |
| 337 @var{flags} are all optional and default to the current buffer, the | |
| 444 | 338 beginning of @var{object}, the end of @var{object}, @code{nil}, and |
| 339 @code{nil}, respectively. @code{map-extents} returns the first | |
| 428 | 340 non-@code{nil} result produced by @var{function}, and no more calls to |
| 341 @var{function} are made after it returns non-@code{nil}. | |
| 342 | |
| 343 If @var{object} is an extent, @var{from} and @var{to} default to the | |
| 344 extent's endpoints, and the mapping omits that extent and its | |
| 345 predecessors. This feature supports restarting a loop based on | |
| 346 @code{map-extents}. Note: @var{object} must be attached to a buffer or | |
| 347 string, and the mapping is done over that buffer or string. | |
| 348 | |
| 349 An extent overlaps the region if there is any point in the extent that | |
| 350 is also in the region. (For the purpose of overlap, zero-length extents | |
| 351 and regions are treated as closed on both ends regardless of their | |
| 352 endpoints' specified open/closedness.) Note that the endpoints of an | |
| 353 extent or region are considered to be in that extent or region if and | |
| 354 only if the corresponding end is closed. For example, the extent [5,7] | |
| 355 overlaps the region [2,5] because 5 is in both the extent and the | |
| 356 region. However, (5,7] does not overlap [2,5] because 5 is not in the | |
| 357 extent, and neither [5,7] nor (5,7] overlaps the region [2,5) because 5 | |
| 358 is not in the region. | |
| 359 | |
| 360 The optional @var{flags} can be a symbol or a list of one or more | |
| 361 symbols, modifying the behavior of @code{map-extents}. Allowed symbols | |
| 362 are: | |
| 363 | |
| 364 @table @code | |
| 365 @item end-closed | |
| 366 The region's end is closed. | |
| 367 | |
| 368 @item start-open | |
| 369 The region's start is open. | |
| 370 | |
| 371 @item all-extents-closed | |
| 372 Treat all extents as closed on both ends for the purpose of determining | |
| 373 whether they overlap the region, irrespective of their actual open- or | |
| 374 closedness. | |
| 375 @item all-extents-open | |
| 376 Treat all extents as open on both ends. | |
| 377 @item all-extents-closed-open | |
| 378 Treat all extents as start-closed, end-open. | |
| 379 @item all-extents-open-closed | |
| 380 Treat all extents as start-open, end-closed. | |
| 381 | |
| 382 @item start-in-region | |
| 383 In addition to the above conditions for extent overlap, the extent's | |
| 384 start position must lie within the specified region. Note that, for | |
| 385 this condition, open start positions are treated as if 0.5 was added to | |
| 386 the endpoint's value, and open end positions are treated as if 0.5 was | |
| 387 subtracted from the endpoint's value. | |
| 388 @item end-in-region | |
| 389 The extent's end position must lie within the region. | |
| 390 @item start-and-end-in-region | |
| 391 Both the extent's start and end positions must lie within the region. | |
| 392 @item start-or-end-in-region | |
| 393 Either the extent's start or end position must lie within the region. | |
| 394 | |
| 395 @item negate-in-region | |
| 396 The condition specified by a @code{*-in-region} flag must @emph{not} | |
| 397 hold for the extent to be considered. | |
| 398 @end table | |
| 399 | |
| 400 At most one of @code{all-extents-closed}, @code{all-extents-open}, | |
| 401 @code{all-extents-closed-open}, and @code{all-extents-open-closed} may | |
| 402 be specified. | |
| 403 | |
| 404 At most one of @code{start-in-region}, @code{end-in-region}, | |
| 405 @code{start-and-end-in-region}, and @code{start-or-end-in-region} may be | |
| 406 specified. | |
| 407 | |
| 408 If optional arg @var{property} is non-@code{nil}, only extents with | |
| 409 that property set on them will be visited. If optional arg @var{value} | |
| 410 is non-@code{nil}, only extents whose value for that property is | |
| 411 @code{eq} to @var{value} will be visited. | |
| 412 @end defun | |
| 413 | |
| 414 If you want to map over extents and accumulate a list of results, | |
| 415 the following function may be more convenient than @code{map-extents}. | |
| 416 | |
| 417 @defun mapcar-extents function &optional predicate buffer-or-string from to flags property value | |
| 418 This function applies @var{function} to all extents which overlap a | |
| 419 region in @var{buffer-or-string}. The region is delimited by | |
| 420 @var{from} and @var{to}. @var{function} is called with one argument, | |
| 421 the extent. A list of the values returned by @var{function} is | |
| 422 returned. An optional @var{predicate} may be used to further limit the | |
| 423 extents over which @var{function} is mapped. The optional arguments | |
| 424 @var{flags}, @var{property}, and @var{value} may also be used to control | |
| 425 the extents passed to @var{predicate} or @var{function}, and have the | |
| 426 same meaning as in @code{map-extents}. | |
| 427 @end defun | |
| 428 | |
| 429 @defun map-extent-children function &optional object from to maparg flags property value | |
| 430 This function is similar to @code{map-extents}, but differs in that: | |
| 431 | |
| 432 @itemize @bullet | |
| 433 @item | |
| 434 It only visits extents which start in the given region. | |
| 435 @item | |
| 436 After visiting an extent @var{e}, it skips all other extents which start | |
| 437 inside @var{e} but end before @var{e}'s end. | |
| 438 @end itemize | |
| 439 | |
| 440 Thus, this function may be used to walk a tree of extents in a buffer: | |
| 441 @example | |
| 442 (defun walk-extents (buffer &optional ignore) | |
| 443 (map-extent-children 'walk-extents buffer)) | |
| 444 @end example | |
| 445 @end defun | |
| 446 | |
| 447 @defun extent-in-region-p extent &optional from to flags | |
| 444 | 448 This function returns @code{t} if @code{map-extents} would visit |
| 428 | 449 @var{extent} if called with the given arguments. |
| 450 @end defun | |
| 451 | |
| 452 @node Extent Properties | |
| 453 @section Properties of Extents | |
| 454 @cindex extent property | |
| 455 @cindex property of an extent | |
| 456 | |
| 457 Each extent has a property list associating property names with | |
| 458 values. Some property names have predefined meanings, and can usually | |
| 459 only assume particular values. Assigning other values to such a | |
| 460 property either cause the value to be converted into a legal value | |
| 461 (e.g., assigning anything but @code{nil} to a Boolean property will | |
| 462 cause the value of @code{t} to be assigned to the property) or will | |
| 463 cause an error. Property names without predefined meanings can be | |
| 464 assigned any value. An undefined property is equivalent to a property | |
| 465 with a value of @code{nil}, or with a particular default value in the | |
| 466 case of properties with predefined meanings. Note that, when an extent | |
| 467 is created, the @code{end-open} and @code{detachable} properties are set | |
| 468 on it. | |
| 469 | |
| 470 If an extent has a parent, all of its properties actually derive | |
| 471 from that parent (or from the root ancestor if the parent in turn | |
| 472 has a parent), and setting a property of the extent actually sets | |
| 473 that property on the parent. @xref{Extent Parents}. | |
| 474 | |
| 444 | 475 @defun extent-property extent property &optional default |
| 476 This function returns @var{extent}'s value for @var{property}, or | |
| 477 @var{default} if no such property exists. | |
| 428 | 478 @end defun |
| 479 | |
| 480 @defun extent-properties extent | |
| 481 This function returns a list of all of @var{extent}'s properties that do | |
| 482 not have the value of @code{nil} (or the default value, for properties | |
| 483 with predefined meanings). | |
| 484 @end defun | |
| 485 | |
| 486 @defun set-extent-property extent property value | |
| 487 This function sets @var{property} to @var{value} in @var{extent}. (If | |
| 488 @var{property} has a predefined meaning, only certain values are | |
| 489 allowed, and some values may be converted to others before being | |
| 490 stored.) | |
| 491 @end defun | |
| 492 | |
| 493 @defun set-extent-properties extent plist | |
| 494 Change some properties of @var{extent}. @var{plist} is a property | |
| 495 list. This is useful to change many extent properties at once. | |
| 496 @end defun | |
| 497 | |
| 498 The following table lists the properties with predefined meanings, along | |
| 499 with their allowable values. | |
| 500 | |
| 501 @table @code | |
| 502 @item detached | |
| 503 (Boolean) Whether the extent is detached. Setting this is the same | |
| 504 as calling @code{detach-extent}. @xref{Detached Extents}. | |
| 505 | |
| 506 @item destroyed | |
| 507 (Boolean) Whether the extent has been deleted. Setting this is the same | |
| 508 as calling @code{delete-extent}. | |
| 509 | |
| 510 @item priority | |
| 511 (integer) The extent's redisplay priority. Defaults to 0. @xref{Intro | |
| 512 to Extents, priority}. This property can also be set with | |
| 513 @code{set-extent-priority} and accessed with @code{extent-priority}. | |
| 514 | |
| 515 @item start-open | |
| 516 (Boolean) Whether the start position of the extent is open, meaning that | |
| 517 characters inserted at that position go outside of the extent. | |
| 518 @xref{Extent Endpoints}. | |
| 519 | |
| 520 @item start-closed | |
| 521 (Boolean) Same as @code{start-open} but with the opposite sense. Setting | |
| 522 this property clears @code{start-open} and vice-versa. | |
| 523 | |
| 524 @item end-open | |
| 525 (Boolean) Whether the end position of the extent is open, meaning that | |
| 526 characters inserted at that position go outside of the extent. This is | |
| 527 @code{t} by default. | |
| 528 @xref{Extent Endpoints}. | |
| 529 | |
| 530 @item end-closed | |
| 531 (Boolean) Same as @code{end-open} but with the opposite sense. Setting | |
| 532 this property clears @code{end-open} and vice-versa. | |
| 533 | |
| 534 @item read-only | |
| 535 (Boolean) Whether text within this extent will be unmodifiable. | |
| 536 | |
| 537 @item face | |
| 538 (face, face name, list of faces or face names, or @code{nil}) The face | |
| 539 in which to display the extent's text. This property can also be set | |
| 540 with @code{set-extent-face} and accessed with @code{extent-face}. | |
| 541 Note that if a list of faces is specified, the faces are merged together, | |
| 542 with faces earlier in the list having priority over faces later in the | |
| 543 list. | |
| 544 | |
| 545 @item mouse-face | |
| 546 (face, face name, list of faces or face names, or @code{nil}) The face | |
| 547 used to display the extent when the mouse moves over it. This property | |
| 548 can also be set with @code{set-extent-mouse-face} and accessed with | |
| 549 @code{extent-mouse-face}. Note that if a list of faces is specified, | |
| 550 the faces are merged together, with faces earlier in the list having | |
| 551 priority over faces later in the list. @xref{Extents and Events}. | |
| 552 | |
| 553 @item pointer | |
| 554 (pointer glyph) The glyph used as the pointer when the mouse moves over | |
| 555 the extent. This takes precedence over the @code{text-pointer-glyph} | |
| 556 and @code{nontext-pointer-glyph} variables. If for any reason this | |
| 557 glyph is an invalid pointer, the standard glyphs will be used as | |
| 2182 | 558 fallbacks. @xref{External Glyphs}. |
| 428 | 559 |
| 560 @item detachable | |
| 561 (Boolean) Whether this extent becomes detached when all of the text it | |
| 562 covers is deleted. This is @code{t} by default. @xref{Detached | |
| 563 Extents}. | |
| 564 | |
| 565 @item duplicable | |
| 566 (Boolean) Whether this extent should be copied into strings, so that | |
| 567 kill, yank, and undo commands will restore or copy it. @xref{Duplicable | |
| 568 Extents}. | |
| 569 | |
| 570 @item unique | |
| 571 (Boolean) Meaningful only in conjunction with @code{duplicable}. | |
| 572 When this is set, there may be only one instance of | |
| 573 this extent attached at a time. @xref{Duplicable Extents}. | |
| 574 | |
| 575 @item invisible | |
| 576 (Boolean) If @code{t}, text under this extent will not be displayed -- | |
| 1620 | 577 it will look as if the text and the begin-glyph is not there at all. |
| 578 The end-glyph will still be displayed. | |
| 428 | 579 |
| 580 @item keymap | |
| 581 (keymap or @code{nil}) This keymap is consulted for mouse clicks on this | |
| 582 extent or keypresses made while @code{point} is within the extent. | |
| 583 @xref{Extents and Events}. | |
| 584 | |
| 585 @item copy-function | |
| 586 This is a hook that is run when a duplicable extent is about to be | |
| 587 copied from a buffer to a string (or the kill ring). @xref{Duplicable | |
| 588 Extents}. | |
| 589 | |
| 590 @item paste-function | |
| 591 This is a hook that is run when a duplicable extent is about to be | |
| 592 copied from a string (or the kill ring) into a buffer. @xref{Duplicable | |
| 593 Extents}. | |
| 594 | |
| 595 @item begin-glyph | |
| 596 (glyph or @code{nil}) This extent's begin glyph. | |
| 597 @xref{Annotations}. | |
| 598 | |
| 599 @item end-glyph | |
| 600 (glyph or @code{nil}) This extent's end glyph. | |
| 601 @xref{Annotations}. | |
| 602 | |
| 603 @item begin-glyph-layout | |
| 604 (@code{text}, @code{whitespace}, @code{inside-margin}, or | |
| 605 @code{outside-margin}) The layout policy for this extent's begin glyph. | |
| 606 Defaults to @code{text}. @xref{Annotations}. | |
| 607 | |
| 608 @item end-glyph-layout | |
| 609 (@code{text}, @code{whitespace}, @code{inside-margin}, or | |
| 610 @code{outside-margin}) The layout policy for this extent's end glyph. | |
| 611 Defaults to @code{text}. @xref{Annotations}. | |
| 612 | |
| 613 @item initial-redisplay-function | |
| 614 (any funcallable object) The function to be called the first time (a | |
| 615 part of) the extent is redisplayed. It will be called with the extent | |
| 616 as its argument. | |
| 617 | |
| 618 This is used by @code{lazy-shot} to implement lazy font-locking. The | |
| 619 functionality is still experimental, and may change without further | |
| 620 notice. | |
| 621 @end table | |
| 622 | |
| 623 The following convenience functions are provided for accessing | |
| 624 particular properties of an extent. | |
| 625 | |
| 626 @defun extent-face extent | |
| 627 This function returns the @code{face} property of @var{extent}. This | |
| 628 might also return a list of face names. Do not modify this list | |
| 629 directly! Instead, use @code{set-extent-face}. | |
| 630 | |
| 631 Note that you can use @code{eq} to compare lists of faces as returned | |
| 632 by @code{extent-face}. In other words, if you set the face of two | |
| 633 different extents to two lists that are @code{equal} but not @code{eq}, | |
| 634 then the return value of @code{extent-face} on the two extents will | |
| 635 return the identical list. | |
| 636 @end defun | |
| 637 | |
| 638 @defun extent-mouse-face extent | |
| 639 This function returns the @code{mouse-face} property of @var{extent}. | |
| 640 This might also return a list of face names. Do not modify this list | |
| 641 directly! Instead, use @code{set-extent-mouse-face}. | |
| 642 | |
| 643 Note that you can use @code{eq} to compare lists of faces as returned | |
| 644 by @code{extent-mouse-face}, just like for @code{extent-face}. | |
| 645 @end defun | |
| 646 | |
| 647 @defun extent-priority extent | |
| 648 This function returns the @code{priority} property of @var{extent}. | |
| 649 @end defun | |
| 650 | |
| 651 @defun extent-keymap extent | |
| 652 This function returns the @code{keymap} property of @var{extent}. | |
| 653 @end defun | |
| 654 | |
| 655 @defun extent-begin-glyph-layout extent | |
| 656 This function returns the @code{begin-glyph-layout} property of | |
| 657 @var{extent}, i.e. the layout policy associated with the @var{extent}'s | |
| 658 begin glyph. | |
| 659 @end defun | |
| 660 | |
| 661 @defun extent-end-glyph-layout extent | |
| 662 This function returns the @code{end-glyph-layout} property of | |
| 663 @var{extent}, i.e. the layout policy associated with the @var{extent}'s | |
| 664 end glyph. | |
| 665 @end defun | |
| 666 | |
| 667 @defun extent-begin-glyph extent | |
| 668 This function returns the @code{begin-glyph} property of @var{extent}, | |
| 669 i.e. the glyph object displayed at the beginning of @var{extent}. If | |
| 670 there is none, @code{nil} is returned. | |
| 671 @end defun | |
| 672 | |
| 673 @defun extent-end-glyph extent | |
| 674 This function returns the @code{end-glyph} property of @var{extent}, | |
| 675 i.e. the glyph object displayed at the end of @var{extent}. If | |
| 676 there is none, @code{nil} is returned. | |
| 677 @end defun | |
| 678 | |
| 679 The following convenience functions are provided for setting particular | |
| 680 properties of an extent. | |
| 681 | |
| 444 | 682 @defun set-extent-priority extent priority |
| 428 | 683 This function sets the @code{priority} property of @var{extent} to |
| 444 | 684 @var{priority}. |
| 428 | 685 @end defun |
| 686 | |
| 687 @defun set-extent-face extent face | |
| 688 This function sets the @code{face} property of @var{extent} to | |
| 689 @var{face}. | |
| 690 @end defun | |
| 691 | |
| 692 @defun set-extent-mouse-face extent face | |
| 693 This function sets the @code{mouse-face} property of @var{extent} to | |
| 694 @var{face}. | |
| 695 @end defun | |
| 696 | |
| 697 @defun set-extent-keymap extent keymap | |
| 698 This function sets the @code{keymap} property of @var{extent} to | |
| 699 @var{keymap}. @var{keymap} must be either a keymap object, or | |
| 700 @code{nil}. | |
| 701 @end defun | |
| 702 | |
| 703 @defun set-extent-begin-glyph-layout extent layout | |
| 704 This function sets the @code{begin-glyph-layout} property of | |
| 705 @var{extent} to @var{layout}. | |
| 706 @end defun | |
| 707 | |
| 708 @defun set-extent-end-glyph-layout extent layout | |
| 709 This function sets the @code{end-glyph-layout} property of | |
| 710 @var{extent} to @var{layout}. | |
| 711 @end defun | |
| 712 | |
| 713 @defun set-extent-begin-glyph extent begin-glyph &optional layout | |
| 714 This function sets the @code{begin-glyph} and @code{glyph-layout} | |
| 715 properties of @var{extent} to @var{begin-glyph} and @var{layout}, | |
| 716 respectively. (@var{layout} defaults to @code{text} if not specified.) | |
| 717 @end defun | |
| 718 | |
| 719 @defun set-extent-end-glyph extent end-glyph &optional layout | |
| 720 This function sets the @code{end-glyph} and @code{glyph-layout} | |
| 721 properties of @var{extent} to @var{end-glyph} and @var{layout}, | |
| 722 respectively. (@var{layout} defaults to @code{text} if not specified.) | |
| 723 @end defun | |
| 724 | |
| 725 @defun set-extent-initial-redisplay-function extent function | |
| 444 | 726 This function sets the @code{initial-redisplay-function} property of the |
| 428 | 727 extent to @var{function}. |
| 728 @end defun | |
| 729 | |
| 730 @node Detached Extents | |
| 731 @section Detached Extents | |
| 732 @cindex detached extent | |
| 733 | |
| 734 A detached extent is an extent that is not attached to a buffer or | |
| 735 string but can be re-inserted. Detached extents have a start position | |
| 736 and end position of @code{nil}. Extents can be explicitly detached | |
| 737 using @code{detach-extent}. An extent is also detached when all of its | |
| 738 characters are all killed by a deletion, if its @code{detachable} | |
| 739 property is set; if this property is not set, the extent becomes a | |
| 740 zero-length extent. (Zero-length extents with the @code{detachable} | |
| 741 property set behave specially. @xref{Extent Endpoints, zero-length | |
| 742 extents}.) | |
| 743 | |
| 744 @defun detach-extent extent | |
| 745 This function detaches @var{extent} from its buffer or string. If | |
| 746 @var{extent} has the @code{duplicable} property, its detachment is | |
| 747 tracked by the undo mechanism. @xref{Duplicable Extents}. | |
| 748 @end defun | |
| 749 | |
| 750 @defun extent-detached-p extent | |
| 751 This function returns @code{nil} if @var{extent} is detached, and | |
| 752 @code{t} otherwise. | |
| 753 @end defun | |
| 754 | |
| 755 @defun copy-extent extent &optional object | |
| 756 This function makes a copy of @var{extent}. It is initially detached. | |
| 757 Optional argument @var{object} defaults to @var{extent}'s object | |
| 758 (normally a buffer or string, but could be @code{nil}). | |
| 759 @end defun | |
| 760 | |
| 761 @defun insert-extent extent &optional start end no-hooks object | |
| 762 This function inserts @var{extent} from @var{start} to @var{end} in | |
| 763 @var{object} (a buffer or string). If @var{extent} is detached from a | |
| 764 different buffer or string, or in most cases when @var{extent} is | |
| 765 already attached, the extent will first be copied as if with | |
| 766 @code{copy-extent}. This function operates the same as if @code{insert} | |
| 767 were called on a string whose extent data calls for @var{extent} to be | |
| 768 inserted, except that if @var{no-hooks} is non-@code{nil}, | |
| 769 @var{extent}'s @code{paste-function} will not be invoked. | |
| 770 @xref{Duplicable Extents}. | |
| 771 @end defun | |
| 772 | |
| 773 @node Extent Parents | |
| 774 @section Extent Parents | |
| 775 @cindex extent parent | |
| 776 @cindex extent children | |
| 777 @cindex parent, of extent | |
| 778 @cindex children, of extent | |
| 779 | |
| 780 An extent can have a parent extent set for it. If this is the case, | |
| 781 the extent derives all its properties from that extent and has no | |
| 782 properties of its own. The only ``properties'' that the extent keeps | |
| 783 are the buffer or string it refers to and the start and end points. | |
| 784 (More correctly, the extent's own properties are shadowed. If you | |
| 785 later change the extent to have no parent, its own properties will | |
| 786 become visible again.) | |
| 787 | |
| 788 It is possible for an extent's parent to itself have a parent, | |
| 789 and so on. Through this, a whole tree of extents can be created, | |
| 790 all deriving their properties from one root extent. Note, however, | |
| 440 | 791 that you cannot create an inheritance loop---this is explicitly |
| 428 | 792 disallowed. |
| 793 | |
| 794 Parent extents are used to implement the extents over the modeline. | |
| 795 | |
| 796 @defun set-extent-parent extent parent | |
| 797 This function sets the parent of @var{extent} to @var{parent}. | |
| 798 If @var{parent} is @code{nil}, the extent is set to have no parent. | |
| 799 @end defun | |
| 800 | |
| 801 @defun extent-parent extent | |
| 802 This function return the parents (if any) of @var{extent}, or | |
| 803 @code{nil}. | |
| 804 @end defun | |
| 805 | |
| 806 @defun extent-children extent | |
| 807 This function returns a list of the children (if any) of @var{extent}. | |
| 808 The children of an extent are all those extents whose parent is that | |
| 809 extent. This function does not recursively trace children of children. | |
| 810 @end defun | |
| 811 | |
| 812 @defun extent-descendants extent | |
| 813 This function returns a list of all descendants of @var{extent}, | |
| 814 including @var{extent}. This recursively applies @code{extent-children} | |
| 815 to any children of @var{extent}, until no more children can be found. | |
| 816 @end defun | |
| 817 | |
| 818 @node Duplicable Extents | |
| 819 @section Duplicable Extents | |
| 820 @cindex duplicable extent | |
| 821 @cindex unique extents | |
| 822 @cindex extent replica | |
| 823 @cindex extent, duplicable | |
| 824 @cindex extent, unique | |
| 825 | |
| 826 If an extent has the @code{duplicable} property, it will be copied into | |
| 827 strings, so that kill, yank, and undo commands will restore or copy it. | |
| 828 | |
| 829 Specifically: | |
| 830 | |
| 831 @itemize @bullet | |
| 832 @item | |
| 833 When a string is created using @code{buffer-substring} or | |
| 834 @code{buffer-string}, any duplicable extents in the region corresponding | |
| 835 to the string will be copied into the string (@pxref{Buffer | |
| 456 | 836 Contents}). When the string is inserted into a buffer using |
| 428 | 837 @code{insert}, @code{insert-before-markers}, @code{insert-buffer} or |
| 838 @code{insert-buffer-substring}, the extents in the string will be copied | |
| 839 back into the buffer (@pxref{Insertion}). The extents in a string can, | |
| 840 of course, be retrieved explicitly using the standard extent primitives | |
| 841 over the string. | |
| 842 | |
| 843 @item | |
| 844 Similarly, when text is copied or cut into the kill ring, any duplicable | |
| 845 extents will be remembered and reinserted later when the text is pasted | |
| 846 back into a buffer. | |
| 847 | |
| 848 @item | |
| 849 When @code{concat} is called on strings, the extents in the strings are | |
| 850 copied into the resulting string. | |
| 851 | |
| 852 @item | |
|
5089
99f8ebc082d9
Make #'substring an alias of #'subseq; give the latter the byte code.
Aidan Kehoe <kehoea@parhasard.net>
parents:
2182
diff
changeset
|
853 When @code{subseq} (or its alias, @code{substring}) is called on a |
|
99f8ebc082d9
Make #'substring an alias of #'subseq; give the latter the byte code.
Aidan Kehoe <kehoea@parhasard.net>
parents:
2182
diff
changeset
|
854 string, the relevant extents are copied into the resulting string. |
| 428 | 855 |
| 856 @item | |
| 857 When a duplicable extent is detached by @code{detach-extent} or string | |
| 858 deletion, or inserted by @code{insert-extent} or string insertion, the | |
| 859 action is recorded by the undo mechanism so that it can be undone later. | |
| 860 Note that if an extent gets detached and then a later undo causes the | |
| 861 extent to get reinserted, the new extent will not be `eq' to the original | |
| 862 extent. | |
| 863 | |
| 864 @item | |
| 865 Extent motion, face changes, and attachment via @code{make-extent} are | |
| 866 not recorded by the undo mechanism. This means that extent changes | |
| 867 which are to be undo-able must be performed by character editing, or by | |
| 868 insertion and detachment of duplicable extents. | |
| 869 | |
| 870 @item | |
| 871 A duplicable extent's @code{copy-function} property, if non-@code{nil}, | |
| 872 should be a function, and will be run when a duplicable extent is about | |
| 873 to be copied from a buffer to a string (or the kill ring). It is called | |
| 874 with three arguments: the extent and the buffer positions within it | |
| 875 which are being copied. If this function returns @code{nil}, then the | |
| 876 extent will not be copied; otherwise it will. | |
| 877 | |
| 878 @item | |
| 879 A duplicable extent's @code{paste-function} property, if non-@code{nil}, | |
| 880 should be a function, and will be run when a duplicable extent is about | |
| 881 to be copied from a string (or the kill ring) into a buffer. It is | |
| 882 called with three arguments: the original extent and the buffer | |
| 883 positions which the copied extent will occupy. (This hook is run after | |
| 884 the corresponding text has already been inserted into the buffer.) Note | |
| 885 that the extent argument may be detached when this function is run. If | |
| 886 this function returns @code{nil}, no extent will be inserted. | |
| 887 Otherwise, there will be an extent covering the range in question. | |
| 888 | |
| 889 Note: if the extent to be copied is already attached to the buffer and | |
| 890 overlaps the new range, the extent will simply be extended and the | |
| 891 @code{paste-function} will not be called. | |
| 892 @end itemize | |
| 893 | |
| 894 @node Extents and Events | |
| 895 @section Interaction of Extents with Keyboard and Mouse Events | |
| 896 | |
| 897 If an extent has the @code{mouse-face} property set, it will be | |
| 1620 | 898 highlighted when the mouse passes over it. This includes the |
| 899 begin-glyph, but not the end-glyph. Highlighting is accomplished by | |
| 900 merging the extent's face with the face or faces specified by the | |
| 428 | 901 @code{mouse-face} property. The effect is as if a pseudo-extent with |
| 902 the @code{mouse-face} face were inserted after the extent in the display | |
| 903 order (@pxref{Extent Endpoints}, display order). | |
| 904 | |
| 905 @defvar mouse-highlight-priority | |
| 906 This variable holds the priority to use when merging in the highlighting | |
| 907 pseudo-extent. The default is 1000. This is purposely set very high | |
| 908 so that the highlighting pseudo-extent shows up even if there are other | |
| 909 extents with various priorities at the same location. | |
| 910 @end defvar | |
| 911 | |
| 912 You can also explicitly cause an extent to be highlighted. Only one | |
| 913 extent at a time can be highlighted in this fashion, and any other | |
| 914 highlighted extent will be de-highlighted. | |
| 915 | |
| 916 @defun highlight-extent extent &optional highlight-p | |
| 917 This function highlights (if @var{highlight-p} is non-@code{nil}) or | |
| 918 de-highlights (if @var{highlight-p} is @code{nil}) @var{extent}, if | |
| 919 @var{extent} has the @code{mouse-face} property. (Nothing happens if | |
| 920 @var{extent} does not have the @code{mouse-face} property.) | |
| 921 @end defun | |
| 922 | |
| 923 @defun force-highlight-extent extent &optional highlight-p | |
| 924 This function is similar to @code{highlight-extent} but highlights | |
| 925 or de-highlights the extent regardless of whether it has the | |
| 926 @code{mouse-face} property. | |
| 927 @end defun | |
| 928 | |
| 929 If an extent has a @code{keymap} property, this keymap will be | |
| 930 consulted for mouse clicks on the extent and keypresses made while | |
| 931 @code{point} is within the extent. The behavior of mouse clicks and | |
| 932 keystrokes not defined in the keymap is as normal for the buffer. | |
| 933 | |
| 934 @node Atomic Extents | |
| 935 @section Atomic Extents | |
| 936 @cindex atomic extent | |
| 937 | |
| 938 If the Lisp file @file{atomic-extents} is loaded, then the atomic | |
| 939 extent facility is available. An @dfn{atomic extent} is an extent for | |
| 940 which @code{point} cannot be positioned anywhere within it. This | |
| 941 ensures that when selecting text, either all or none of the extent is | |
| 942 selected. | |
| 943 | |
| 944 To make an extent atomic, set its @code{atomic} property. |