Function: icalendar-fold-region

icalendar-fold-region is a byte-compiled function defined in icalendar-parser.el.gz.

Signature

(icalendar-fold-region BEGIN END &optional ANNOTATE-ONLY USE-TABS)

Documentation

Fold content lines between BEGIN and END when longer than 75 octets.

"Folding" means inserting a line break and a single space
character at the beginning of the new line. If USE-TABS is non-nil, insert a tab character instead of a single space.

RFC5545 specifies that lines longer than 75 *octets* (excluding the line-ending CR-LF sequence) must be folded, and allows that some implementations might fold lines in the middle of a multibyte character. This function takes care not to do that in a buffer where enable-multibyte-characters is non-nil, and only folds between character boundaries. If the buffer is in unibyte mode, however, and contains undecoded multibyte data, it may fold lines in the middle of a multibyte character.

By default, this function modifies the region by inserting line folds. If the optional argument ANNOTATE-ONLY is non-nil, it will instead leave the buffer unmodified, and return a list of "annotations"
(POSITION . LINE-FOLD), indicating where line folds in the region should
be inserted. This output is suitable for a function in write-region-annotation-functions; icalendar-folding-annotations is a wrapper for this function which can be added to that list.

Source Code

;; Defined in /usr/src/emacs/lisp/calendar/icalendar-parser.el.gz
(defun ical:fold-region (begin end &optional annotate-only use-tabs)
  "Fold content lines between BEGIN and END when longer than 75 octets.

\"Folding\" means inserting a line break and a single space
character at the beginning of the new line.  If USE-TABS is
non-nil, insert a tab character instead of a single space.

RFC5545 specifies that lines longer than 75 *octets* (excluding
the line-ending CR-LF sequence) must be folded, and allows that
some implementations might fold lines in the middle of a
multibyte character.  This function takes care not to do that in a
buffer where `enable-multibyte-characters' is non-nil, and only
folds between character boundaries.  If the buffer is in unibyte
mode, however, and contains undecoded multibyte data, it may fold
lines in the middle of a multibyte character.

By default, this function modifies the region by inserting line folds.
If the optional argument ANNOTATE-ONLY is non-nil, it will instead leave
the buffer unmodified, and return a list of \"annotations\"
\(POSITION . LINE-FOLD), indicating where line folds in the region should
be inserted.  This output is suitable for a function in
`write-region-annotation-functions'; `icalendar-folding-annotations'
is a wrapper for this function which can be added to that list."
  ;; TODO: also make this a command so it can be run manually?
  (let (annotations)
    (save-excursion
      (goto-char begin)
      (when (not (bolp))
        (let ((inhibit-field-text-motion t))
          (beginning-of-line)))
      (let ((bol (point))
            (eol (make-marker))
            (reg-end (make-marker))
            (line-fold (if use-tabs "\n\t" "\n ")))
        (set-marker reg-end end)
        (while (< bol reg-end)
          (let ((inhibit-field-text-motion t))
            (end-of-line))
          (set-marker eol (point))
          (when (< 75 (- (position-bytes (marker-position eol))
                         (position-bytes bol)))
            (goto-char
             ;; the max of 75 excludes the two CR-LF
             ;; characters we're about to add:
             (byte-to-position (+ 75 (position-bytes bol))))
            (if annotate-only
                (push (cons (point) line-fold) annotations)
              (insert line-fold))
            (set-marker eol (point)))
          (setq bol (goto-char (1+ eol))))))
    ;; Return annotations, or nil if we modified the buffer directly:
    (nreverse annotations)))