blank-mode.el v5.1

[Vinicius Jose Latorre]

blank-mode.el v5.1

;;; blank-mode --- Minor mode to visualise blanks (SPACE, HARD SPACE and TAB).

;; Copyright (C) 2000, 2001, 2006 Vinicius Jose Latorre

;; Author: Vinicius Jose Latorre <address@hidden>
;; Maintainer: Vinicius Jose Latorre <address@hidden>
;; Keywords: data, wp
;; Time-stamp: <2006/12/21 16:56:43 vinicius>
;; Version: 5.1
;; X-URL: http://www.emacswiki.org/cgi-bin/wiki/ViniciusJoseLatorre

;; This file is *NOT* (yet?) part of GNU Emacs.

;; This program is free software; you can redistribute it and/or modify it
;; under the terms of the GNU General Public License as published by the Free
;; Software Foundation; either version 2, or (at your option) any later
;; version.

;; This program is distributed in the hope that it will be useful, but WITHOUT
;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
;; FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
;; more details.

;; You should have received a copy of the GNU General Public License along with
;; GNU Emacs; see the file COPYING.  If not, write to the Free Software
;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 
USA.

;;; Commentary:

;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;; Introduction
;; ------------
;;
;; This package is a minor mode to visualise blanks (SPACE, HARD SPACE and
;; TAB).
;;
;; blank-mode uses two ways to visualise blanks: faces and display table.
;;
;; Faces are used to highlight the background with a color.  blank-mode uses
;; font-lock to highlight blank characters.
;;
;; Display table change the way a character is displayed, that is, it provides
;; a visual mark for characters, for example, at the end of line (?\xB6), at
;; spaces (?\xB7) and at tabs (?\xBB).
;;
;; The `blank-style' and `blank-chars' variables are used to select which way
;; should be used to visualise blanks.
;;
;; To use blank-mode, insert in your ~/.emacs:
;;
;;    (require 'blank-mode)
;;
;; Or:
;;
;;    (autoload 'blank-mode-on        "blank-mode"
;;      "Turn on blank visualisation."   t)
;;    (autoload 'blank-mode-off       "blank-mode"
;;      "Turn off blank visualisation."  t)
;;    (autoload 'blank-mode           "blank-mode"
;;      "Toggle blank visualisation."    t)
;;    (autoload 'blank-mode-customize "blank-mode"
;;      "Customize blank visualisation." t)
;;
;; For good performance, be sure to byte-compile blank-mode.el, e.g.
;;
;;    M-x byte-compile-file <give the path to blank-mode.el when prompted>
;;
;; This will generate blank-mode.elc, which will be loaded instead of
;; blank-mode.el.
;;
;; blank-mode was tested with GNU Emacs 20.6.1, 21 and 22.
;;
;;
;; Using blank-mode
;; ----------------
;;
;; To activate blank-mode, type:
;;
;;    M-x blank-mode-on RET
;;
;; Or:
;;
;;    C-u 1 M-x blank-mode RET
;;
;; To deactivate blank-mode, type:
;;
;;    M-x blank-mode-off RET
;;
;; Or:
;;
;;    C-u 0 M-x blank-mode RET
;;
;; To toggle blank-mode, type:
;;
;;    M-x blank-mode RET
;;
;; To customize blank-mode, type:
;;
;;    M-x blank-mode-customize RET
;;
;; You can also bind `blank-mode', `blank-mode-on', `blank-mode-off' and
;; `blank-mode-customize' to some key, like:
;;
;;    (global-set-key "\C-c\C-a" 'blank-mode-on)
;;    (global-set-key "\C-c\C-e" 'blank-mode-off)
;;    (global-set-key "\C-c\C-t" 'blank-mode)
;;    (global-set-key "\C-c\C-c" 'blank-mode-customize)
;;
;;
;; Hooks
;; -----
;;
;; blank-mode has the following hook variables:
;;
;; `blank-mode-hook'
;;    It is evaluated always when blank-mode is turned on.
;;
;; `blank-load-hook'
;;    It is evaluated after blank-mode package is loaded.
;;
;;
;; Options
;; -------
;;
;; Below it's shown a brief description of blank-mode options, please, see the
;; options declaration in the code for a long documentation.
;;
;; `blank-verbose'              Non-nil means generate messages.
;;
;; `blank-style'                Specify the visualisation style.
;;
;; `blank-chars'                Specify which kind of blank is visualised.
;;
;; `blank-space-face'           Face used to visualise SPACE.
;;
;; `blank-hspace-face'          Face used to visualise HARD SPACE.
;;
;; `blank-tab-face'             Face used to visualise TAB.
;;
;; `blank-map-face'             Face used to visualise NEWLINE char mapping.
;;
;; `blank-trailing-face'        Face used to visualise trailing blanks.
;;
;; `blank-space-regexp'         Specify space characters regexp.
;;
;; `blank-hspace-regexp'        Specify hard space characters regexp.
;;
;; `blank-tab-regexp'           Specify tab characters regexp.
;;
;; `blank-trailing-regexp'      Specify trailing characters regexp.
;;
;; `blank-display-mappings'     Specify an alist of mappings for displaying
;;                              characters.
;;
;; To set the above options you may:
;;
;; a) insert the code in your ~/.emacs, like:
;;
;;       (setq blank-space-face 'underline)
;;
;;    This way always keep your default settings when you enter a new Emacs
;;    session.
;;
;; b) or use `set-variable' in your Emacs session, like:
;;
;;       M-x set-variable RET blank-space-face RET underline RET
;;
;;    This way keep your settings only during the current Emacs session.
;;
;; c) or use customization, for example:
;;       click on menu-bar *Help* option,
;;       then click on *Customize*,
;;       then click on *Browse Customization Groups*,
;;       expand *Data* group,
;;       expand *Blank* group
;;       and then customize blank-mode options.
;;    Through this way, you may choose if the settings are kept or not when
;;    you leave out the current Emacs session.
;;
;; d) or see the option value:
;;
;;       C-h v blank-space-face RET
;;
;;    and click the *customize* hypertext button.
;;    Through this way, you may choose if the settings are kept or not when
;;    you leave out the current Emacs session.
;;
;; e) or invoke:
;;
;;       M-x blank-mode-customize RET
;;
;;    and then customize blank-mode options.
;;    Through this way, you may choose if the settings are kept or not when
;;    you leave out the current Emacs session.
;;
;;
;; Acknowledgements
;; ----------------
;;
;; Thanks to Yanghui Bian <address@hidden> for indicating a new
;; newline character mapping.
;;
;; Thanks to Pete Forman <address@hidden> for indicating
;; whitespace-mode on XEmacs.
;;
;; Thanks to:
;;    Aurelien Tisne <address@hidden>   show-whitespace-mode.el
;;    Lawrence Mitchell <address@hidden>                whitespace-mode.el
;;    Miles Bader <address@hidden>              visws.el
;; And to all people who contributed with them.
;;
;;
;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;;; code:


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; User Variables:


;;; Interface to the command system


(defgroup blank nil
  "Visualise blanks (SPACE, HARD SPACE and TAB)."
  :link '(emacs-library-link :tag "Source Lisp File" "blank-mode.el")
  :group 'wp
  :group 'data)


(defcustom blank-verbose t
  "*Non-nil means generate messages."
  :type 'boolean
  :group 'blank)


(defcustom blank-style '(mark color)
  "*Specify the visualisation style.

It's a list which element value can be:

   'mark        display mappings are visualised.

   'color       faces are visualised.

Any other value is ignored.

If it's nil, don't visualise TABs, SPACEs and HARD SPACEs.

See also `blank-display-mappings' for documentation."
  :type '(repeat :tag "Style of Blank"
                 (choice :tag "Style of Blank"
                         (const :tag "Display Table" mark)
                         (const :tag "Faces" color)))
  :group 'blank)


