1 This is ../info/lispref.info, produced by makeinfo version 4.0 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: Parsing Expressions, Next: Standard Syntax Tables, Prev: Motion and Syntax, Up: Syntax Tables
55 Parsing Balanced Expressions
56 ============================
58 Here are several functions for parsing and scanning balanced
59 expressions, also known as "sexps", in which parentheses match in
60 pairs. The syntax table controls the interpretation of characters, so
61 these functions can be used for Lisp expressions when in Lisp mode and
62 for C expressions when in C mode. *Note List Motion::, for convenient
63 higher-level functions for moving over balanced expressions.
65 - Function: parse-partial-sexp start limit &optional target-depth
66 stop-before state stop-comment buffer
67 This function parses a sexp in the current buffer starting at
68 START, not scanning past LIMIT. It stops at position LIMIT or
69 when certain criteria described below are met, and sets point to
70 the location where parsing stops. It returns a value describing
71 the status of the parse at the point where it stops.
73 If STATE is `nil', START is assumed to be at the top level of
74 parenthesis structure, such as the beginning of a function
75 definition. Alternatively, you might wish to resume parsing in the
76 middle of the structure. To do this, you must provide a STATE
77 argument that describes the initial status of parsing.
79 If the third argument TARGET-DEPTH is non-`nil', parsing stops if
80 the depth in parentheses becomes equal to TARGET-DEPTH. The depth
81 starts at 0, or at whatever is given in STATE.
83 If the fourth argument STOP-BEFORE is non-`nil', parsing stops
84 when it comes to any character that starts a sexp. If
85 STOP-COMMENT is non-`nil', parsing stops when it comes to the
88 The fifth argument STATE is an eight-element list of the same form
89 as the value of this function, described below. The return value
90 of one call may be used to initialize the state of the parse on
91 another call to `parse-partial-sexp'.
93 The result is a list of eight elements describing the final state
96 0. The depth in parentheses, counting from 0.
98 1. The character position of the start of the innermost
99 parenthetical grouping containing the stopping point; `nil'
102 2. The character position of the start of the last complete
103 subexpression terminated; `nil' if none.
105 3. Non-`nil' if inside a string. More precisely, this is the
106 character that will terminate the string.
108 4. `t' if inside a comment (of either style).
110 5. `t' if point is just after a quote character.
112 6. The minimum parenthesis depth encountered during this scan.
114 7. `t' if inside a comment of style "b".
116 Elements 0, 3, 4, 5 and 7 are significant in the argument STATE.
118 This function is most often used to compute indentation for
119 languages that have nested parentheses.
121 - Function: scan-lists from count depth &optional buffer noerror
122 This function scans forward COUNT balanced parenthetical groupings
123 from character number FROM. It returns the character position
124 where the scan stops.
126 If DEPTH is nonzero, parenthesis depth counting begins from that
127 value. The only candidates for stopping are places where the
128 depth in parentheses becomes zero; `scan-lists' counts COUNT such
129 places and then stops. Thus, a positive value for DEPTH means go
130 out DEPTH levels of parenthesis.
132 Scanning ignores comments if `parse-sexp-ignore-comments' is
135 If the scan reaches the beginning or end of the buffer (or its
136 accessible portion), and the depth is not zero, an error is
137 signaled. If the depth is zero but the count is not used up,
140 If optional arg BUFFER is non-`nil', scanning occurs in that
141 buffer instead of in the current buffer.
143 If optional arg NOERROR is non-`nil', `scan-lists' will return
144 `nil' instead of signalling an error.
146 - Function: scan-sexps from count &optional buffer noerror
147 This function scans forward COUNT sexps from character position
148 FROM. It returns the character position where the scan stops.
150 Scanning ignores comments if `parse-sexp-ignore-comments' is
153 If the scan reaches the beginning or end of (the accessible part
154 of) the buffer in the middle of a parenthetical grouping, an error
155 is signaled. If it reaches the beginning or end between groupings
156 but before count is used up, `nil' is returned.
158 If optional arg BUFFER is non-`nil', scanning occurs in that
159 buffer instead of in the current buffer.
161 If optional arg NOERROR is non-`nil', `scan-sexps' will return nil
162 instead of signalling an error.
164 - Variable: parse-sexp-ignore-comments
165 If the value is non-`nil', then comments are treated as whitespace
166 by the functions in this section and by `forward-sexp'.
168 In older Emacs versions, this feature worked only when the comment
169 terminator is something like `*/', and appears only to end a
170 comment. In languages where newlines terminate comments, it was
171 necessary make this variable `nil', since not every newline is the
172 end of a comment. This limitation no longer exists.
174 You can use `forward-comment' to move forward or backward over one
175 comment or several comments.
177 - Function: forward-comment count &optional buffer
178 This function moves point forward across COUNT comments (backward,
179 if COUNT is negative). If it finds anything other than a comment
180 or whitespace, it stops, leaving point at the place where it
181 stopped. It also stops after satisfying COUNT.
183 Optional argument BUFFER defaults to the current buffer.
185 To move forward over all comments and whitespace following point, use
186 `(forward-comment (buffer-size))'. `(buffer-size)' is a good argument
187 to use, because the number of comments in the buffer cannot exceed that
191 File: lispref.info, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables
193 Some Standard Syntax Tables
194 ===========================
196 Most of the major modes in XEmacs have their own syntax tables. Here
199 - Function: standard-syntax-table
200 This function returns the standard syntax table, which is the
201 syntax table used in Fundamental mode.
203 - Variable: text-mode-syntax-table
204 The value of this variable is the syntax table used in Text mode.
206 - Variable: c-mode-syntax-table
207 The value of this variable is the syntax table for C-mode buffers.
209 - Variable: emacs-lisp-mode-syntax-table
210 The value of this variable is the syntax table used in Emacs Lisp
211 mode by editing commands. (It has no effect on the Lisp `read'
215 File: lispref.info, Node: Syntax Table Internals, Prev: Standard Syntax Tables, Up: Syntax Tables
217 Syntax Table Internals
218 ======================
220 Each element of a syntax table is an integer that encodes the syntax
221 of one character: the syntax class, possible matching character, and
222 flags. Lisp programs don't usually work with the elements directly; the
223 Lisp-level syntax table functions usually work with syntax descriptors
224 (*note Syntax Descriptors::).
226 The low 8 bits of each element of a syntax table indicate the syntax
274 The next 8 bits are the matching opposite parenthesis (if the
275 character has parenthesis syntax); otherwise, they are not meaningful.
276 The next 6 bits are the flags.
279 File: lispref.info, Node: Abbrevs, Next: Extents, Prev: Syntax Tables, Up: Top
281 Abbrevs And Abbrev Expansion
282 ****************************
284 An abbreviation or "abbrev" is a string of characters that may be
285 expanded to a longer string. The user can insert the abbrev string and
286 find it replaced automatically with the expansion of the abbrev. This
289 The set of abbrevs currently in effect is recorded in an "abbrev
290 table". Each buffer has a local abbrev table, but normally all buffers
291 in the same major mode share one abbrev table. There is also a global
292 abbrev table. Normally both are used.
294 An abbrev table is represented as an obarray containing a symbol for
295 each abbreviation. The symbol's name is the abbreviation; its value is
296 the expansion; its function definition is the hook function to do the
297 expansion (*note Defining Abbrevs::); its property list cell contains
298 the use count, the number of times the abbreviation has been expanded.
299 Because these symbols are not interned in the usual obarray, they will
300 never appear as the result of reading a Lisp expression; in fact,
301 normally they are never used except by the code that handles abbrevs.
302 Therefore, it is safe to use them in an extremely nonstandard way.
303 *Note Creating Symbols::.
305 For the user-level commands for abbrevs, see *Note Abbrev Mode:
310 * Abbrev Mode:: Setting up XEmacs for abbreviation.
311 * Tables: Abbrev Tables. Creating and working with abbrev tables.
312 * Defining Abbrevs:: Specifying abbreviations and their expansions.
313 * Files: Abbrev Files. Saving abbrevs in files.
314 * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
315 * Standard Abbrev Tables:: Abbrev tables used by various major modes.
318 File: lispref.info, Node: Abbrev Mode, Next: Abbrev Tables, Up: Abbrevs
320 Setting Up Abbrev Mode
321 ======================
323 Abbrev mode is a minor mode controlled by the value of the variable
326 - Variable: abbrev-mode
327 A non-`nil' value of this variable turns on the automatic expansion
328 of abbrevs when their abbreviations are inserted into a buffer.
329 If the value is `nil', abbrevs may be defined, but they are not
330 expanded automatically.
332 This variable automatically becomes local when set in any fashion.
334 - Variable: default-abbrev-mode
335 This is the value of `abbrev-mode' for buffers that do not
336 override it. This is the same as `(default-value 'abbrev-mode)'.
339 File: lispref.info, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs
344 This section describes how to create and manipulate abbrev tables.
346 - Function: make-abbrev-table
347 This function creates and returns a new, empty abbrev table--an
348 obarray containing no symbols. It is a vector filled with zeros.
350 - Function: clear-abbrev-table table
351 This function undefines all the abbrevs in abbrev table TABLE,
352 leaving it empty. The function returns `nil'.
354 - Function: define-abbrev-table tabname definitions
355 This function defines TABNAME (a symbol) as an abbrev table name,
356 i.e., as a variable whose value is an abbrev table. It defines
357 abbrevs in the table according to DEFINITIONS, a list of elements
358 of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'. The value is
361 - Variable: abbrev-table-name-list
362 This is a list of symbols whose values are abbrev tables.
363 `define-abbrev-table' adds the new abbrev table name to this list.
365 - Function: insert-abbrev-table-description name &optional human
366 This function inserts before point a description of the abbrev
367 table named NAME. The argument NAME is a symbol whose value is an
368 abbrev table. The value is always `nil'.
370 If HUMAN is non-`nil', the description is human-oriented.
371 Otherwise the description is a Lisp expression--a call to
372 `define-abbrev-table' that would define NAME exactly as it is
376 File: lispref.info, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs
381 These functions define an abbrev in a specified abbrev table.
382 `define-abbrev' is the low-level basic function, while `add-abbrev' is
383 used by commands that ask for information from the user.
385 - Function: add-abbrev table type arg
386 This function adds an abbreviation to abbrev table TABLE based on
387 information from the user. The argument TYPE is a string
388 describing in English the kind of abbrev this will be (typically,
389 `"global"' or `"mode-specific"'); this is used in prompting the
390 user. The argument ARG is the number of words in the expansion.
392 The return value is the symbol that internally represents the new
393 abbrev, or `nil' if the user declines to confirm redefining an
396 - Function: define-abbrev table name expansion hook
397 This function defines an abbrev in TABLE named NAME, to expand to
398 EXPANSION, and call HOOK. The return value is an uninterned
399 symbol that represents the abbrev inside XEmacs; its name is NAME.
401 The argument NAME should be a string. The argument EXPANSION
402 should be a string, or `nil' to undefine the abbrev.
404 The argument HOOK is a function or `nil'. If HOOK is non-`nil',
405 then it is called with no arguments after the abbrev is replaced
406 with EXPANSION; point is located at the end of EXPANSION when HOOK
409 The use count of the abbrev is initialized to zero.
411 - User Option: only-global-abbrevs
412 If this variable is non-`nil', it means that the user plans to use
413 global abbrevs only. This tells the commands that define
414 mode-specific abbrevs to define global ones instead. This
415 variable does not alter the behavior of the functions in this
416 section; it is examined by their callers.
419 File: lispref.info, Node: Abbrev Files, Next: Abbrev Expansion, Prev: Defining Abbrevs, Up: Abbrevs
421 Saving Abbrevs in Files
422 =======================
424 A file of saved abbrev definitions is actually a file of Lisp code.
425 The abbrevs are saved in the form of a Lisp program to define the same
426 abbrev tables with the same contents. Therefore, you can load the file
427 with `load' (*note How Programs Do Loading::). However, the function
428 `quietly-read-abbrev-file' is provided as a more convenient interface.
430 User-level facilities such as `save-some-buffers' can save abbrevs
431 in a file automatically, under the control of variables described here.
433 - User Option: abbrev-file-name
434 This is the default file name for reading and saving abbrevs.
436 - Function: quietly-read-abbrev-file filename
437 This function reads abbrev definitions from a file named FILENAME,
438 previously written with `write-abbrev-file'. If FILENAME is
439 `nil', the file specified in `abbrev-file-name' is used.
440 `save-abbrevs' is set to `t' so that changes will be saved.
442 This function does not display any messages. It returns `nil'.
444 - User Option: save-abbrevs
445 A non-`nil' value for `save-abbrev' means that XEmacs should save
446 abbrevs when files are saved. `abbrev-file-name' specifies the
447 file to save the abbrevs in.
449 - Variable: abbrevs-changed
450 This variable is set non-`nil' by defining or altering any
451 abbrevs. This serves as a flag for various XEmacs commands to
452 offer to save your abbrevs.
454 - Command: write-abbrev-file filename
455 Save all abbrev definitions, in all abbrev tables, in the file
456 FILENAME, in the form of a Lisp program that when loaded will
457 define the same abbrevs. This function returns `nil'.
460 File: lispref.info, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs
462 Looking Up and Expanding Abbreviations
463 ======================================
465 Abbrevs are usually expanded by commands for interactive use,
466 including `self-insert-command'. This section describes the
467 subroutines used in writing such functions, as well as the variables
468 they use for communication.
470 - Function: abbrev-symbol abbrev &optional table
471 This function returns the symbol representing the abbrev named
472 ABBREV. The value returned is `nil' if that abbrev is not
473 defined. The optional second argument TABLE is the abbrev table
474 to look it up in. If TABLE is `nil', this function tries first
475 the current buffer's local abbrev table, and second the global
478 - Function: abbrev-expansion abbrev &optional table
479 This function returns the string that ABBREV would expand into (as
480 defined by the abbrev tables used for the current buffer). The
481 optional argument TABLE specifies the abbrev table to use, as in
484 - Command: expand-abbrev
485 This command expands the abbrev before point, if any. If point
486 does not follow an abbrev, this command does nothing. The command
487 returns `t' if it did expansion, `nil' otherwise.
489 - Command: abbrev-prefix-mark &optional arg
490 Mark current point as the beginning of an abbrev. The next call to
491 `expand-abbrev' will use the text from here to point (where it is
492 then) as the abbrev to expand, rather than using the previous word
495 - User Option: abbrev-all-caps
496 When this is set non-`nil', an abbrev entered entirely in upper
497 case is expanded using all upper case. Otherwise, an abbrev
498 entered entirely in upper case is expanded by capitalizing each
499 word of the expansion.
501 - Variable: abbrev-start-location
502 This is the buffer position for `expand-abbrev' to use as the start
503 of the next abbrev to be expanded. (`nil' means use the word
504 before point instead.) `abbrev-start-location' is set to `nil'
505 each time `expand-abbrev' is called. This variable is also set by
506 `abbrev-prefix-mark'.
508 - Variable: abbrev-start-location-buffer
509 The value of this variable is the buffer for which
510 `abbrev-start-location' has been set. Trying to expand an abbrev
511 in any other buffer clears `abbrev-start-location'. This variable
512 is set by `abbrev-prefix-mark'.
514 - Variable: last-abbrev
515 This is the `abbrev-symbol' of the last abbrev expanded. This
516 information is left by `expand-abbrev' for the sake of the
517 `unexpand-abbrev' command.
519 - Variable: last-abbrev-location
520 This is the location of the last abbrev expanded. This contains
521 information left by `expand-abbrev' for the sake of the
522 `unexpand-abbrev' command.
524 - Variable: last-abbrev-text
525 This is the exact expansion text of the last abbrev expanded,
526 after case conversion (if any). Its value is `nil' if the abbrev
527 has already been unexpanded. This contains information left by
528 `expand-abbrev' for the sake of the `unexpand-abbrev' command.
530 - Variable: pre-abbrev-expand-hook
531 This is a normal hook whose functions are executed, in sequence,
532 just before any expansion of an abbrev. *Note Hooks::. Since it
533 is a normal hook, the hook functions receive no arguments.
534 However, they can find the abbrev to be expanded by looking in the
537 The following sample code shows a simple use of
538 `pre-abbrev-expand-hook'. If the user terminates an abbrev with a
539 punctuation character, the hook function asks for confirmation. Thus,
540 this hook allows the user to decide whether to expand the abbrev, and
541 aborts expansion if it is not confirmed.
543 (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
545 ;; This is the function invoked by `pre-abbrev-expand-hook'.
547 ;; If the user terminated the abbrev with a space, the function does
548 ;; nothing (that is, it returns so that the abbrev can expand). If the
549 ;; user entered some other character, this function asks whether
550 ;; expansion should continue.
552 ;; If the user answers the prompt with `y', the function returns
553 ;; `nil' (because of the `not' function), but that is
554 ;; acceptable; the return value has no effect on expansion.
556 (defun query-if-not-space ()
557 (if (/= ?\ (preceding-char))
558 (if (not (y-or-n-p "Do you want to expand this abbrev? "))
559 (error "Not expanding this abbrev"))))
562 File: lispref.info, Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbrevs
564 Standard Abbrev Tables
565 ======================
567 Here we list the variables that hold the abbrev tables for the
568 preloaded major modes of XEmacs.
570 - Variable: global-abbrev-table
571 This is the abbrev table for mode-independent abbrevs. The abbrevs
572 defined in it apply to all buffers. Each buffer may also have a
573 local abbrev table, whose abbrev definitions take precedence over
574 those in the global table.
576 - Variable: local-abbrev-table
577 The value of this buffer-local variable is the (mode-specific)
578 abbreviation table of the current buffer.
580 - Variable: fundamental-mode-abbrev-table
581 This is the local abbrev table used in Fundamental mode; in other
582 words, it is the local abbrev table in all buffers in Fundamental
585 - Variable: text-mode-abbrev-table
586 This is the local abbrev table used in Text mode.
588 - Variable: c-mode-abbrev-table
589 This is the local abbrev table used in C mode.
591 - Variable: lisp-mode-abbrev-table
592 This is the local abbrev table used in Lisp mode and Emacs Lisp
596 File: lispref.info, Node: Extents, Next: Specifiers, Prev: Abbrevs, Up: Top
601 An "extent" is a region of text (a start position and an end
602 position) that is displayed in a particular face and can have certain
603 other properties such as being read-only. Extents can overlap each
604 other. XEmacs efficiently handles buffers with large numbers of
607 - Function: extentp object
608 This returns `t' if OBJECT is an extent.
612 * Intro to Extents:: Extents are regions over a buffer or string.
613 * Creating and Modifying Extents::
614 Basic extent functions.
615 * Extent Endpoints:: Accessing and setting the bounds of an extent.
616 * Finding Extents:: Determining which extents are in an object.
617 * Mapping Over Extents:: More sophisticated functions for extent scanning.
618 * Extent Properties:: Extents have built-in and user-definable properties.
619 * Detached Extents:: Extents that are not in a buffer.
620 * Extent Parents:: Inheriting properties from another extent.
621 * Duplicable Extents:: Extents can be marked to be copied into strings.
622 * Extents and Events:: Extents can interact with the keyboard and mouse.
623 * Atomic Extents:: Treating a block of text as a single entity.
626 File: lispref.info, Node: Intro to Extents, Next: Creating and Modifying Extents, Up: Extents
628 Introduction to Extents
629 =======================
631 An extent is a region of text within a buffer or string that has
632 certain properties associated with it. The properties of an extent
633 primarily affect the way the text contained in the extent is displayed.
634 Extents can freely overlap each other in a buffer or string. Extents
635 are invisible to functions that merely examine the text of a buffer or
638 _Please note:_ An alternative way to add properties to a buffer or
639 string is to use text properties. *Note Text Properties::.
641 An extent is logically a Lisp object consisting of a start position,
642 an end position, a buffer or string to which these positions refer, and
643 a property list. As text is inserted into a buffer, the start and end
644 positions of the extent are automatically adjusted as necessary to keep
645 the extent referring to the same text in the buffer. If text is
646 inserted at the boundary of an extent, the extent's `start-open' and
647 `end-open' properties control whether the text is included as part of
648 the extent. If the text bounded by an extent is deleted, the extent
649 becomes "detached"; its start and end positions are no longer
650 meaningful, but it maintains all its other properties and can later be
651 reinserted into a buffer. (None of these considerations apply to
652 strings, because text cannot be inserted into or deleted from a string.)
654 Each extent has a face or list of faces associated with it, which
655 controls the way in which the text bounded by the extent is displayed.
656 If an extent's face is `nil' or its properties are partially undefined,
657 the corresponding properties from the default face for the frame is
658 used. If two or more extents overlap, or if a list of more than one
659 face is specified for a particular extent, the corresponding faces are
660 merged to determine the text's displayed properties. Every extent has
661 a "priority" that determines which face takes precedence if the faces
662 conflict. (If two extents have the same priority, the one that comes
663 later in the display order takes precedence. *Note display order:
664 Extent Endpoints.) Higher-numbered priority values correspond to a
665 higher priority, and priority values can be negative. Every extent is
666 created with a priority of 0, but this can be changed with
667 `set-extent-priority'. Within a single extent with a list of faces,
668 faces earlier in the list have a higher priority than faces later in
671 Extents can be set to respond specially to key and mouse events
672 within the extent. An extent's `keymap' property controls the effect of
673 key and mouse strokes within the extent's text, and the `mouse-face'
674 property controls whether the extent is highlighted when the mouse moves
675 over it. *Note Extents and Events::.
677 An extent can optionally have a "begin-glyph" or "end-glyph"
678 associated with it. A begin-glyph or end-glyph is a pixmap or string
679 that will be displayed either at the start or end of an extent or in the
680 margin of the line that the start or end of the extent lies in,
681 depending on the extent's layout policy. Begin-glyphs and end-glyphs
682 are used to implement annotations, and you should use the annotation API
683 functions in preference to the lower-level extent functions. For more
684 information, *Note Annotations::.
686 If an extent has its `detachable' property set, it will become
687 "detached" (i.e. no longer in the buffer) when all its text is deleted.
688 Otherwise, it will simply shrink down to zero-length and sit in the
689 same place in the buffer. By default, the `detachable' property is set
690 on newly-created extents. *Note Detached Extents::.
692 If an extent has its `duplicable' property set, it will be
693 remembered when a string is created from text bounded by the extent.
694 When the string is re-inserted into a buffer, the extent will also be
695 re-inserted. This mechanism is used in the kill, yank, and undo
696 commands. *Note Duplicable Extents::.
699 File: lispref.info, Node: Creating and Modifying Extents, Next: Extent Endpoints, Prev: Intro to Extents, Up: Extents
701 Creating and Modifying Extents
702 ==============================
704 - Function: make-extent from to &optional object
705 This function makes an extent for the range [FROM, TO) in OBJECT
706 (a buffer or string). OBJECT defaults to the current buffer.
707 Insertions at point TO will be outside of the extent; insertions
708 at FROM will be inside the extent, causing the extent to grow
709 (*note Extent Endpoints::). This is the same way that markers
710 behave. The extent is initially detached if both FROM and TO are
711 `nil', and in this case OBJECT defaults to `nil', meaning the
712 extent is in no buffer or string (*note Detached Extents::).
714 - Function: delete-extent extent
715 This function removes EXTENT from its buffer and destroys it.
716 This does not modify the buffer's text, only its display
717 properties. The extent cannot be used thereafter. To remove an
718 extent in such a way that it can be re-inserted later, use
719 `detach-extent'. *Note Detached Extents::.
721 - Function: extent-object extent
722 This function returns the buffer or string that EXTENT is in. If
723 the return value is `nil', this means that the extent is detached;
724 however, a detached extent will not necessarily return a value of
727 - Function: extent-live-p extent
728 This function returns `nil' if EXTENT is deleted, and `t'
732 File: lispref.info, Node: Extent Endpoints, Next: Finding Extents, Prev: Creating and Modifying Extents, Up: Extents
737 Every extent has a start position and an end position, and logically
738 affects the characters between those positions. Normally the start and
739 end positions must both be valid positions in the extent's buffer or
740 string. However, both endpoints can be `nil', meaning the extent is
741 detached. *Note Detached Extents::.
743 Whether the extent overlaps its endpoints is governed by its
744 `start-open' and `end-open' properties. Insertion of a character at a
745 closed endpoint will expand the extent to include that character;
746 insertion at an open endpoint will not. Similarly, functions such as
747 `extent-at' that scan over all extents overlapping a particular
748 position will include extents with a closed endpoint at that position,
749 but not extents with an open endpoint.
751 Note that the `start-closed' and `end-closed' properties are
752 equivalent to `start-open' and `end-open' with the opposite sense.
754 Both endpoints can be equal, in which case the extent includes no
755 characters but still exists in the buffer or string. Zero-length
756 extents are used to represent annotations (*note Annotations::) and can
757 be used as a more powerful form of a marker. Deletion of all the
758 characters in an extent may or may not result in a zero-length extent;
759 this depends on the `detachable' property (*note Detached Extents::).
760 Insertion at the position of a zero-length extent expands the extent if
761 both endpoints are closed; goes before the extent if it has the
762 `start-open' property; and goes after the extent if it has the
763 `end-open' property. Zero-length extents with both the `start-open'
764 and `end-open' properties are treated as if their starting point were
765 closed. Deletion of a character on a side of a zero-length extent
766 whose corresponding endpoint is closed causes the extent to be detached
767 if its `detachable' property is set; if the corresponding endpoint is
768 open, the extent remains in the buffer, moving as necessary.
770 Extents are ordered within a buffer or string by increasing start
771 position, and then by decreasing end position (this is called the
774 - Function: extent-start-position extent
775 This function returns the start position of EXTENT.
777 - Function: extent-end-position extent
778 This function returns the end position of EXTENT.
780 - Function: extent-length extent
781 This function returns the length of EXTENT in characters. If the
782 extent is detached, this returns `0'. If the extent is not
783 detached, this is equivalent to
784 (- (extent-end-position EXTENT) (extent-start-position EXTENT))
786 - Function: set-extent-endpoints extent start end &optional
788 This function sets the start and end position of EXTENT to START
789 and END. If both are `nil', this is equivalent to `detach-extent'.
791 BUFFER-OR-STRING specifies the new buffer or string that the
792 extent should be in, and defaults to EXTENT's buffer or string.
793 (If `nil', and EXTENT is in no buffer and no string, it defaults
794 to the current buffer.)
796 See documentation on `detach-extent' for a discussion of undo
800 File: lispref.info, Node: Finding Extents, Next: Mapping Over Extents, Prev: Extent Endpoints, Up: Extents
805 The following functions provide a simple way of determining the
806 extents in a buffer or string. A number of more sophisticated
807 primitives for mapping over the extents in a range of a buffer or string
808 are also provided (*note Mapping Over Extents::). When reading through
809 this section, keep in mind the way that extents are ordered (*note
812 - Function: extent-list &optional buffer-or-string from to flags
813 This function returns a list of the extents in BUFFER-OR-STRING.
814 BUFFER-OR-STRING defaults to the current buffer if omitted. FROM
815 and TO can be used to limit the range over which extents are
816 returned; if omitted, all extents in the buffer or string are
819 More specifically, if a range is specified using FROM and TO, only
820 extents that overlap the range (i.e. begin or end inside of the
821 range) are included in the list. FROM and TO default to the
822 beginning and end of BUFFER-OR-STRING, respectively.
824 FLAGS controls how end cases are treated. For a discussion of
825 this, and exactly what "overlap" means, see `map-extents'.
827 Functions that create extents must be prepared for the possibility
828 that there are other extents in the same area, created by other
829 functions. To deal with this, functions typically mark their own
830 extents by setting a particular property on them. The following
831 function makes it easier to locate those extents.
833 - Function: extent-at pos &optional object property before at-flag
834 This function finds the "smallest" extent (i.e., the last one in
835 the display order) at (i.e., overlapping) POS in OBJECT (a buffer
836 or string) having PROPERTY set. OBJECT defaults to the current
837 buffer. PROPERTY defaults to `nil', meaning that any extent will
838 do. Returns `nil' if there is no matching extent at POS. If the
839 fourth argument BEFORE is not `nil', it must be an extent; any
840 returned extent will precede that extent. This feature allows
841 `extent-at' to be used by a loop over extents.
843 AT-FLAG controls how end cases are handled (i.e. what "at" really
844 means), and should be one of:
849 An extent is at POS if it covers the character after POS.
850 This is consistent with the way that text properties work.
853 An extent is at POS if it covers the character before POS.
856 An extent is at POS if it overlaps or abuts POS. This
857 includes all zero-length extents at POS.
859 Note that in all cases, the start-openness and end-openness of the
860 extents considered is ignored. If you want to pay attention to
861 those properties, you should use `map-extents', which gives you
864 The following low-level functions are provided for explicitly
865 traversing the extents in a buffer according to the display order.
866 These functions are mostly intended for debugging--in normal operation,
867 you should probably use `mapcar-extents' or `map-extents', or loop
868 using the BEFORE argument to `extent-at', rather than creating a loop
871 - Function: next-extent extent
872 Given an extent EXTENT, this function returns the next extent in
873 the buffer or string's display order. If EXTENT is a buffer or
874 string, this returns the first extent in the buffer or string.
876 - Function: previous-extent extent
877 Given an extent EXTENT, this function returns the previous extent
878 in the buffer or string's display order. If EXTENT is a buffer or
879 string, this returns the last extent in the buffer or string.
882 File: lispref.info, Node: Mapping Over Extents, Next: Extent Properties, Prev: Finding Extents, Up: Extents
887 The most basic and general function for mapping over extents is
888 called `map-extents'. You should read through the definition of this
889 function to familiarize yourself with the concepts and optional
890 arguments involved. However, in practice you may find it more
891 convenient to use the function `mapcar-extents' or to create a loop
892 using the `before' argument to `extent-at' (*note Finding Extents::).
894 - Function: map-extents function &optional object from to maparg flags
896 This function maps FUNCTION over the extents which overlap a
897 region in OBJECT. OBJECT is normally a buffer or string but could
898 be an extent (see below). The region is normally bounded by
899 [FROM, TO) (i.e. the beginning of the region is closed and the end
900 of the region is open), but this can be changed with the FLAGS
901 argument (see below for a complete discussion).
903 FUNCTION is called with the arguments (extent, MAPARG). The
904 arguments OBJECT, FROM, TO, MAPARG, and FLAGS are all optional and
905 default to the current buffer, the beginning of OBJECT, the end of
906 OBJECT, NIL, and NIL, respectively. `map-extents' returns the
907 first non-`nil' result produced by FUNCTION, and no more calls to
908 FUNCTION are made after it returns non-`nil'.
910 If OBJECT is an extent, FROM and TO default to the extent's
911 endpoints, and the mapping omits that extent and its predecessors.
912 This feature supports restarting a loop based on `map-extents'.
913 Note: OBJECT must be attached to a buffer or string, and the
914 mapping is done over that buffer or string.
916 An extent overlaps the region if there is any point in the extent
917 that is also in the region. (For the purpose of overlap,
918 zero-length extents and regions are treated as closed on both ends
919 regardless of their endpoints' specified open/closedness.) Note
920 that the endpoints of an extent or region are considered to be in
921 that extent or region if and only if the corresponding end is
922 closed. For example, the extent [5,7] overlaps the region [2,5]
923 because 5 is in both the extent and the region. However, (5,7]
924 does not overlap [2,5] because 5 is not in the extent, and neither
925 [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the
928 The optional FLAGS can be a symbol or a list of one or more
929 symbols, modifying the behavior of `map-extents'. Allowed symbols
933 The region's end is closed.
936 The region's start is open.
939 Treat all extents as closed on both ends for the purpose of
940 determining whether they overlap the region, irrespective of
941 their actual open- or closedness.
944 Treat all extents as open on both ends.
946 `all-extents-closed-open'
947 Treat all extents as start-closed, end-open.
949 `all-extents-open-closed'
950 Treat all extents as start-open, end-closed.
953 In addition to the above conditions for extent overlap, the
954 extent's start position must lie within the specified region.
955 Note that, for this condition, open start positions are
956 treated as if 0.5 was added to the endpoint's value, and open
957 end positions are treated as if 0.5 was subtracted from the
961 The extent's end position must lie within the region.
963 `start-and-end-in-region'
964 Both the extent's start and end positions must lie within the
967 `start-or-end-in-region'
968 Either the extent's start or end position must lie within the
972 The condition specified by a `*-in-region' flag must _not_
973 hold for the extent to be considered.
975 At most one of `all-extents-closed', `all-extents-open',
976 `all-extents-closed-open', and `all-extents-open-closed' may be
979 At most one of `start-in-region', `end-in-region',
980 `start-and-end-in-region', and `start-or-end-in-region' may be
983 If optional arg PROPERTY is non-`nil', only extents with that
984 property set on them will be visited. If optional arg VALUE is
985 non-`nil', only extents whose value for that property is `eq' to
986 VALUE will be visited.
988 If you want to map over extents and accumulate a list of results,
989 the following function may be more convenient than `map-extents'.
991 - Function: mapcar-extents function &optional predicate
992 buffer-or-string from to flags property value
993 This function applies FUNCTION to all extents which overlap a
994 region in BUFFER-OR-STRING. The region is delimited by FROM and
995 TO. FUNCTION is called with one argument, the extent. A list of
996 the values returned by FUNCTION is returned. An optional
997 PREDICATE may be used to further limit the extents over which
998 FUNCTION is mapped. The optional arguments FLAGS, PROPERTY, and
999 VALUE may also be used to control the extents passed to PREDICATE
1000 or FUNCTION, and have the same meaning as in `map-extents'.
1002 - Function: map-extent-children function &optional object from to
1003 maparg flags property value
1004 This function is similar to `map-extents', but differs in that:
1006 * It only visits extents which start in the given region.
1008 * After visiting an extent E, it skips all other extents which
1009 start inside E but end before E's end.
1011 Thus, this function may be used to walk a tree of extents in a
1013 (defun walk-extents (buffer &optional ignore)
1014 (map-extent-children 'walk-extents buffer))
1016 - Function: extent-in-region-p extent &optional from to flags
1017 This function returns T if `map-extents' would visit EXTENT if
1018 called with the given arguments.
projects / chise / xemacs-chise.git / blob