Info Catalog elisp: Kill Functions elisp: The Kill Ring elisp: Yank Commands

elisp: Yanking

 
 31.8.3 Yanking
 --------------
 
 Yanking means inserting text from the kill ring, but it does not insert
 the text blindly.  The ‘yank’ command, and related commands, use
 ‘insert-for-yank’ to perform special processing on the text before it is
 inserted.
 
  -- Function: insert-for-yank string
      This function works like ‘insert’, except that it processes the
      text in STRING according to the ‘yank-handler’ text property, as
      well as the variables ‘yank-handled-properties’ and
      ‘yank-excluded-properties’ (see below), before inserting the result
      into the current buffer.
 
  -- Function: insert-buffer-substring-as-yank buf &optional start end
      This function resembles ‘insert-buffer-substring’, except that it
      processes the text according to ‘yank-handled-properties’ and
      ‘yank-excluded-properties’.  (It does not handle the ‘yank-handler’
      property, which does not normally occur in buffer text anyway.)
 
    If you put a ‘yank-handler’ text property on all or part of a string,
 that alters how ‘insert-for-yank’ inserts the string.  If different
 parts of the string have different ‘yank-handler’ values (comparison
 being done with ‘eq’), 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):
 
      (FUNCTION PARAM NOEXCLUDE UNDO)
 
    Here is what the elements do:
 
 FUNCTION
      When FUNCTION is non-‘nil’, it is called instead of ‘insert’ to
      insert the string, with one argument—the string to insert.
 
 PARAM
      If PARAM is present and non-‘nil’, it replaces STRING (or the
      substring of STRING being processed) as the object passed to
      FUNCTION (or ‘insert’).  For example, if FUNCTION is
      ‘yank-rectangle’, PARAM should be a list of strings to insert as a
      rectangle.
 
 NOEXCLUDE
      If NOEXCLUDE is present and non-‘nil’, that disables the normal
      action of ‘yank-handled-properties’ and ‘yank-excluded-properties’
      on the inserted string.
 
 UNDO
      If UNDO is present and non-‘nil’, it is a function that will be
      called by ‘yank-pop’ to undo the insertion of the current object.
      It is called with two arguments, the start and end of the current
      region.  FUNCTION can set ‘yank-undo-function’ to override the UNDO
      value.
 
  -- User Option: yank-handled-properties
      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 ‘yank-handler’ property), and prior to
      ‘yank-excluded-properties’ taking effect.
 
      The value should be an alist of elements ‘(PROP . FUN)’.  Each
      alist element is handled in order.  The inserted text is scanned
      for stretches of text having text properties ‘eq’ to PROP; for each
      such stretch, FUN is called with three arguments: the value of the
      property, and the start and end positions of the text.
 
  -- User Option: yank-excluded-properties
      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
      ‘yank-handled-properties’.
 

Info Catalog elisp: Kill Functions elisp: The Kill Ring elisp: Yank Commands