(defcustom blank-chars '(tabs spaces trailing)
  "*Specify which kind of blank is visualised.

It's a list which element value can be:

   'trailing    trailing blanks are visualised.

   'tabs        TABs are visualised.

   'spaces      SPACEs and HARD SPACEs are visualised.

Any other element value is ignored.

If it's nil, don't visualise TABs, SPACEs and HARD SPACEs.

Used when `blank-style' has 'color as an element."
  :type '(repeat :tag "Kind of Blank"
                 (choice :tag "Kind of Blank"
                         (const :tag "Trailing TABs, SPACEs and HARD SPACEs"
                                trailing)
                         (const :tag "SPACEs and HARD SPACEs" spaces)
                         (const :tag "TABs" tabs)))
  :group 'blank)


(defcustom blank-space-face 'blank-space-face
  "*Symbol face used to visualise SPACE.

Used when `blank-style' has 'color as an element."
  :type 'face
  :group 'blank)


(defface blank-space-face
  '((t (:background "LightYellow" :foreground "Aquamarine3")))
  "Face used to visualise SPACE.")


(defcustom blank-hspace-face 'blank-hspace-face ; 'nobreak-space
  "*Symbol face used to visualise HARD SPACE.

Used when `blank-style' has 'color as an element."
  :type 'face
  :group 'blank)


(defface blank-hspace-face
  '((t (:background "LemonChiffon3" :foreground "Aquamarine3")))
  "Face used to visualise HARD SPACE.")


(defcustom blank-tab-face 'blank-tab-face
  "*Symbol face used to visualise TAB.

Used when `blank-style' has 'color as an element."
  :type 'face
  :group 'blank)


(defface blank-tab-face
  '((((class mono)) :inverse-video t)
    (t (:background "Beige" :foreground "Aquamarine3")))
  "Face used to visualise TAB.")


(defcustom blank-map-face 'blank-map-face
  "*Symbol face used to visualise NEWLINE char mapping.  See 
`blank-display-mappings'.

Used when `blank-style' has 'mark as an element."
  :type 'face
  :group 'blank)


(defface blank-map-face
  '((((class mono)) (:bold t :underline t))
    (t (:background "Linen" :foreground "Aquamarine3" :bold t)))
  "Face used to visualise NEWLINE char mapping.  See `blank-display-mappings'.")


(defcustom blank-trailing-face 'blank-trailing-face ; 'trailing-whitespace
  "*Symbol face used to visualise traling blanks.

Used when `blank-style' has 'color as an element."
  :type 'face
  :group 'blank)


(defface blank-trailing-face
  '((((class mono)) (:bold t :underline t))
    (t (:background "red1" :foreground "yellow" :bold t)))
  "Face used to visualise trailing blanks.")


(defcustom blank-hspace-regexp "\\(\xA0+\\)"
  "*Specify hard space characters regexp.

If you're using `mule' package, it may exists other characters besides \"\\xA0\"
that it should be considered hard space.

Here are some examples:

   \"\\\\(^\\xA0+\\\\)\"                visualise only leading hard spaces.
   \"\\\\(\\xA0+$\\\\)\"                visualise only trailing hard spaces.
   \"\\\\(^\\xA0+\\\\|\\xA0+$\\\\)\"    visualise leading and/or trailing hard 
spaces.
   \"\\t\\\\(\\xA0+\\\\)\\t\"           visualise only hard spaces between tabs.

NOTE: Enclose always by \\\\( and \\\\) the elements to highlight.
      Use exactly one pair of enclosing \\\\( and \\\\).

Used when `blank-style' has 'color as an element, and `blank-chars' has
'spaces as an element."
  :type '(regexp :tag "Hard Space Chars")
  :group 'blank)


(defcustom blank-space-regexp "\\( +\\)"
  "*Specify space characters regexp.

If you're using `mule' package, it may exists other characters besides \" \"
that it should be considered space.

Here are some examples:

   \"\\\\(^ +\\\\)\"            visualise only leading spaces.
   \"\\\\( +$\\\\)\"            visualise only trailing spaces.
   \"\\\\(^ +\\\\| +$\\\\)\"    visualise leading and/or trailing spaces.
   \"\\t\\\\( +\\\\)\\t\"       visualise only spaces between tabs.

NOTE: Enclose always by \\\\( and \\\\) the elements to highlight.
      Use exactly one pair of enclosing \\\\( and \\\\).

Used when `blank-style' has 'color as an element, and `blank-chars' has
'spaces as an element."
  :type '(regexp :tag "Space Chars")
  :group 'blank)


(defcustom blank-tab-regexp "\\(\t+\\)"
  "*Specify tab characters regexp.

If you're using `mule' package, it may exists other characters besides \"\\t\"
that it should be considered tab.

Here are some examples:

   \"\\\\(^\\t+\\\\)\"          visualise only leading tabs.
   \"\\\\(\\t+$\\\\)\"          visualise only trailing tabs.
   \"\\\\(^\\t+\\\\|\\t+$\\\\)\"        visualise leading and/or trailing tabs.
   \" \\\\(\\t+\\\\) \" visualise only tabs between spaces.

NOTE: Enclose always by \\\\( and \\\\) the elements to highlight.
      Use exactly one pair of enclosing \\\\( and \\\\).

Used when `blank-style' has 'color as an element, and `blank-chars' has 'tabs
as an element."
  :type '(regexp :tag "Tab Chars")
  :group 'blank)


(defcustom blank-trailing-regexp "\t\\| \\|\xA0"
  "*Specify trailing characters regexp.

If you're using `mule' package, it may exists other characters besides \" \",
\"\\t\" or \"\\xA0\" that it should be considered blank.

NOTE: DOES NOT enclose by \\\\( and \\\\) the elements to highlight.
      `blank-mode' surrounds this regexp by \"\\\\(\\\\(\" and
      \"\\\\)+\\\\)$\".

Used when `blank-style' has 'color as an element, and `blank-chars' has
'trailing as an element."
  :type '(regexp :tag "Trailing Chars")
  :group 'blank)


;; Hacked from `visible-whitespace-mappings' in visws.el
(defcustom blank-display-mappings
  '((?\    [?\xB7]     [?.])            ; space
    (?\xA0 [?\xA4]     [?_])            ; hard space
    (?\n   [?\xB6 ?\n] [?$ ?\n])        ; end-of-line
    ;; WARNING: the mapping below has a problem.
    ;; When a tab occupies exactly one column, it will display the character
    ;; ?\xBB at that column followed by a tab which goes to the next tab
    ;; column.
    ;; If this is a problem for you, please, comment the line below.
    (?\t   [?\xBB ?\t] [?\\ ?\t])       ; tab
    )
  "*Specify an alist of mappings for displaying characters.

Each element has the following form:

   (CHAR VECTOR...)

Where:

CHAR    Is the character to be mapped.

VECTOR  Is a vector of characters to be displayed in place of CHAR.
        The first display vector that can be displayed is used; if no display
        vector for a mapping can be displayed, then that character is
        displayed unmodified.

The NEWLINE character is displayed using the face given by `blank-map-face'
variable.

Used when `blank-style' has 'mark as an element."
  :type '(repeat
          (list :tag "Character Mapping"
                (character :tag "Char")
                (repeat :inline t :tag "Vector List"
                        (vector :tag ""
                                (repeat :inline t :tag "Vector Characters"
                                        (character :tag "Char"))))))
  :group 'blank)


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Macros


(defmacro blank-message (&rest body)
  (` (and blank-verbose (interactive-p)
          (message (,@ body)))))


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Customization


;;;###autoload
(defun blank-mode-customize ()
  "Customize blank-mode options."
  (interactive)
  (customize-group 'blank))


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; User commands


(defvar blank-mode nil)
(make-variable-buffer-local 'blank-mode)

(defvar blank-active-style nil)
(make-variable-buffer-local 'blank-active-style)


;;;###autoload
(defun blank-mode (&optional arg)
  "Toggle blank visualisation.

If ARG is null, toggle blank visualisation.
If ARG is a number and is greater than zero, turn on visualisation; otherwise,
turn off visualisation."
  (interactive "P")
  (if (if arg
          (> (prefix-numeric-value arg) 0)
        (not blank-mode))
      (blank-mode-on)
    (blank-mode-off))
  (blank-message "Blank Mode is now %s." (if blank-mode "on" "off")))


;;;###autoload
(defun blank-mode-on ()
  "Turn on blank visualisation."
  (interactive)
  (or (and (boundp 'blank-mode) blank-mode)
      (when blank-style
        (setq blank-mode         t
              blank-active-style blank-style)
        (and (memq 'color blank-active-style)
             (blank-color-on))
        (and (memq 'mark  blank-active-style)
             (blank-display-char-on))
        (run-hooks 'blank-mode-hook)
        (blank-message "Blank Mode is now on."))))


;;;###autoload
(defun blank-mode-off ()
  "Turn off blank visualisation."
  (interactive)
  (and (boundp 'blank-mode) blank-mode
       (progn
         (setq blank-mode nil)
         (and (memq 'color blank-active-style)
              (blank-color-off))
         (and (memq 'mark  blank-active-style)
              (blank-display-char-off))
         (blank-message "Blank Mode is now off."))))


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Internal functions


(defvar blank-font-lock-keywords nil)
(make-variable-buffer-local 'blank-font-lock-keywords)

(defvar blank-active-chars nil)
(make-variable-buffer-local 'blank-active-chars)


(defun blank-color-on ()
  (setq blank-active-chars blank-chars)
  (when blank-active-chars
    (setq blank-font-lock-keywords font-lock-keywords)
    (and (memq 'spaces blank-active-chars)
         (font-lock-add-keywords
          nil
          (list
           ;; Show spaces
           (list blank-space-regexp  1 blank-space-face  t)
           ;; Show hard spaces
           (list blank-hspace-regexp 1 blank-hspace-face t))
          t))
    (and (memq 'tabs blank-active-chars)
         (font-lock-add-keywords
          nil
          (list
           ;; Show tabs
           (list blank-tab-regexp 1 blank-tab-face t))
          t))
    (and (memq 'trailing blank-active-chars)
         (font-lock-add-keywords
          nil
          (list
           ;; Show trailing blanks
           (list (concat "\\(\\(" blank-trailing-regexp "\\)+\\)$")
                 1 blank-trailing-face t))
          t))
  (font-lock-fontify-buffer)))


(defun blank-color-off ()
  (when blank-active-chars
    (setq font-lock-keywords blank-font-lock-keywords)
    (font-lock-fontify-buffer)))


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Hacked from visws.el


(defun blank-legal-display-vector-p (vec)
  "Return true if every character in the display vector VEC can be displayed."
  (let ((i (length vec)))
    (when (> i 0)
      ;; This check should be improved!!!
      (while (and (>= (setq i (1- i)) 0)
                  (or (< (aref vec i) 256)
                      (char-valid-p (aref vec i)))))
      (< i 0))))


;; Buffer local variable used to remember whether a buffer initially had a
;; local display table or not.
(defvar blank-display-table-was-local nil)
(make-variable-buffer-local 'blank-display-table-was-local)


(defun blank-display-char-on ()
  "Turn on character display mapping."
  (and blank-display-mappings
       (let ((face-bits (ash (face-id blank-map-face) 19))
             (map-list blank-display-mappings)
             entry vecs len vec i)
         ;; Remember whether a buffer has a local display table.
         (setq blank-display-table-was-local
               (copy-sequence buffer-display-table))
         (or buffer-display-table
             (setq buffer-display-table (make-display-table)))
         (while map-list
           (setq entry    (car map-list)
                 vecs     (cdr entry)
                 map-list (cdr map-list))
           ;; Get a displayable mapping.
           (while (and vecs (not (blank-legal-display-vector-p (car vecs))))
             (setq vecs (cdr vecs)))
           ;; Display a valid mapping.
           (when vecs
             (setq vec (copy-sequence (car vecs)))
             ;; Only insert face bits on NEWLINE char mapping to avoid
             ;; obstruction of other faces like TABs and (HARD) SPACEs faces,
             ;; font-lock faces, etc.
             (when (eq (car entry) ?\n)
               (setq len (length (car vecs))
                     i -1)
               (while (< (setq i (1+ i)) len)
                 (or (eq (aref vec i) ?\n)
                     (aset vec i (logior (aref vec i) face-bits)))))
             (aset buffer-display-table (car entry) vec))))))


(defun blank-display-char-off ()
  "Turn off character display mapping."
  (and blank-display-mappings
       (setq buffer-display-table blank-display-table-was-local)))


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;


(add-to-list 'minor-mode-alist '(blank-mode " Bl"))


(provide 'blank-mode)


(run-hooks 'blank-load-hook)


;;; blank-mode.el ends here