Variable: write-region-annotate-functions

write-region-annotate-functions is a variable defined in fileio.c.

Value

nil

Documentation

A list of functions to be called at the start of write-region.

Each is passed two arguments, START and END as for write-region. These are usually two numbers but not always; see the documentation for write-region. The function should return a list of pairs of the form (POSITION . STRING), consisting of strings to be effectively inserted at the specified positions of the file being written (1 means to insert before the first byte written). The POSITIONs must be sorted into increasing order.

If there are several annotation functions, the lists returned by these functions are merged destructively. As each annotation function runs, the variable write-region-annotations-so-far contains a list of all annotations returned by previous annotation functions.

An annotation function can return with a different buffer current. Doing so removes the annotations returned by previous functions, and resets START and END to point-min and point-max of the new buffer.

After write-region completes, Emacs calls the function stored in write-region-post-annotation-function, once for each buffer that was current when building the annotations (i.e., at least once), with that buffer current.

View in manual

Probably introduced at or before Emacs version 19.29.

Source Code

// Defined in /usr/src/emacs/src/fileio.c
  DEFVAR_LISP ("write-region-annotate-functions", Vwrite_region_annotate_functions,
	       doc: /* A list of functions to be called at the start of `write-region'.
Each is passed two arguments, START and END as for `write-region'.
These are usually two numbers but not always; see the documentation
for `write-region'.  The function should return a list of pairs
of the form (POSITION . STRING), consisting of strings to be effectively
inserted at the specified positions of the file being written (1 means to
insert before the first byte written).  The POSITIONs must be sorted into
increasing order.

If there are several annotation functions, the lists returned by these
functions are merged destructively.  As each annotation function runs,
the variable `write-region-annotations-so-far' contains a list of all
annotations returned by previous annotation functions.

An annotation function can return with a different buffer current.
Doing so removes the annotations returned by previous functions, and
resets START and END to `point-min' and `point-max' of the new buffer.

After `write-region' completes, Emacs calls the function stored in
`write-region-post-annotation-function', once for each buffer that was
current when building the annotations (i.e., at least once), with that
buffer current.  */);