procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document yank behavior in the right place

Browse source 
* 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>
This commit is contained in:
Karl Fogel 2016-10-02 19:47:27 -05:00
parent 74b4f13842
commit e1b2918c7c
2 changed files with 36 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
lisp/simple.el
View file

@ -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")

32
lisp/subr.el
View file

@ -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))