Mercurial > hg > xemacs-beta
annotate man/lispref/extents.texi @ 5353:38e24b8be4ea
Improve the lexical scoping in #'block, #'return-from.
lisp/ChangeLog addition:
2011-02-07 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el:
* bytecomp.el (byte-compile-initial-macro-environment):
Shadow `block', `return-from' here, we implement them differently
when byte-compiling.
* bytecomp.el (byte-compile-active-blocks): New.
* bytecomp.el (byte-compile-block-1): New.
* bytecomp.el (byte-compile-return-from-1): New.
* bytecomp.el (return-from-1): New.
* bytecomp.el (block-1): New.
These are two aliases that exist to have their own associated
byte-compile functions, which functions implement `block' and
`return-from'.
* cl-extra.el (cl-macroexpand-all):
Fix a bug here when macros in the environment have been compiled.
* cl-macs.el (block):
* cl-macs.el (return):
* cl-macs.el (return-from):
Be more careful about lexical scope in these macros.
* cl.el:
* cl.el ('cl-block-wrapper): Removed.
* cl.el ('cl-block-throw): Removed.
These aren't needed in code generated by this XEmacs. They
shouldn't be needed in code generated by XEmacs 21.4, but if it
turns out the packages do need them, we can put them back.
2011-01-30 Mike Sperber <mike@xemacs.org>
* font-lock.el (font-lock-fontify-pending-extents): Don't fail if
`font-lock-mode' is unset, which can happen in the middle of
`revert-buffer'.
2011-01-23 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (delete):
* cl-macs.el (delq):
* cl-macs.el (remove):
* cl-macs.el (remq):
Don't use the compiler macro if these functions were given the
wrong number of arguments, as happens in lisp-tests.el.
* cl-seq.el (remove, remq): Removed.
I added these to subr.el, and forgot to remove them from here.
2011-01-22 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-setq, byte-compile-set):
Remove kludge allowing keywords' values to be set, all the code
that does that is gone.
* cl-compat.el (elt-satisfies-test-p):
* faces.el (set-face-parent):
* faces.el (face-doc-string):
* gtk-font-menu.el:
* gtk-font-menu.el (gtk-reset-device-font-menus):
* msw-font-menu.el:
* msw-font-menu.el (mswindows-reset-device-font-menus):
* package-get.el (package-get-installedp):
* select.el (select-convert-from-image-data):
* sound.el:
* sound.el (load-sound-file):
* x-font-menu.el (x-reset-device-font-menus-core):
Don't quote keywords, they're self-quoting, and the
win from backward-compatibility is sufficiently small now that the
style problem overrides it.
2011-01-22 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (block, return-from): Require that NAME be a symbol
in these macros, as always documented in the #'block docstring and
as required by Common Lisp.
* descr-text.el (unidata-initialize-unihan-database):
Correct the use of non-symbols in #'block and #'return-from in
this function.
2011-01-15 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (concatenate): Accept more complicated TYPEs in this
function, handing the sequences over to #'coerce if we don't
understand them here.
* cl-macs.el (inline): Don't proclaim #'concatenate as inline, its
compiler macro is more useful than doing that.
2011-01-11 Aidan Kehoe <kehoea@parhasard.net>
* subr.el (delete, delq, remove, remq): Move #'remove, #'remq
here, they don't belong in cl-seq.el; move #'delete, #'delq here
from fns.c, implement them in terms of #'delete*, allowing support
for sequences generally.
* update-elc.el (do-autoload-commands): Use #'delete*, not #'delq
here, now the latter's no longer dumped.
* cl-macs.el (delete, delq): Add compiler macros transforming
#'delete and #'delq to #'delete* calls.
2011-01-10 Aidan Kehoe <kehoea@parhasard.net>
* dialog.el (make-dialog-box): Correct a misplaced parenthesis
here, thank you Mats Lidell in 87zkr9gqrh.fsf@mail.contactor.se !
2011-01-02 Aidan Kehoe <kehoea@parhasard.net>
* dialog.el (make-dialog-box):
* list-mode.el (display-completion-list):
These functions used to use cl-parsing-keywords; change them to
use defun* instead, fixing the build. (Not sure what led to me
not including this change in d1b17a33450b!)
2011-01-02 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (define-star-compiler-macros):
Make sure the form has ITEM and LIST specified before attempting
to change to calls with explicit tests; necessary for some tests
in lisp-tests.el to compile correctly.
(stable-union, stable-intersection): Add compiler macros for these
functions, in the same way we do for most of the other functions
in cl-seq.el.
2011-01-01 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (dolist, dotimes, do-symbols, macrolet)
(symbol-macrolet):
Define these macros with defmacro* instead of parsing the argument
list by hand, for the sake of style and readability; use backquote
where appropriate, instead of calling #'list and and friends, for
the same reason.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* x-misc.el (device-x-display):
Provide this function, documented in the Lispref for years, but
not existing previously. Thank you Julian Bradfield, thank you
Jeff Mincy.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* cl-seq.el:
Move the heavy lifting from this file to C. Dump the
cl-parsing-keywords macro, but don't use defun* for the functions
we define that do take keywords, dynamic scope lossage makes that
not practical.
* subr.el (sort, fillarray): Move these aliases here.
(map-plist): #'nsublis is now built-in, but at this point #'eql
isn't necessarily available as a test; use #'eq.
* obsolete.el (cl-delete-duplicates): Make this available for old
compiler macros and old code.
(memql): Document that this is equivalent to #'member*, and worse.
* cl.el (adjoin, subst): Removed. These are in C.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* simple.el (assoc-ignore-case): Remove a duplicate definition of
this function (it's already in subr.el).
* iso8859-1.el (char-width):
On non-Mule, make this function equivalent to that produced by
(constantly 1), but preserve its docstring.
* subr.el (subst-char-in-string): Define this in terms of
#'substitute, #'nsubstitute.
(string-width): Define this using #'reduce and #'char-width.
(char-width): Give this a simpler definition, it makes far more
sense to check for mule at load time and redefine, as we do in
iso8859-1.el.
(store-substring): Implement this in terms of #'replace, now
#'replace is cheap.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* update-elc.el (lisp-files-needed-for-byte-compilation)
(lisp-files-needing-early-byte-compilation):
cl-macs belongs in the former, not the latter, it is as
fundamental as bytecomp.el.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* cl.el:
Provde the Common Lisp program-error, type-error as error
symbols. This doesn't nearly go far enough for anyone using the
Common Lisp errors.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (delete-duplicates):
If the form has an incorrect number of arguments, don't attempt a
compiler macroexpansion.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (cl-safe-expr-p):
Forms that start with the symbol lambda are also safe.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (= < > <= >=):
For these functions' compiler macros, the optimisation is safe
even if the first and the last arguments have side effects, since
they're only used the once.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (inline-side-effect-free-compiler-macros):
Unroll a loop here at macro-expansion time, so these compiler
macros are compiled. Use #'eql instead of #'eq in a couple of
places for better style.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (notany, notevery): Avoid some dynamic scope
stupidity with local variable names in these functions, when they
weren't prefixed with cl-; go into some more detail in the doc
strings.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (side-effect-free-fns): #'remove, #'remq are
free of side-effects.
(side-effect-and-error-free-fns):
Drop dot, dot-marker from the list.
2010-11-17 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (coerce):
In the argument list, name the first argument OBJECT, not X; the
former name was always used in the doc string and is clearer.
Handle vector type specifications which include the length of the
target sequence, error if there's a mismatch.
* cl-macs.el (cl-make-type-test): Handle type specifications
starting with the symbol 'eql.
2010-11-14 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (eql): Don't remove the byte-compile property of this
symbol. That was necessary to override a bug in bytecomp.el where
#'eql was confused with #'eq, which bug we no longer have.
If neither expression is constant, don't attempt to handle the
expression in this compiler macro, leave it to byte-compile-eql,
which produces better code anyway.
* bytecomp.el (eq): #'eql is not the function associated with the
byte-eq byte code.
(byte-compile-eql): Add an explicit compile method for this
function, for cases where the cl-macs compiler macro hasn't
reduced it to #'eq or #'equal.
2010-10-25 Aidan Kehoe <kehoea@parhasard.net>
Add compiler macros and compilation sanity-checking for various
functions that take keywords.
* byte-optimize.el (side-effect-free-fns): #'symbol-value is
side-effect free and not error free.
* bytecomp.el (byte-compile-normal-call): Check keyword argument
lists for sanity; store information about the positions where
keyword arguments start using the new byte-compile-keyword-start
property.
* cl-macs.el (cl-const-expr-val): Take a new optional argument,
cl-not-constant, defaulting to nil, in this function; return it if
the expression is not constant.
(cl-non-fixnum-number-p): Make this into a separate function, we
want to pass it to #'every.
(eql): Use it.
(define-star-compiler-macros): Use the same code to generate the
member*, assoc* and rassoc* compiler macros; special-case some
code in #'add-to-list in subr.el.
(remove, remq): Add compiler macros for these two functions, in
preparation for #'remove being in C.
(define-foo-if-compiler-macros): Transform (remove-if-not ...) calls to
(remove ... :if-not) at compile time, which will be a real win
once the latter is in C.
(define-substitute-if-compiler-macros)
(define-subst-if-compiler-macros): Similarly for these functions.
(delete-duplicates): Change this compiler macro to use
#'plists-equal; if we don't have information about the type of
SEQUENCE at compile time, don't bother attempting to inline the
call, the function will be in C soon enough.
(equalp): Remove an old commented-out compiler macro for this, if
we want to see it it's in version control.
(subst-char-in-string): Transform this to a call to nsubstitute or
nsubstitute, if that is appropriate.
* cl.el (ldiff): Don't call setf here, this makes for a load-time
dependency problem in cl-macs.el
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* term/vt100.el:
Refer to XEmacs, not GNU Emacs, in permissions.
* term/bg-mouse.el:
* term/sup-mouse.el:
Put copyright notice in canonical "Copyright DATE AUTHOR" form.
Refer to XEmacs, not GNU Emacs, in permissions.
* site-load.el:
Add permission boilerplate.
* mule/canna-leim.el:
* alist.el:
Refer to XEmacs, not APEL/this program, in permissions.
* mule/canna-leim.el:
Remove my copyright, I've assigned it to the FSF.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* gtk.el:
* gtk-widget-accessors.el:
* gtk-package.el:
* gtk-marshal.el:
* gtk-compose.el:
* gnome.el:
Add copyright notice based on internal evidence.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* easymenu.el: Add reference to COPYING to permission notice.
* gutter.el:
* gutter-items.el:
* menubar-items.el:
Fix typo "Xmacs" in permissions notice.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* auto-save.el:
* font.el:
* fontconfig.el:
* mule/kinsoku.el:
Add "part of XEmacs" text to permission notice.
2010-10-14 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (side-effect-free-fns):
* cl-macs.el (remf, getf):
* cl-extra.el (tailp, cl-set-getf, cl-do-remf):
* cl.el (ldiff, endp):
Tighten up Common Lisp compatibility for #'ldiff, #'endp, #'tailp;
add circularity checking for the first two.
#'cl-set-getf and #'cl-do-remf were Lisp implementations of
#'plist-put and #'plist-remprop; change the names to aliases,
changes the macros that use them to using #'plist-put and
#'plist-remprop directly.
2010-10-12 Aidan Kehoe <kehoea@parhasard.net>
* abbrev.el (fundamental-mode-abbrev-table, global-abbrev-table):
Create both these abbrev tables using the usual
#'define-abbrev-table calls, rather than attempting to
special-case them.
* cl-extra.el: Force cl-macs to be loaded here, if cl-extra.el is
being loaded interpreted. Previously other, later files would
redundantly call (load "cl-macs") when interpreted, it's more
reasonable to do it here, once.
* cmdloop.el (read-quoted-char-radix): Use defcustom here, we
don't have any dump-order dependencies that would prevent that.
* custom.el (eval-when-compile): Don't load cl-macs when
interpreted or when byte-compiling, rely on cl-extra.el in the
former case and the appropriate entry in bytecomp-load-hook in the
latter. Get rid of custom-declare-variable-list, we have no
dump-time dependencies that would require it.
* faces.el (eval-when-compile): Don't load cl-macs when
interpreted or when byte-compiling.
* packages.el: Remove some inaccurate comments.
* post-gc.el (cleanup-simple-finalizers): Use #'delete-if-not
here, now the order of preloaded-file-list has been changed to
make it available.
* subr.el (custom-declare-variable-list): Remove. No need for it.
Also remove a stub define-abbrev-table from this file, given the
current order of preloaded-file-list there's no need for it.
2010-10-10 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-constp) Forms quoted with FUNCTION are
also constant.
(byte-compile-initial-macro-environment): In #'the, if FORM is
constant and does not match TYPE, warn at byte-compile time.
2010-10-10 Aidan Kehoe <kehoea@parhasard.net>
* backquote.el (bq-vector-contents, bq-list*): Remove; the former
is equivalent to (append VECTOR nil), the latter to (list* ...).
(bq-process-2): Use (append VECTOR nil) instead of using
#'bq-vector-contents to convert to a list.
(bq-process-1): Now we use list* instead of bq-list
* subr.el (list*): Moved from cl.el, since it is now required to
be available the first time a backquoted form is encountered.
* cl.el (list*): Move to subr.el.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* test-harness.el (Check-Message):
Add an omitted comma here, thank you the buildbot.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* hash-table.el (hash-table-key-list, hash-table-value-list)
(hash-table-key-value-alist, hash-table-key-value-plist):
Remove some useless #'nreverse calls in these files; our hash
tables have no order, it's not helpful to pretend they do.
* behavior.el (read-behavior):
Do the same in this file, in some code evidently copied from
hash-table.el.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* info.el (Info-insert-dir):
* format.el (format-deannotate-region):
* files.el (cd, save-buffers-kill-emacs):
Use #'some, #'every and related functions for applying boolean
operations to lists, instead of rolling our own ones that cons and
don't short-circuit.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-initial-macro-environment):
* cl-macs.el (the):
Rephrase the docstring, make its implementation when compiling
files a little nicer.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* descr-text.el (unidata-initialize-unicodedata-database)
(unidata-initialize-unihan-database, describe-char-unicode-data)
(describe-char-unicode-data):
Wrap calls to the database functions with (with-fboundp ...),
avoiding byte compile warnings on builds without support for the
database functions.
(describe-char): (reduce #'max ...), not (apply #'max ...), no
need to cons needlessly.
(describe-char): Remove a redundant lambda wrapping
#'extent-properties.
(describe-char-unicode-data): Call #'nsubst when replacing "" with
nil in the result of #'split-string, instead of consing inside
mapcar.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* x-faces.el (x-available-font-sizes):
* specifier.el (let-specifier):
* package-ui.el (pui-add-required-packages):
* msw-faces.el (mswindows-available-font-sizes):
* modeline.el (modeline-minor-mode-menu):
* minibuf.el (minibuf-directory-files):
Replace the O2N (delq nil (mapcar (lambda (W) (and X Y)) Z)) with
the ON (mapcan (lambda (W) (and X (list Y))) Z) in these files.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (= < > <= >=):
When these functions are handed more than two arguments, and those
arguments have no side effects, transform to a series of two
argument calls, avoiding funcall in the byte-compiled code.
* mule/mule-cmds.el (finish-set-language-environment):
Take advantage of this change in a function called 256 times at
startup.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-function-form, byte-compile-quote)
(byte-compile-quote-form):
Warn at compile time, and error at runtime, if a (quote ...) or a
(function ...) form attempts to quote more than one object.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (byte-optimize-apply): Transform (apply 'nconc
(mapcar ...)) to (mapcan ...); warn about use of the first idiom.
* update-elc.el (do-autoload-commands):
* packages.el (packages-find-package-library-path):
* frame.el (frame-list):
* extents.el (extent-descendants):
* etags.el (buffer-tag-table-files):
* dumped-lisp.el (preloaded-file-list):
* device.el (device-list):
* bytecomp-runtime.el (proclaim-inline, proclaim-notinline)
Use #'mapcan, not (apply #'nconc (mapcar ...) in all these files.
* bytecomp-runtime.el (eval-when-compile, eval-and-compile):
In passing, mention that these macros also evaluate the body when
interpreted.
tests/ChangeLog addition:
2011-02-07 Aidan Kehoe <kehoea@parhasard.net>
* automated/lisp-tests.el:
Test lexical scope for `block', `return-from'; add a
Known-Bug-Expect-Failure for a contorted example that fails when
byte-compiled.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Mon, 07 Feb 2011 12:01:24 +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. |