diff options
Diffstat (limited to 'devdocs/elisp/yanking.html')
| -rw-r--r-- | devdocs/elisp/yanking.html | 22 |
1 files changed, 22 insertions, 0 deletions
diff --git a/devdocs/elisp/yanking.html b/devdocs/elisp/yanking.html new file mode 100644 index 00000000..f57d83d4 --- /dev/null +++ b/devdocs/elisp/yanking.html @@ -0,0 +1,22 @@ + <h4 class="subsection">Yanking</h4> <p>Yanking means inserting text from the kill ring, but it does not insert the text blindly. The <code>yank</code> command, and related commands, use <code>insert-for-yank</code> to perform special processing on the text before it is inserted. </p> <dl> <dt id="insert-for-yank">Function: <strong>insert-for-yank</strong> <em>string</em> +</dt> <dd><p>This function works like <code>insert</code>, except that it processes the text in <var>string</var> according to the <code>yank-handler</code> text property, as well as the variables <code>yank-handled-properties</code> and <code>yank-excluded-properties</code> (see below), before inserting the result into the current buffer. </p></dd> +</dl> <dl> <dt id="insert-buffer-substring-as-yank">Function: <strong>insert-buffer-substring-as-yank</strong> <em>buf &optional start end</em> +</dt> <dd><p>This function resembles <code>insert-buffer-substring</code>, except that it processes the text according to <code>yank-handled-properties</code> and <code>yank-excluded-properties</code>. (It does not handle the <code>yank-handler</code> property, which does not normally occur in buffer text anyway.) </p></dd> +</dl> <p>If you put a <code>yank-handler</code> text property on all or part of a string, that alters how <code>insert-for-yank</code> inserts the string. If different parts of the string have different <code>yank-handler</code> values (comparison being done with <code>eq</code>), each substring is handled separately. The property value must be a list of one to four elements, with the following format (where elements after the first may be omitted): </p> <div class="example"> <pre class="example">(<var>function</var> <var>param</var> <var>noexclude</var> <var>undo</var>) +</pre> +</div> <p>Here is what the elements do: </p> <dl compact> <dt><var>function</var></dt> <dd> +<p>When <var>function</var> is non-<code>nil</code>, it is called instead of <code>insert</code> to insert the string, with one argument—the string to insert. </p> </dd> <dt><var>param</var></dt> <dd> +<p>If <var>param</var> is present and non-<code>nil</code>, it replaces <var>string</var> (or the substring of <var>string</var> being processed) as the object passed to <var>function</var> (or <code>insert</code>). For example, if <var>function</var> is <code>yank-rectangle</code>, <var>param</var> should be a list of strings to insert as a rectangle. </p> </dd> <dt><var>noexclude</var></dt> <dd> +<p>If <var>noexclude</var> is present and non-<code>nil</code>, that disables the normal action of <code>yank-handled-properties</code> and <code>yank-excluded-properties</code> on the inserted string. </p> </dd> <dt><var>undo</var></dt> <dd><p>If <var>undo</var> is present and non-<code>nil</code>, it is a function that will be called by <code>yank-pop</code> to undo the insertion of the current object. It is called with two arguments, the start and end of the current region. <var>function</var> can set <code>yank-undo-function</code> to override the <var>undo</var> value. </p></dd> </dl> <dl> <dt id="yank-handled-properties">User Option: <strong>yank-handled-properties</strong> +</dt> <dd> +<p>This variable specifies special text property handling conditions for yanked text. It takes effect after the text has been inserted (either normally, or via the <code>yank-handler</code> property), and prior to <code>yank-excluded-properties</code> taking effect. </p> <p>The value should be an alist of elements <code>(<var>prop</var> +. <var>fun</var>)</code>. Each alist element is handled in order. The inserted text is scanned for stretches of text having text properties <code>eq</code> to <var>prop</var>; for each such stretch, <var>fun</var> is called with three arguments: the value of the property, and the start and end positions of the text. </p> +</dd> +</dl> <dl> <dt id="yank-excluded-properties">User Option: <strong>yank-excluded-properties</strong> +</dt> <dd><p>The value of this variable is the list of properties to remove from inserted text. Its default value contains properties that might lead to annoying results, such as causing the text to respond to the mouse or specifying key bindings. It takes effect after <code>yank-handled-properties</code>. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Yanking.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Yanking.html</a> + </p> +</div> |