Commit e1b2918c authored by Karl Fogel's avatar Karl Fogel

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>
parent 74b4f138
...@@ -4662,9 +4662,9 @@ If N is negative, this is a more recent kill. ...@@ -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 The sequence of kills wraps around, so that after the oldest one
comes the newest one. comes the newest one.
When this command inserts killed text into the buffer, it honors This command honors the `yank-handled-properties' and
`yank-excluded-properties' and `yank-handler' as described in the `yank-excluded-properties' variables, and the `yank-handler' text
doc string for `insert-for-yank-1', which see." property, in the way that `yank' does."
(interactive "*p") (interactive "*p")
(if (not (eq last-command 'yank)) (if (not (eq last-command 'yank))
(user-error "Previous command was not a 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. ...@@ -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 just \\[universal-argument] as argument, put point at beginning, and mark at end.
With argument N, reinsert the Nth most recent kill. With argument N, reinsert the Nth most recent kill.
When this command inserts text into the buffer, it honors the This command honors the `yank-handled-properties' and
`yank-handled-properties' and `yank-excluded-properties' `yank-excluded-properties' variables, and the `yank-handler' text
variables, and the `yank-handler' text property. See property, as described below.
`insert-for-yank-1' for details.
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])." See also the command `yank-pop' (\\[yank-pop])."
(interactive "*P") (interactive "*P")
......
...@@ -2859,9 +2859,11 @@ remove properties specified by `yank-excluded-properties'." ...@@ -2859,9 +2859,11 @@ remove properties specified by `yank-excluded-properties'."
(defvar yank-undo-function) (defvar yank-undo-function)
(defun insert-for-yank (string) (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) (let (to)
(while (setq to (next-single-property-change 0 'yank-handler string)) (while (setq to (next-single-property-change 0 'yank-handler string))
(insert-for-yank-1 (substring string 0 to)) (insert-for-yank-1 (substring string 0 to))
...@@ -2869,31 +2871,7 @@ See `insert-for-yank-1' for more details." ...@@ -2869,31 +2871,7 @@ See `insert-for-yank-1' for more details."
(insert-for-yank-1 string)) (insert-for-yank-1 string))
(defun insert-for-yank-1 (string) (defun insert-for-yank-1 (string)
"Insert STRING at point for the `yank' command. "Helper for `insert-for-yank', which see."
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."
(let* ((handler (and (stringp string) (let* ((handler (and (stringp string)
(get-text-property 0 'yank-handler string))) (get-text-property 0 'yank-handler string)))
(param (or (nth 1 handler) string)) (param (or (nth 1 handler) string))
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment