elisp: Low-Level Kill Ring
31.8.5 Low-Level Kill Ring
--------------------------
These functions and variables provide access to the kill ring at a lower
level, but are still convenient for use in Lisp programs, because they
take care of interaction with window system selections (
Window
System Selections).
-- Function: current-kill n &optional do-not-move
The function ‘current-kill’ rotates the yanking pointer, which
designates the front of the kill ring, by N places (from newer
kills to older ones), and returns the text at that place in the
ring.
If the optional second argument DO-NOT-MOVE is non-‘nil’, then
‘current-kill’ doesn’t alter the yanking pointer; it just returns
the Nth kill, counting from the current yanking pointer.
If N is zero, indicating a request for the latest kill,
‘current-kill’ calls the value of ‘interprogram-paste-function’
(documented below) before consulting the kill ring. If that value
is a function and calling it returns a string or a list of several
string, ‘current-kill’ pushes the strings onto the kill ring and
returns the first string. It also sets the yanking pointer to
point to the kill-ring entry of the first string returned by
‘interprogram-paste-function’, regardless of the value of
DO-NOT-MOVE. Otherwise, ‘current-kill’ does not treat a zero value
for N specially: it returns the entry pointed at by the yanking
pointer and does not move the yanking pointer.
-- Function: kill-new string &optional replace
This function pushes the text STRING onto the kill ring and makes
the yanking pointer point to it. It discards the oldest entry if
appropriate. It also invokes the value of
‘interprogram-cut-function’ (see below).
If REPLACE is non-‘nil’, then ‘kill-new’ replaces the first element
of the kill ring with STRING, rather than pushing STRING onto the
kill ring.
-- Function: kill-append string before-p
This function appends the text STRING to the first entry in the
kill ring and makes the yanking pointer point to the combined
entry. Normally STRING goes at the end of the entry, but if
BEFORE-P is non-‘nil’, it goes at the beginning. This function
also invokes the value of ‘interprogram-cut-function’ (see below).
-- Variable: interprogram-paste-function
This variable provides a way of transferring killed text from other
programs, when you are using a window system. Its value should be
‘nil’ or a function of no arguments.
If the value is a function, ‘current-kill’ calls it to get the most
recent kill. If the function returns a non-‘nil’ value, then that
value is used as the most recent kill. If it returns ‘nil’, then
the front of the kill ring is used.
To facilitate support for window systems that support multiple
selections, this function may also return a list of strings. In
that case, the first string is used as the most recent kill, and
all the other strings are pushed onto the kill ring, for easy
access by ‘yank-pop’.
The normal use of this function is to get the window system’s
clipboard as the most recent kill, even if the selection belongs to
another application. Window System Selections. However,
if the clipboard contents come from the current Emacs session, this
function should return ‘nil’.
-- Variable: interprogram-cut-function
This variable provides a way of communicating killed text to other
programs, when you are using a window system. Its value should be
‘nil’ or a function of one required argument.
If the value is a function, ‘kill-new’ and ‘kill-append’ call it
with the new first element of the kill ring as the argument.
The normal use of this function is to put newly killed text in the
window system’s clipboard. Window System Selections.
Info Catalog
elisp: Yank Commands
elisp: The Kill Ring
elisp: Internals of Kill Ring