47.9 Duplicable Extents

If an extent has the duplicable property, it will be copied into strings, so that kill, yank, and undo commands will restore or copy it.

Specifically:

• When a string is created using buffer-substring or buffer-string, any duplicable extents in the region corresponding to the string will be copied into the string (see Buffer Contents). When the string is inserted into a buffer using insert, insert-before-markers, insert-buffer or insert-buffer-substring, the extents in the string will be copied back into the buffer (see Insertion). The extents in a string can, of course, be retrieved explicitly using the standard extent primitives over the string.
• Similarly, when text is copied or cut into the kill ring, any duplicable extents will be remembered and reinserted later when the text is pasted back into a buffer.
• When concat is called on strings, the extents in the strings are copied into the resulting string.
• When substring is called on a string, the relevant extents are copied into the resulting string.
• When a duplicable extent is detached by detach-extent or string deletion, or inserted by insert-extent or string insertion, the action is recorded by the undo mechanism so that it can be undone later. Note that if an extent gets detached and then a later undo causes the extent to get reinserted, the new extent will not be ‘eq’ to the original extent.
• Extent motion, face changes, and attachment via make-extent are not recorded by the undo mechanism. This means that extent changes which are to be undo-able must be performed by character editing, or by insertion and detachment of duplicable extents.
• A duplicable extent’s copy-function property, if non-nil, should be a function, and will be run when a duplicable extent is about to be copied from a buffer to a string (or the kill ring). It is called with three arguments: the extent and the buffer positions within it which are being copied. If this function returns nil, then the extent will not be copied; otherwise it will.
• A duplicable extent’s paste-function property, if non-nil, should be a function, and will be run when a duplicable extent is about to be copied from a string (or the kill ring) into a buffer. It is called with three arguments: the original extent and the buffer positions which the copied extent will occupy. (This hook is run after the corresponding text has already been inserted into the buffer.) Note that the extent argument may be detached when this function is run. If this function returns nil, no extent will be inserted. Otherwise, there will be an extent covering the range in question.

  Note: if the extent to be copied is already attached to the buffer and overlaps the new range, the extent will simply be extended and the paste-function will not be called.