43.18.5 Saving Text Properties in Files

You can save text properties in files, and restore text properties when inserting the files, using these two hooks:

Variable: write-region-annotate-functions

This variable’s value is a list of functions for write-region to run to encode text properties in some fashion as annotations to the text being written in the file. See Writing to Files.

Each function in the list is called with two arguments: the start and end of the region to be written. These functions should not alter the contents of the buffer. Instead, they should return lists indicating annotations to write in the file in addition to the text in the buffer.

Each function should return a list of elements of the form (position . string), where position is an integer specifying the relative position in the text to be written, and string is the annotation to add there.

Each list returned by one of these functions must be already sorted in increasing order by position. If there is more than one function, write-region merges the lists destructively into one sorted list.

When write-region actually writes the text from the buffer to the file, it intermixes the specified annotations at the corresponding positions. All this takes place without modifying the buffer.

Variable: after-insert-file-functions

This variable holds a list of functions for insert-file-contents to call after inserting a file’s contents. These functions should scan the inserted text for annotations, and convert them to the text properties they stand for.

Each function receives one argument, the length of the inserted text; point indicates the start of that text. The function should scan that text for annotations, delete them, and create the text properties that the annotations specify. The function should return the updated length of the inserted text, as it stands after those changes. The value returned by one function becomes the argument to the next function.

These functions should always return with point at the beginning of the inserted text.

The intended use of after-insert-file-functions is for converting some sort of textual annotations into actual text properties. But other uses may be possible.

We invite users to write Lisp programs to store and retrieve text properties in files, using these hooks, and thus to experiment with various data formats and find good ones. Eventually we hope users will produce good, general extensions we can install in SXEmacs.

We suggest not trying to handle arbitrary Lisp objects as property names or property values—because a program that general is probably difficult to write, and slow. Instead, choose a set of possible data types that are reasonably flexible, and not too hard to encode.

See Format Conversion, for a related feature.