1 ;;; whitespace.el --- Warn about and clean bogus whitespaces in the file.
3 ;; Copyright (C) 1999 Free Software Foundation, Inc.
5 ;; Author: Rajesh Vaidheeswarran <rv@dsmit.com>
6 ;; Keywords: convenience
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software; you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation; either version 2, or (at your option)
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs; see the file COPYING. If not, write to the
22 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
23 ;; Boston, MA 02111-1307, USA.
27 ;; Whitespace.el URL: http://www.dsmit.com/lisp/
29 ;; Exported functions:
31 ;; `whitespace-buffer' - To check the current buffer for whitespace problems.
32 ;; `whitespace-cleanup' - To cleanup all whitespaces in the current buffer.
33 ;; `whitespace-region' - To check between point and mark for whitespace
35 ;; `whitespace-cleanup-region' - To cleanup all whitespaces between point
36 ;; and mark in the current buffer.
37 ;; `whitespace-describe' - A simple introduction to the library.
41 ;; add a hook to find-file-hooks and kill-buffer-hook
42 (add-hook 'find-file-hooks 'whitespace-buffer)
43 (add-hook 'kill-buffer-hook 'whitespace-buffer)
45 (defvar whitespace-version "2.3" "Version of the whitespace library.")
46 ;; Find out what type of Emacs we are running in.
47 (defvar whitespace-running-emacs (if (string-match "XEmacs\\|Lucid"
49 "If this is Emacs, not XEmacs, this is t.")
51 (if whitespace-running-emacs (require 'timer))
53 (defvar whitespace-all-buffer-files nil
54 "An associated list of buffers and files checked for whitespace cleanliness.
56 This is to enable periodic checking of whitespace cleanliness in the files
57 visited by the buffers.")
59 (defvar whitespace-rescan-timer nil
60 "Timer object used to rescan the files in buffers that have been modified.")
62 ;; For users of Emacs 19.x, defgroup and defcustom are not defined.
65 (if (< (string-to-int emacs-version) 20)
67 (defmacro defgroup (sym memb doc &rest args)
68 "Null macro for defgroup in all versions of Emacs < 20.x"
70 (defmacro defcustom (sym val doc &rest args)
71 "Macro to alias defcustom to defvar in all versions of Emacs < 20.x"
72 `(defvar ,sym ,val ,doc)))))
74 (defgroup whitespace nil
75 "Check for and fix five different types of whitespaces in source code."
76 ;; Since XEmacs doesn't have a 'convenience group, use the next best group
78 :group (if whitespace-running-emacs 'convenience 'editing))
80 (defcustom whitespace-check-leading-whitespace t
81 "Flag to check leading whitespace."
85 (defcustom whitespace-check-trailing-whitespace t
86 "Flag to check trailing whitespace."
90 (defcustom whitespace-check-spacetab-whitespace t
91 "Flag to check space followed by a TAB."
95 (defcustom whitespace-spacetab-regexp " \t"
96 "Regexp to match a space followed by a TAB."
100 (defcustom whitespace-check-indent-whitespace t
101 "Flag to check indentation whitespace."
105 (defcustom whitespace-indent-regexp (concat "^\\(\t*\\) " " ")
106 "Regexp to match (any TABS followed by) 8/more whitespaces at start of line."
110 (defcustom whitespace-check-ateol-whitespace t
111 "Flag to check end-of-line whitespace."
115 (defcustom whitespace-ateol-regexp "[ \t]$"
116 "Regexp to match a TAB or a space at the EOL."
120 (defcustom whitespace-errbuf "*Whitespace Errors*"
121 "The buffer where whitespace related messages will be logged."
125 (defcustom whitespace-auto-cleanup nil
126 "Cleanup a buffer automatically on finding it whitespace unclean."
130 (defcustom whitespace-silent nil
131 "All whitespace errors will be shown only in the modeline when t.
133 Note that setting this may cause all whitespaces introduced in a file to go
134 unnoticed when the buffer is killed, unless the user visits the `*Whitespace
135 Errors*' buffer before opening (or closing) another file."
139 (defcustom whitespace-modes '(ada-mode asm-mode autoconf-mode awk-mode
140 c-mode c++-mode cc-mode
141 change-log-mode cperl-mode
142 electric-nroff-mode emacs-lisp-mode
143 f90-mode fortran-mode html-mode
144 html3-mode java-mode jde-mode
145 ksh-mode latex-mode LaTeX-mode
146 lisp-mode m4-mode makefile-mode
147 modula-2-mode nroff-mode objc-mode
148 pascal-mode perl-mode prolog-mode
149 python-mode scheme-mode sgml-mode
150 sh-mode shell-script-mode simula-mode
151 tcl-mode tex-mode texinfo-mode
154 "Major Modes in which we turn on whitespace checking.
156 These are mostly programming and documentation modes. But you may add other
157 modes that you want whitespaces checked in by adding something like the
158 following to your `.emacs':
160 \(setq whitespace-modes (cons 'my-mode (cons 'my-other-mode
163 Or, alternately, you can use the Emacs `customize' command to set this."
166 (defcustom whitespace-rescan-timer-time 60
167 "Period in seconds to rescan modified buffers for whitespace creep.
169 This is the period after which the timer will fire causing
170 `whitespace-rescan-files-in-buffers' to check for whitespace creep in
173 To disable timer scans, set this to zero."
177 ;; Tell Emacs about this new kind of minor mode
178 (defvar whitespace-mode nil
179 "Non-nil when Whitespace mode (a minor mode) is enabled.")
180 (make-variable-buffer-local 'whitespace-mode)
181 (put 'whitespace-mode 'permanent-local nil)
183 (defvar whitespace-mode-line nil
184 "String to display in the mode line for Whitespace mode.")
185 (make-variable-buffer-local 'whitespace-mode-line)
186 (put 'whitespace-mode-line 'permanent-local nil)
188 (if (not (assoc 'whitespace-mode minor-mode-alist))
189 (setq minor-mode-alist (cons '(whitespace-mode whitespace-mode-line)
192 (defun whitespace-check-whitespace-mode (&optional arg)
193 "Test and set the whitespace-mode in qualifying buffers."
194 (if (null whitespace-mode)
195 (setq whitespace-mode
196 (if (or arg (member major-mode whitespace-modes))
201 (defun whitespace-buffer (&optional quiet)
202 "Find five different types of white spaces in buffer:
204 1. Leading space \(empty lines at the top of a file\).
205 2. Trailing space \(empty lines at the end of a file\).
206 3. Indentation space \(8 or more spaces, that should be replaced with TABS\).
207 4. Spaces followed by a TAB. \(Almost always, we never want that\).
208 5. Spaces or TABS at the end of a line.
210 Check for whitespace only if this buffer really contains a non-empty file
212 1. the major mode is one of the whitespace-modes, or
213 2. `whitespace-buffer' was explicitly called with a prefix argument."
215 (whitespace-check-whitespace-mode current-prefix-arg)
216 (if (and buffer-file-name (> (buffer-size) 0) whitespace-mode)
218 (whitespace-check-buffer-list (buffer-name) buffer-file-name)
219 (whitespace-tickle-timer)
220 (if whitespace-auto-cleanup
221 (if (and (not quiet) buffer-read-only)
222 (message "Can't Cleanup: %s is read-only." (buffer-name))
223 (whitespace-cleanup))
224 (let ((whitespace-leading (if whitespace-check-leading-whitespace
225 (whitespace-buffer-leading)
227 (whitespace-trailing (if whitespace-check-trailing-whitespace
228 (whitespace-buffer-trailing)
230 (whitespace-indent (if whitespace-check-indent-whitespace
231 (whitespace-buffer-search
232 whitespace-indent-regexp)
234 (whitespace-spacetab (if whitespace-check-spacetab-whitespace
235 (whitespace-buffer-search
236 whitespace-spacetab-regexp)
238 (whitespace-ateol (if whitespace-check-ateol-whitespace
239 (whitespace-buffer-search
240 whitespace-ateol-regexp)
242 (whitespace-errmsg nil)
243 (whitespace-error nil)
244 (whitespace-filename buffer-file-name)
245 (whitespace-this-modeline ""))
247 ;; Now let's complain if we found any of the above.
248 (setq whitespace-error (or whitespace-leading whitespace-indent
249 whitespace-spacetab whitespace-ateol
250 whitespace-trailing))
254 (setq whitespace-errmsg
255 (concat whitespace-filename " contains:\n"
256 (if whitespace-leading "Leading whitespace\n")
257 (if whitespace-indent
258 (concat "Indentation whitespace"
259 whitespace-indent "\n"))
260 (if whitespace-spacetab
261 (concat "Space followed by Tab"
262 whitespace-spacetab "\n"))
264 (concat "End-of-line whitespace"
265 whitespace-ateol "\n"))
266 (if whitespace-trailing
267 "Trailing whitespace.\n")
269 "`whitespace-cleanup' to cleanup the file."))
270 (setq whitespace-this-modeline
271 (concat (if whitespace-ateol "e")
272 (if whitespace-indent "i")
273 (if whitespace-leading "l")
274 (if whitespace-spacetab "s")
275 (if whitespace-trailing "t")))
276 (setq whitespace-mode-line
277 (concat " W:" whitespace-this-modeline))
278 (whitespace-force-mode-line-update)))
280 ;; Now test and set the whitespaces that are not checked.
281 (whitespace-display-unchecked-whitespaces
283 (concat " W:" whitespace-this-modeline)))
285 (get-buffer-create whitespace-errbuf)
286 (kill-buffer whitespace-errbuf)
287 (get-buffer-create whitespace-errbuf)
288 (set-buffer whitespace-errbuf)
289 (if whitespace-errmsg
291 (insert whitespace-errmsg)
292 (if (not (or quiet whitespace-silent))
293 (display-buffer whitespace-errbuf t))
295 (message "Whitespaces: [%s] in %s"
296 whitespace-this-modeline
297 whitespace-filename)))
299 (message "%s clean" whitespace-filename)))))))))
302 (defun whitespace-region (s e)
303 "Check a region specified by point and mark for whitespace errors."
307 (narrow-to-region s e)
308 (whitespace-buffer))))
311 (defun whitespace-cleanup ()
312 "Cleanup the five different kinds of whitespace problems.
314 Use \\[describe-function] whitespace-describe to read a summary of the
315 whitespace problems."
317 ;; If this buffer really contains a file, then run, else quit.
318 (whitespace-check-whitespace-mode current-prefix-arg)
319 (if (and buffer-file-name whitespace-mode)
320 (let ((whitespace-any nil)
321 (whitespace-tabwith 8)
322 (whitespace-tabwith-saved tab-width))
324 ;; since all printable TABS should be 8, irrespective of how
325 ;; they are displayed.
326 (setq tab-width whitespace-tabwith)
328 (if (and whitespace-check-leading-whitespace
329 (whitespace-buffer-leading))
331 (whitespace-buffer-leading-cleanup)
332 (setq whitespace-any t)))
334 (if (and whitespace-check-trailing-whitespace
335 (whitespace-buffer-trailing))
337 (whitespace-buffer-trailing-cleanup)
338 (setq whitespace-any t)))
340 (if (and whitespace-check-indent-whitespace
341 (whitespace-buffer-search whitespace-indent-regexp))
343 (whitespace-indent-cleanup)
344 (setq whitespace-any t)))
346 (if (and whitespace-check-spacetab-whitespace
347 (whitespace-buffer-search whitespace-spacetab-regexp))
349 (whitespace-buffer-cleanup whitespace-spacetab-regexp "\t")
350 (setq whitespace-any t)))
352 (if (and whitespace-check-ateol-whitespace
353 (whitespace-buffer-search whitespace-ateol-regexp))
355 (whitespace-buffer-cleanup whitespace-ateol-regexp "")
356 (setq whitespace-any t)))
358 ;; Call this recursively till everything is taken care of
362 (message "%s clean" buffer-file-name)
363 (setq whitespace-mode-line nil)
364 (whitespace-force-mode-line-update)
365 (whitespace-display-unchecked-whitespaces)))
366 (setq tab-width whitespace-tabwith-saved))))
369 (defun whitespace-cleanup-region (s e)
370 "Whitespace cleanup on a region specified by point and mark."
374 (narrow-to-region s e)
375 (whitespace-cleanup))
376 (whitespace-buffer t)))
378 (defun whitespace-buffer-leading ()
379 "Check to see if there are any empty lines at the top of the file."
383 (goto-char (point-min))
388 (if (equal pmin pmax)
392 (defun whitespace-buffer-leading-cleanup ()
393 "Remove any empty lines at the top of the file."
397 (goto-char (point-min))
402 (if (equal pmin pmax)
405 (whitespace-buffer-leading-cleanup))))))
407 (defun whitespace-buffer-trailing ()
408 "Check to see if are is more than one empty line at the bottom."
412 (goto-char (point-max))
417 (if (equal pmin pmax)
419 (goto-char (- (point) 1))
424 (if (equal pmin pmax)
429 (defun whitespace-buffer-trailing-cleanup ()
430 "Delete all the empty lines at the bottom."
434 (goto-char (point-max))
439 (if (equal pmin pmax)
441 (goto-char (1- pmin))
446 (if (equal pmin pmax)
448 (goto-char (1- (point-max)))
451 (whitespace-buffer-trailing-cleanup))))))))
453 (defun whitespace-buffer-search (regexp)
454 "Search for any given whitespace REGEXP."
455 (let ((whitespace-retval ""))
457 (goto-char (point-min))
458 (while (re-search-forward regexp nil t)
459 (setq whitespace-retval (format "%s %s " whitespace-retval
460 (match-beginning 0))))
461 (if (equal "" whitespace-retval)
463 whitespace-retval))))
465 (defun whitespace-buffer-cleanup (regexp newregexp)
466 "Search for any given whitespace REGEXP and replace it with the NEWREGEXP."
468 (goto-char (point-min))
469 (while (re-search-forward regexp nil t)
470 (replace-match newregexp))))
472 (defun whitespace-indent-cleanup ()
473 "Search for 8/more spaces at the start of a line and replace it with tabs."
475 (goto-char (point-min))
476 (while (re-search-forward whitespace-indent-regexp nil t)
477 (let ((column (current-column))
478 (indent-tabs-mode t))
479 (delete-region (match-beginning 0) (point))
480 (indent-to column)))))
482 (defun whitespace-display-unchecked-whitespaces (&optional whitespace-str)
483 "Update modeline with whitespaces whose testing has been turned off."
484 (let ((whitespace-this-modeline
485 (concat (if (not whitespace-check-ateol-whitespace) "e")
486 (if (not whitespace-check-indent-whitespace) "i")
487 (if (not whitespace-check-leading-whitespace) "l")
488 (if (not whitespace-check-spacetab-whitespace) "s")
489 (if (not whitespace-check-trailing-whitespace) "t"))))
490 (setq whitespace-mode-line whitespace-str)
491 (if (not (equal whitespace-this-modeline ""))
492 (setq whitespace-mode-line
493 (concat whitespace-str " Woff:" whitespace-this-modeline)))
494 (whitespace-force-mode-line-update)))
496 ;; Force mode line updation for different Emacs versions
497 (defun whitespace-force-mode-line-update ()
498 "Force the mode line update for different flavors of Emacs."
499 (if whitespace-running-emacs
500 (force-mode-line-update) ; Emacs
501 (redraw-modeline))) ; XEmacs
503 (defun whitespace-check-buffer-list (buf-name buf-file)
504 "Add a buffer and its file to the whitespace monitor list.
506 The buffer named BUF-NAME and its associated file BUF-FILE are now monitored
507 periodically for whitespace."
508 (if (and whitespace-mode (not (member (list buf-file buf-name)
509 whitespace-all-buffer-files)))
510 (add-to-list 'whitespace-all-buffer-files (list buf-file buf-name))))
512 (defun whitespace-tickle-timer ()
513 "Tickle timer to periodically to scan qualifying files for whitespace creep.
515 If timer is not set, then set it to scan the files in
516 `whitespace-all-buffer-files' periodically (defined by
517 `whitespace-rescan-timer-time') for whitespace creep."
518 (if (and whitespace-rescan-timer-time (not whitespace-rescan-timer))
519 (setq whitespace-rescan-timer
520 (if whitespace-running-emacs
521 (run-at-time nil whitespace-rescan-timer-time
522 'whitespace-rescan-files-in-buffers)
523 (add-timeout whitespace-rescan-timer-time
524 'whitespace-rescan-files-in-buffers nil
525 whitespace-rescan-timer-time)))))
527 (defun whitespace-rescan-files-in-buffers (&optional arg)
528 "Check monitored files for whitespace creep since last scan."
529 (let ((whitespace-all-my-files whitespace-all-buffer-files)
530 buffile bufname thiselt buf)
531 (if (not whitespace-all-my-files)
533 (if whitespace-running-emacs
534 (cancel-timer whitespace-rescan-timer)
535 (disable-timeout whitespace-rescan-timer))
536 (setq whitespace-rescan-timer nil))
537 (while whitespace-all-my-files
538 (setq thiselt (car whitespace-all-my-files))
539 (setq whitespace-all-my-files (cdr whitespace-all-my-files))
540 (setq buffile (car thiselt))
541 (setq bufname (cadr thiselt))
542 (setq buf (get-buffer bufname))
543 (if (buffer-live-p buf)
545 ;;(message "buffer %s live" bufname)
549 ;;(message "checking for whitespace in %s" bufname)
550 (if whitespace-auto-cleanup
552 ;;(message "cleaning up whitespace in %s" bufname)
553 (whitespace-cleanup))
555 ;;(message "whitespace-buffer %s." (buffer-name))
556 (whitespace-buffer t))))
557 ;;(message "Removing %s from refresh list" bufname)
558 (whitespace-refresh-rescan-list buffile bufname)))
559 ;;(message "Removing %s from refresh list" bufname)
560 (whitespace-refresh-rescan-list buffile bufname))))))
562 (defun whitespace-refresh-rescan-list (buffile bufname)
563 "Refresh the list of files to be rescaned for whitespace creep."
564 (if whitespace-all-buffer-files
566 (setq whitespace-all-buffer-files
567 (delete (list buffile bufname) whitespace-all-buffer-files)))
569 (if (and whitespace-running-emacs (timerp whitespace-rescan-timer))
570 (cancel-timer whitespace-rescan-timer))
571 (if (and (not whitespace-running-emacs) whitespace-rescan-timer)
572 (disable-timeout whitespace-rescan-timer))
573 (if whitespace-rescan-timer
574 (setq whitespace-rescan-timer nil)))))
577 (defun whitespace-describe ()
578 "A summary of whitespaces and what this library can do about them.
580 The whitespace library is intended to find and help fix five different types
581 of whitespace problems that commonly exist in source code.
583 1. Leading space (empty lines at the top of a file).
584 2. Trailing space (empty lines at the end of a file).
585 3. Indentation space (8 or more spaces at beginning of line, that should be
587 4. Spaces followed by a TAB. (Almost always, we never want that).
588 5. Spaces or TABS at the end of a line.
590 Whitespace errors are reported in a buffer, and on the modeline.
592 Modeline will show a W:<x> to denote a particular type of whitespace, where
593 `x' can be one (or more) of:
595 e - End-of-Line whitespace.
596 i - Indentation whitespace.
597 l - Leading whitespace.
598 s - Space followed by Tab.
599 t - Trailing whitespace.
601 If any of the whitespace checks is turned off, the modeline will display a
602 Woff:<x>, where `x' can be one (or more) of the above.
604 (since (3) is the most controversial one, here is the rationale: Most
605 terminal drivers and printer drivers have TAB configured or even
606 hardcoded to be 8 spaces. (Some of them allow configuration, but almost
607 always they default to 8.)
609 Changing tab-width to other than 8 and editing will cause your code to
610 look different from within Emacs, and say, if you cat it or more it, or
613 Almost all the popular programming modes let you define an offset (like
614 c-basic-offset or perl-indent-level) to configure the offset, so you
615 should never have to set your tab-width to be other than 8 in all these
616 modes. In fact, with an indent level of say, 4, 2 TABS will cause Emacs
617 to replace your 8 spaces with one \t (try it). If vi users in your
618 office complain, tell them to use vim, which distinguishes between
619 tabstop and shiftwidth (vi equivalent of our offsets), and also ask them
622 All the above have caused (and will cause) unwanted codeline integration and
625 whitespace.el will complain if it detects whitespaces on opening a file, and
626 warn you on closing a file also. (if in case you had inserted any
627 whitespaces during the process of your editing.)"
629 (message "Use C-h f whitespace-describe to read about whitespace.el v%s."
632 (provide 'whitespace)
634 ;;; whitespace.el ends here