From e1b2918c7cdecdde093390adc2fa26713554da02 Mon Sep 17 00:00:00 2001 From: Karl Fogel Date: Sun, 2 Oct 2016 19:47:27 -0500 Subject: [PATCH] Document yank behavior in the right place * lisp/simple.el (yank): Document the handling of the `yank-handled-properties' and `yank-excluded-properties' variables, and the `yank-handler' text property. (yank-pop): Refer to `yank' now (bug#286) * lisp/subr.el (insert-for-yank): Refer to `yank' now. (insert-for-yank-1): Refer to `insert-for-yank' now. See this thread for discussion: https://lists.gnu.org/archive/html/emacs-devel/2016-09/threads.html#00329 From: Karl Fogel To: Emacs Devel Subject: Question about intended behavior of 'insert-for-yank-1'. Date: Mon, 12 Sep 2016 00:17:14 -0500 Message-ID: <874m5lr92d.fsf@red-bean.com> --- lisp/simple.el | 38 +++++++++++++++++++++++++++++++------- lisp/subr.el | 32 +++++--------------------------- 2 files changed, 36 insertions(+), 34 deletions(-) diff --git a/lisp/simple.el b/lisp/simple.el index c7d3b2e6b0b..c43fe548c82 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -4662,9 +4662,9 @@ If N is negative, this is a more recent kill. The sequence of kills wraps around, so that after the oldest one comes the newest one. -When this command inserts killed text into the buffer, it honors -`yank-excluded-properties' and `yank-handler' as described in the -doc string for `insert-for-yank-1', which see." +This command honors the `yank-handled-properties' and +`yank-excluded-properties' variables, and the `yank-handler' text +property, in the way that `yank' does." (interactive "*p") (if (not (eq last-command 'yank)) (user-error "Previous command was not a yank")) @@ -4697,10 +4697,34 @@ at the end, and set mark at the beginning without activating it. With just \\[universal-argument] as argument, put point at beginning, and mark at end. With argument N, reinsert the Nth most recent kill. -When this command inserts text into the buffer, it honors the -`yank-handled-properties' and `yank-excluded-properties' -variables, and the `yank-handler' text property. See -`insert-for-yank-1' for details. +This command honors the `yank-handled-properties' and +`yank-excluded-properties' variables, and the `yank-handler' text +property, as described below. + +Properties listed in `yank-handled-properties' are processed, +then those listed in `yank-excluded-properties' are discarded. + +If STRING has a non-nil `yank-handler' property anywhere, the +normal insert behavior is altered, and instead, for each contiguous +segment of STRING that has a given value of the `yank-handler' +property, that value is used as follows: + +The value of a `yank-handler' property must be a list of one to four +elements, of the form (FUNCTION PARAM NOEXCLUDE UNDO). +FUNCTION, if non-nil, should be a function of one argument (the + object to insert); FUNCTION is called instead of `insert'. +PARAM, if present and non-nil, is passed to FUNCTION (to be handled + in whatever way is appropriate; e.g. if FUNCTION is `yank-rectangle', + PARAM may be a list of strings to insert as a rectangle). If PARAM + is nil, then the current segment of STRING is used. +If NOEXCLUDE is present and non-nil, the normal removal of + `yank-excluded-properties' is not performed; instead FUNCTION is + responsible for the removal. This may be necessary if FUNCTION + adjusts point before or after inserting the object. +UNDO, if present and non-nil, should be a function to be called + by `yank-pop' to undo the insertion of the current PARAM. It is + given two arguments, the start and end of the region. FUNCTION + may set `yank-undo-function' to override UNDO. See also the command `yank-pop' (\\[yank-pop])." (interactive "*P") diff --git a/lisp/subr.el b/lisp/subr.el index e9e19d35f65..9c717e16b94 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -2859,9 +2859,11 @@ remove properties specified by `yank-excluded-properties'." (defvar yank-undo-function) (defun insert-for-yank (string) - "Call `insert-for-yank-1' repetitively for each `yank-handler' segment. + "Insert STRING at point for the `yank' command. -See `insert-for-yank-1' for more details." +This function is like `insert', except it honors the variables +`yank-handled-properties' and `yank-excluded-properties', and the +`yank-handler' text property, in the way that `yank' does." (let (to) (while (setq to (next-single-property-change 0 'yank-handler string)) (insert-for-yank-1 (substring string 0 to)) @@ -2869,31 +2871,7 @@ See `insert-for-yank-1' for more details." (insert-for-yank-1 string)) (defun insert-for-yank-1 (string) - "Insert STRING at point for the `yank' command. -This function is like `insert', except it honors the variables -`yank-handled-properties' and `yank-excluded-properties', and the -`yank-handler' text property. - -Properties listed in `yank-handled-properties' are processed, -then those listed in `yank-excluded-properties' are discarded. - -If STRING has a non-nil `yank-handler' property on its first -character, the normal insert behavior is altered. The value of -the `yank-handler' property must be a list of one to four -elements, of the form (FUNCTION PARAM NOEXCLUDE UNDO). -FUNCTION, if non-nil, should be a function of one argument, an - object to insert; it is called instead of `insert'. -PARAM, if present and non-nil, replaces STRING as the argument to - FUNCTION or `insert'; e.g. if FUNCTION is `yank-rectangle', PARAM - may be a list of strings to insert as a rectangle. -If NOEXCLUDE is present and non-nil, the normal removal of - `yank-excluded-properties' is not performed; instead FUNCTION is - responsible for the removal. This may be necessary if FUNCTION - adjusts point before or after inserting the object. -UNDO, if present and non-nil, should be a function to be called - by `yank-pop' to undo the insertion of the current object. It is - given two arguments, the start and end of the region. FUNCTION - may set `yank-undo-function' to override UNDO." + "Helper for `insert-for-yank', which see." (let* ((handler (and (stringp string) (get-text-property 0 'yank-handler string))) (param (or (nth 1 handler) string)) -- 2.39.2