lisp/font-core.el

   1 ;;; font-core.el --- Core interface to font-lock
   2
   3 ;; Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
   4 ;;   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
   5 ;;   Free Software Foundation, Inc.
   6
   7 ;; Maintainer: FSF
   8 ;; Keywords: languages, faces
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software: you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation, either version 3 of the License, or
  15 ;; (at your option) any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  24
  25 ;;; Code:
  26
  27 ;; This variable is used by mode packages that support Font Lock mode by
  28 ;; defining their own keywords to use for `font-lock-keywords'.  (The mode
  29 ;; command should make it buffer-local and set it to provide the set up.)
  30 (defvar font-lock-defaults nil
  31   "Defaults for Font Lock mode specified by the major mode.
  32 Defaults should be of the form:
  33
  34  (KEYWORDS [KEYWORDS-ONLY [CASE-FOLD [SYNTAX-ALIST [SYNTAX-BEGIN ...]]]])
  35
  36 KEYWORDS may be a symbol (a variable or function whose value is the keywords
  37 to use for fontification) or a list of symbols (specifying different levels
  38 of fontification).
  39
  40 If KEYWORDS-ONLY is non-nil, syntactic fontification (strings and
  41 comments) is not performed.
  42
  43 If CASE-FOLD is non-nil, the case of the keywords is ignored when fontifying.
  44
  45 If SYNTAX-ALIST is non-nil, it should be a list of cons pairs of the form
  46 \(CHAR-OR-STRING . STRING) used to set the local Font Lock syntax table, for
  47 keyword and syntactic fontification (see `modify-syntax-entry').
  48
  49 If SYNTAX-BEGIN is non-nil, it should be a function with no args used to move
  50 backwards outside any enclosing syntactic block, for syntactic fontification.
  51 Typical values are `beginning-of-line' (i.e., the start of the line is known to
  52 be outside a syntactic block), or `beginning-of-defun' for programming modes or
  53 `backward-paragraph' for textual modes (i.e., the mode-dependent function is
  54 known to move outside a syntactic block).  If nil, the beginning of the buffer
  55 is used as a position outside of a syntactic block, in the worst case.
  56
  57 \(See also Info node `(elisp)Font Lock Basics'.)
  58
  59 These item elements are used by Font Lock mode to set the variables
  60 `font-lock-keywords', `font-lock-keywords-only',
  61 `font-lock-keywords-case-fold-search', `font-lock-syntax-table' and
  62 `font-lock-beginning-of-syntax-function', respectively.
  63
  64 Further item elements are alists of the form (VARIABLE . VALUE) and are in no
  65 particular order.  Each VARIABLE is made buffer-local before set to VALUE.
  66
  67 Currently, appropriate variables include `font-lock-mark-block-function'.
  68 If this is non-nil, it should be a function with no args used to mark any
  69 enclosing block of text, for fontification via \\[font-lock-fontify-block].
  70 Typical values are `mark-defun' for programming modes or `mark-paragraph' for
  71 textual modes (i.e., the mode-dependent function is known to put point and mark
  72 around a text block relevant to that mode).
  73
  74 Other variables include that for syntactic keyword fontification,
  75 `font-lock-syntactic-keywords' and those for buffer-specialized fontification
  76 functions, `font-lock-fontify-buffer-function',
  77 `font-lock-unfontify-buffer-function', `font-lock-fontify-region-function',
  78 `font-lock-unfontify-region-function', and `font-lock-inhibit-thing-lock'.")
  79 ;;;###autoload
  80 (put 'font-lock-defaults 'risky-local-variable t)
  81 (make-variable-buffer-local 'font-lock-defaults)
  82
  83 (defvar font-lock-defaults-alist nil
  84   "Alist of fall-back Font Lock defaults for major modes.
  85
  86 Each item should be a list of the form:
  87
  88  (MAJOR-MODE . FONT-LOCK-DEFAULTS)
  89
  90 where MAJOR-MODE is a symbol and FONT-LOCK-DEFAULTS is a list of default
  91 settings.  See the variable `font-lock-defaults', which takes precedence.")
  92 (make-obsolete-variable 'font-lock-defaults-alist 'font-lock-defaults "21.1")
  93
  94 (defvar font-lock-function 'font-lock-default-function
  95   "A function which is called when `font-lock-mode' is toggled.
  96 It will be passed one argument, which is the current value of
  97 `font-lock-mode'.")
  98
  99 ;; The mode for which font-lock was initialized, or nil if none.
 100 (defvar font-lock-major-mode)
 101 (define-minor-mode font-lock-mode
 102   "Toggle Font Lock mode.
 103 With arg, turn Font Lock mode off if and only if arg is a non-positive
 104 number; if arg is nil, toggle Font Lock mode; anything else turns Font
 105 Lock on.
 106 \(Font Lock is also known as \"syntax highlighting\".)
 107
 108 When Font Lock mode is enabled, text is fontified as you type it:
 109
 110  - Comments are displayed in `font-lock-comment-face';
 111  - Strings are displayed in `font-lock-string-face';
 112  - Certain other expressions are displayed in other faces according to the
 113    value of the variable `font-lock-keywords'.
 114
 115 To customize the faces (colors, fonts, etc.) used by Font Lock for
 116 fontifying different parts of buffer text, use \\[customize-face].
 117
 118 You can enable Font Lock mode in any major mode automatically by turning on in
 119 the major mode's hook.  For example, put in your ~/.emacs:
 120
 121  (add-hook 'c-mode-hook 'turn-on-font-lock)
 122
 123 Alternatively, you can use Global Font Lock mode to automagically turn on Font
 124 Lock mode in buffers whose major mode supports it and whose major mode is one
 125 of `font-lock-global-modes'.  For example, put in your ~/.emacs:
 126
 127  (global-font-lock-mode t)
 128
 129 Where major modes support different levels of fontification, you can use
 130 the variable `font-lock-maximum-decoration' to specify which level you
 131 generally prefer.  When you turn Font Lock mode on/off the buffer is
 132 fontified/defontified, though fontification occurs only if the buffer is
 133 less than `font-lock-maximum-size'.
 134
 135 To add your own highlighting for some major mode, and modify the highlighting
 136 selected automatically via the variable `font-lock-maximum-decoration', you can
 137 use `font-lock-add-keywords'.
 138
 139 To fontify a buffer, without turning on Font Lock mode and regardless of buffer
 140 size, you can use \\[font-lock-fontify-buffer].
 141
 142 To fontify a block (the function or paragraph containing point, or a number of
 143 lines around point), perhaps because modification on the current line caused
 144 syntactic change on other lines, you can use \\[font-lock-fontify-block].
 145
 146 See the variable `font-lock-defaults-alist' for the Font Lock mode default
 147 settings.  You can set your own default settings for some mode, by setting a
 148 buffer local value for `font-lock-defaults', via its mode hook.
 149
 150 The above is the default behavior of `font-lock-mode'; you may specify
 151 your own function which is called when `font-lock-mode' is toggled via
 152 `font-lock-function'. "
 153   nil nil nil
 154   ;; Don't turn on Font Lock mode if we don't have a display (we're running a
 155   ;; batch job) or if the buffer is invisible (the name starts with a space).
 156   (when (or noninteractive (eq (aref (buffer-name) 0) ?\s))
 157     (setq font-lock-mode nil))
 158   (funcall font-lock-function font-lock-mode)
 159   ;; Arrange to unfontify this buffer if we change major mode later.
 160   (if font-lock-mode
 161       (add-hook 'change-major-mode-hook 'font-lock-change-mode nil t)
 162     (remove-hook 'change-major-mode-hook 'font-lock-change-mode t)))
 163
 164 ;; Get rid of fontification for the old major mode.
 165 ;; We do this when changing major modes.
 166 (defun font-lock-change-mode ()
 167   (font-lock-mode -1))
 168
 169 (defun font-lock-defontify ()
 170   "Clear out all `font-lock-face' properties in current buffer.
 171 A major mode that uses `font-lock-face' properties might want to put
 172 this function onto `change-major-mode-hook'."
 173   (let ((modp (buffer-modified-p))
 174         (inhibit-read-only t))
 175     (save-restriction
 176       (widen)
 177       (remove-list-of-text-properties (point-min) (point-max)
 178                                       '(font-lock-face)))
 179     (restore-buffer-modified-p modp)))
 180
 181 (defvar font-lock-set-defaults)
 182 (defun font-lock-default-function (mode)
 183   ;; Turn on Font Lock mode.
 184   (when mode
 185     (set (make-local-variable 'char-property-alias-alist)
 186          (copy-tree char-property-alias-alist))
 187     ;; Add `font-lock-face' as an alias for the `face' property.
 188     (let ((elt (assq 'face char-property-alias-alist)))
 189       (if elt
 190           (unless (memq 'font-lock-face (cdr elt))
 191             (setcdr elt (nconc (cdr elt) (list 'font-lock-face))))
 192         (push (list 'face 'font-lock-face) char-property-alias-alist))))
 193   ;; Turn off Font Lock mode.
 194   (unless mode
 195     ;; Remove `font-lock-face' as an alias for the `face' property.
 196     (set (make-local-variable 'char-property-alias-alist)
 197          (copy-tree char-property-alias-alist))
 198     (let ((elt (assq 'face char-property-alias-alist)))
 199       (when elt
 200         (setcdr elt (remq 'font-lock-face (cdr elt)))
 201         (when (null (cdr elt))
 202           (setq char-property-alias-alist
 203                 (delq elt char-property-alias-alist))))))
 204
 205   ;; Only do hard work if the mode has specified stuff in
 206   ;; `font-lock-defaults'.
 207   (when (or font-lock-defaults
 208             (if (boundp 'font-lock-keywords) font-lock-keywords)
 209             (with-no-warnings
 210               (cdr (assq major-mode font-lock-defaults-alist)))
 211             (and mode
 212                  (boundp 'font-lock-set-defaults)
 213                  font-lock-set-defaults
 214                  font-lock-major-mode
 215                  (not (eq font-lock-major-mode major-mode))))
 216     (font-lock-mode-internal mode)))
 217
 218 (defun turn-on-font-lock ()
 219   "Turn on Font Lock mode (only if the terminal can display it)."
 220   (unless font-lock-mode
 221     (font-lock-mode)))
 222
 223 ;;; Global Font Lock mode.
 224
 225 ;; A few people have hassled in the past for a way to make it easier to turn on
 226 ;; Font Lock mode, without the user needing to know for which modes s/he has to
 227 ;; turn it on, perhaps the same way hilit19.el/hl319.el does.  I've always
 228 ;; balked at that way, as I see it as just re-moulding the same problem in
 229 ;; another form.  That is; some person would still have to keep track of which
 230 ;; modes (which may not even be distributed with Emacs) support Font Lock mode.
 231 ;; The list would always be out of date.  And that person might have to be me.
 232
 233 ;; Implementation.
 234 ;;
 235 ;; In a previous discussion the following hack came to mind.  It is a gross
 236 ;; hack, but it generally works.  We use the convention that major modes start
 237 ;; by calling the function `kill-all-local-variables', which in turn runs
 238 ;; functions on the hook variable `change-major-mode-hook'.  We attach our
 239 ;; function `font-lock-change-major-mode' to that hook.  Of course, when this
 240 ;; hook is run, the major mode is in the process of being changed and we do not
 241 ;; know what the final major mode will be.  So, `font-lock-change-major-mode'
 242 ;; only (a) notes the name of the current buffer, and (b) adds our function
 243 ;; `turn-on-font-lock-if-desired' to the hook variables
 244 ;; `after-change-major-mode-hook' and `post-command-hook' (for modes
 245 ;; that do not yet run `after-change-major-mode-hook').  By the time
 246 ;; the functions on the first of these hooks to be run are run, the new major
 247 ;; mode is assumed to be in place.  This way we get a Font Lock function run
 248 ;; when a major mode is turned on, without knowing major modes or their hooks.
 249 ;;
 250 ;; Naturally this requires that major modes run `kill-all-local-variables'
 251 ;; and `after-change-major-mode-hook', as they are supposed to.  For modes
 252 ;; that do not run `after-change-major-mode-hook' yet, `post-command-hook'
 253 ;; takes care of things if the mode is set directly or indirectly by
 254 ;; an interactive command; however, problems can occur if the mode is
 255 ;; set by a timer or process: in that case, proper handling of Font Lock mode
 256 ;; may be delayed until the next interactive command.
 257
 258 ;; User interface.
 259 ;;
 260 ;; Although Global Font Lock mode is a pseudo-mode, I think that the user
 261 ;; interface should conform to the usual Emacs convention for modes, i.e., a
 262 ;; command to toggle the feature (`global-font-lock-mode') with a variable for
 263 ;; finer control of the mode's behavior (`font-lock-global-modes').
 264 ;;
 265 ;; The feature should not be enabled by loading font-lock.el, since other
 266 ;; mechanisms for turning on Font Lock mode, such as M-x font-lock-mode RET or
 267 ;; (add-hook 'c-mode-hook 'turn-on-font-lock), would cause Font Lock mode to be
 268 ;; turned on everywhere.  That would not be intuitive or informative because
 269 ;; loading a file tells you nothing about the feature or how to control it.  It
 270 ;; would also be contrary to the Principle of Least Surprise.  sm.
 271
 272 (defcustom font-lock-global-modes t
 273   "Modes for which Font Lock mode is automagically turned on.
 274 Global Font Lock mode is controlled by the command `global-font-lock-mode'.
 275 If nil, means no modes have Font Lock mode automatically turned on.
 276 If t, all modes that support Font Lock mode have it automatically turned on.
 277 If a list, it should be a list of `major-mode' symbol names for which Font Lock
 278 mode should be automatically turned on.  The sense of the list is negated if it
 279 begins with `not'.  For example:
 280  (c-mode c++-mode)
 281 means that Font Lock mode is turned on for buffers in C and C++ modes only."
 282   :type '(choice (const :tag "none" nil)
 283                  (const :tag "all" t)
 284                  (set :menu-tag "mode specific" :tag "modes"
 285                       :value (not)
 286                       (const :tag "Except" not)
 287                       (repeat :inline t (symbol :tag "mode"))))
 288   :group 'font-lock)
 289
 290 (defun turn-on-font-lock-if-desired ()
 291   (when (cond ((eq font-lock-global-modes t)
 292                t)
 293               ((eq (car-safe font-lock-global-modes) 'not)
 294                (not (memq major-mode (cdr font-lock-global-modes))))
 295               (t (memq major-mode font-lock-global-modes)))
 296     (let (inhibit-quit)
 297       (turn-on-font-lock))))
 298
 299 (define-globalized-minor-mode global-font-lock-mode
 300   font-lock-mode turn-on-font-lock-if-desired
 301   ;; What was this :extra-args thingy for?  --Stef
 302   ;; :extra-args (dummy)
 303   :initialize 'custom-initialize-delay
 304   :init-value (not (or noninteractive emacs-basic-display))
 305   :group 'font-lock
 306   :version "22.1")
 307
 308 ;;; End of Global Font Lock mode.
 309
 310 (provide 'font-core)
 311
 312 ;; arch-tag: f8c286e1-02f7-41d9-b89b-1b67780aed71
 313 ;;; font-core.el ends here