Lines Matching defs:format
0 ;;; format.el --- read and save files in multiple formats
28 ;; in different formats. `format-alist' contains information that directs
32 ;; When a file is visited, its format is determined by matching the
34 ;; `format-alist'. If this fails, you can manually translate the buffer
35 ;; using `format-decode-buffer'. In either case, the formats used are
36 ;; listed in the variable `buffer-file-format', and become the default
37 ;; format for saving the buffer. To save a buffer in a different format,
38 ;; change this variable, or use `format-write-file'.
40 ;; Auto-save files are normally created in the same format as the visited
41 ;; file, but the variable `buffer-auto-save-file-format' can be set to a
42 ;; particularly fast or otherwise preferred format to be used for
46 ;; You can manually translate a buffer into or out of a particular format
47 ;; with the functions `format-encode-buffer' and `format-decode-buffer'.
48 ;; To translate just the region use the functions `format-encode-region'
49 ;; and `format-decode-region'.
51 ;; You can define a new format by writing the encoding and decoding
52 ;; functions, and adding an entry to `format-alist'. See enriched.el for
53 ;; an example of how to implement a file format. There are various
56 ;; * `format-annotate-region' and `format-deannotate-region' allow a
60 ;; * `format-replace-strings' is similarly useful for doing simple
65 (put 'buffer-file-format 'permanent-local t)
66 (put 'buffer-auto-save-file-format 'permanent-local t)
68 (defvar format-alist
69 '((text/enriched "Extended MIME text/enriched format."
72 (plain "ISO 8859-1 standard format, no text properties."
112 NAME is a symbol, which is stored in `buffer-file-format'.
115 format. It is currently unused, but in the future will be shown to
119 it should match only files in that format. Use nil to avoid
123 FROM-FN is called to decode files in that format; it takes two args, BEGIN
130 TO-FN is called to encode a region into that format; it takes three
143 MODE-FN, if specified, is called when visiting a file with that format.
147 PRESERVE, if non-nil, means that `format-write-file' should not remove
148 this format from `buffer-file-formats'.")
152 (defun format-encode-run-method (method from to &optional buffer)
160 format-alist)
175 (defun format-decode-run-method (method from to &optional buffer)
182 format-alist)
201 (defun format-annotate-function (format from to orig-buf format-count)
203 FORMAT is a symbol naming one of the formats defined in `format-alist'.
204 It must be a single symbol, not a list like `buffer-file-format'.
216 For most purposes, consider using `format-encode-region' instead."
218 ;; build_annotations) for each element of buffer-file-format.
219 (let* ((info (assq format format-alist))
225 (let ((copy-buf (get-buffer-create (format " *Format Temp %d*"
226 format-count)))
236 (format-insert-annotations write-region-annotations-so-far from)
237 (format-encode-run-method to-fn (point-min) (point-max) orig-buf)
242 (defun format-decode (format length &optional visit-flag)
245 FORMAT is a symbol appearing in `format-alist' or a list of such symbols,
246 or nil, in which case this function tries to guess the format of the data by
247 matching against the regular expressions in `format-alist'. After a match is
252 If optional third arg VISIT-FLAG is true, set `buffer-file-format'
258 For most purposes, consider using `format-decode-region' instead."
266 (if (null format)
267 ;; Figure out which format it is in, remember list in `format'.
268 (let ((try format-alist))
276 (push (car f) format)
279 (setq end (format-decode-run-method (nth 3 f) begin end)))
284 ;; Rewind list to look for another format
285 (setq try format-alist))
287 ;; Deal with given format(s)
288 (or (listp format) (setq format (list format)))
289 (let ((do format) f)
291 (or (setq f (assq (car do) format-alist))
292 (error "Unknown format %s" (car do)))
295 (setq end (format-decode-run-method (nth 3 f) begin end)))
300 (setq format (reverse format)))
302 (setq buffer-file-format format)))
313 (defun format-decode-buffer (&optional format)
315 If the format is not specified, attempt a regexp-based guess.
316 Set `buffer-file-format' to the format used, and call any
317 format-specific mode functions."
319 (list (format-read "Translate buffer from format (default guess): ")))
322 (format-decode format (buffer-size) t)))
324 (defun format-decode-region (from to &optional format)
325 "Decode the region from some format.
326 Arg FORMAT is optional; if omitted the format will be determined by looking
330 (format-read "Translate region from format (default guess): ")))
333 (format-decode format (- to from) nil)))
335 (defun format-encode-buffer (&optional format)
337 FORMAT defaults to `buffer-file-format'. It is a symbol naming one of the
338 formats defined in `format-alist', or a list of such symbols."
340 (list (format-read (format "Translate buffer to format (default %s): "
341 buffer-file-format))))
342 (format-encode-region (point-min) (point-max) format))
344 (defun format-encode-region (beg end &optional format)
346 FORMAT defaults to `buffer-file-format'. It is a symbol naming
347 one of the formats defined in `format-alist', or a list of such symbols."
350 (format-read (format "Translate region to format (default %s): "
351 buffer-file-format))))
352 (if (null format) (setq format buffer-file-format))
353 (if (symbolp format) (setq format (list format)))
358 (while format
359 (let* ((info (assq (car format) format-alist))
365 (setq end (format-encode-run-method to-fn beg end
367 (format-insert-annotations
369 (setq format (cdr format)))))))
371 (defun format-write-file (filename format &optional confirm)
373 Make buffer visit that file and set the format as the default for future
381 ;; Same interactive spec as write-file, plus format question.
389 (fmt (format-read (format "Write file `%s' in format: "
392 (let ((old-formats buffer-file-format)
395 (let ((aelt (assq fmt format-alist)))
398 (setq buffer-file-format format)
400 (unless (memq fmt buffer-file-format)
401 (setq buffer-file-format (append buffer-file-format (list fmt))))))
404 (defun format-find-file (filename format)
405 "Find the file FILENAME using data format FORMAT.
406 If FORMAT is nil then do not do any format conversion."
408 ;; Same interactive spec as write-file, plus format question.
410 (fmt (format-read (format "Read file `%s' in format: "
413 (let ((format-alist nil))
415 (if format
416 (format-decode-buffer format)))
418 (defun format-insert-file (filename format &optional beg end)
419 "Insert the contents of file FILENAME using data format FORMAT.
420 If FORMAT is nil then do not do any format conversion.
427 ;; Same interactive spec as write-file, plus format question.
429 (fmt (format-read (format "Read file `%s' in format: "
433 (let ((format-alist nil))
436 (if format
437 (setq size (format-decode format size)
441 (defun format-read (&optional prompt)
442 "Read and return the name of a format.
443 Return value is a list, like `buffer-file-format'; it may be nil.
444 Formats are defined in `format-alist'. Optional arg is the PROMPT to use."
446 format-alist))
453 ;;; decoding functions for use in format-alist.
456 (defun format-replace-strings (alist &optional reverse beg end)
483 (defun format-delq-cons (cons list)
486 `\(setq foo \(format-delq-cons element foo))' to be sure of changing
492 (if (null p) (error "format-delq-cons: not an element"))
498 (defun format-make-relatively-unique (a b)
507 (if dup (setq acopy (format-delq-cons tail acopy)
508 bcopy (format-delq-cons dup bcopy)))
512 (defun format-common-tail (a b)
528 (defun format-proper-list-p (list)
536 (defun format-reorder (items order)
544 (format-reorder (format-delq-cons item items)
546 (format-reorder items (cdr order))))
549 (put 'face 'format-list-valued t) ; These text-properties take values
550 (put 'unknown 'format-list-valued t) ; that are lists, the elements of which
552 ; See format-deannotate-region and
553 ; format-annotate-region.
557 (put 'display 'format-list-atomic-p t)
563 (defun format-deannotate-region (from to translations next-fn)
575 The basic format of the TRANSLATIONS argument is described in the
576 documentation for the `format-annotate-region' function. There are some
587 non-nil `format-list-valued' property, then the value will be consed onto the
608 \(unknown \(nil format-annotate-value))
675 (format-subtract-regions
741 (format-property-increment-region from to prop val 0)
744 (cond ((get prop 'format-list-valued) ; value gets consed onto
754 (defun format-subtract-regions (minu subtra)
791 ;; This should probably go somewhere other than format.el. Then again,
795 (defun format-property-increment-region (from to prop delta default)
811 (defun format-insert-annotations (list &optional offset)
827 (defun format-annotate-value (old new)
835 (defun format-annotate-region (from to translations format-fn ignore)
842 function to `format-insert-annotations'.
866 a cons cell (CLOSE . OPEN) as `format-annotate-single-property-change' does.
877 (let* ((ans (format-annotate-location loc (= loc from) ignore translations))
878 (neg-ans (format-reorder (aref ans 0) open-ans))
895 (cons (cons loc (funcall format-fn (car open-ans) nil))
901 (push (cons loc (funcall format-fn (car neg-ans) nil))
908 (push (cons loc (funcall format-fn (car pos-ans) t))
915 (cons (cons to (funcall format-fn (car open-ans) nil))
923 ;;; Internal functions for format-annotate-region.
925 (defun format-annotate-location (loc all ignore translations)
931 Use the TRANSLATIONS alist (see `format-annotate-region' for doc).
939 They can be whatever the FORMAT-FN in `format-annotate-region'
966 (let ((result (format-annotate-single-property-change
974 (defun format-annotate-single-property-change (prop old new translations)
977 (see `format-annotate-region' for the format).
985 They can be whatever the FORMAT-FN in `format-annotate-region'
995 (not (get prop 'format-list-atomic-p)))
996 (if (or (not (format-proper-list-p old))
997 (not (format-proper-list-p new)))
998 (format-annotate-atomic-property-change prop-alist old new)
1001 (tail (format-common-tail old new))
1005 (append (car (format-annotate-atomic-property-change
1011 (append (cdr (format-annotate-atomic-property-change
1015 (format-make-relatively-unique close open)))
1016 (format-annotate-atomic-property-change prop-alist old new)))))
1018 (defun format-annotate-atomic-property-change (prop-alist old new)
1052 (format-make-relatively-unique close open)
1058 (provide 'format)
1061 ;;; format.el ends here