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