Function: cycle-spacing

cycle-spacing is an interactive and byte-compiled function defined in simple.el.gz.

Signature

(cycle-spacing &optional N PRESERVE-NL-BACK MODE)

Documentation

Manipulate whitespace around point in a smart way.

In interactive use, this function behaves differently in successive consecutive calls.

The first call in a sequence acts like just-one-space. It deletes all spaces and tabs around point, leaving one space
(or N spaces). N is the prefix argument. If N is negative,
it deletes newlines as well, leaving -N spaces.
(If PRESERVE-NL-BACK is non-nil, it does not delete newlines before point.)

The second call in a sequence deletes all spaces.

The third call in a sequence restores the original whitespace (and point).

If MODE is single-shot, it performs only the first step in the sequence. If MODE is fast and the first step would not result in any change
(i.e., there are exactly (abs N) spaces around point),
the function goes straight to the second step.

Repeatedly calling the function with different values of N starts a new sequence each time.

Probably introduced at or before Emacs version 24.4.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/simple.el.gz
(defun cycle-spacing (&optional n preserve-nl-back mode)
  "Manipulate whitespace around point in a smart way.
In interactive use, this function behaves differently in successive
consecutive calls.

The first call in a sequence acts like `just-one-space'.
It deletes all spaces and tabs around point, leaving one space
\(or N spaces).  N is the prefix argument.  If N is negative,
it deletes newlines as well, leaving -N spaces.
\(If PRESERVE-NL-BACK is non-nil, it does not delete newlines before point.)

The second call in a sequence deletes all spaces.

The third call in a sequence restores the original whitespace (and point).

If MODE is `single-shot', it performs only the first step in the sequence.
If MODE is `fast' and the first step would not result in any change
\(i.e., there are exactly (abs N) spaces around point),
the function goes straight to the second step.

Repeatedly calling the function with different values of N starts a
new sequence each time."
  (interactive "*p")
  (let ((orig-pos	 (point))
	(skip-characters (if (and n (< n 0)) " \t\n\r" " \t"))
	(num		 (abs (or n 1))))
    (skip-chars-backward (if preserve-nl-back " \t" skip-characters))
    (constrain-to-field nil orig-pos)
    (cond
     ;; Command run for the first time, single-shot mode or different argument
     ((or (eq 'single-shot mode)
	  (not (equal last-command this-command))
	  (not cycle-spacing--context)
	  (not (eq (car cycle-spacing--context) n)))
      (let* ((start (point))
	     (num   (- num (skip-chars-forward " " (+ num (point)))))
	     (mid   (point))
	     (end   (progn
		      (skip-chars-forward skip-characters)
		      (constrain-to-field nil orig-pos t))))
	(setq cycle-spacing--context  ;; Save for later.
	      ;; Special handling for case where there was no space at all.
	      (unless (= start end)
                (cons n (cons orig-pos (buffer-substring start (point))))))
	;; If this run causes no change in buffer content, delete all spaces,
	;; otherwise delete all excess spaces.
	(delete-region (if (and (eq mode 'fast) (zerop num) (= mid end))
			   start mid) end)
        (insert (make-string num ?\s))))

     ;; Command run for the second time.
     ((not (equal orig-pos (point)))
      (delete-region (point) orig-pos))

     ;; Command run for the third time.
     (t
      (insert (cddr cycle-spacing--context))
      (goto-char (cadr cycle-spacing--context))
      (setq cycle-spacing--context nil)))))