jit-lock.el 17 KB
Newer Older
Gerd Moellmann's avatar
Gerd Moellmann committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
;;; jit-lock.el --- just-in-time fontification.

;; Copyright (C) 1998 Free Software Foundation, Inc.

;; Author: Gerd Moellmann <gerd@gnu.org>
;; Keywords: faces files
;; Version: 1.0

;; This file is part of GNU Emacs.

;; GNU Emacs 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.

;; GNU Emacs 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., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.

;;; Commentary:

;; Just-in-time fontification, triggered by C redisplay code.

;;; Code:


(eval-when-compile
34 35 36 37
  (defmacro with-buffer-unmodified (&rest body)
    "Eval BODY, preserving the current buffer's modified state."
    (let ((modified (make-symbol "modified")))
      `(let ((,modified (buffer-modified-p)))
38 39 40 41
	 (unwind-protect
	     (progn ,@body)
	   (unless ,modified
	     (restore-buffer-modified-p nil))))))
42
  
43
  (defmacro with-buffer-prepared-for-jit-lock (&rest body)
Gerd Moellmann's avatar
Gerd Moellmann committed
44 45
    "Execute BODY in current buffer, overriding several variables.
Preserves the `buffer-modified-p' state of the current buffer."
Gerd Moellmann's avatar
Gerd Moellmann committed
46 47 48 49
    `(with-buffer-unmodified
      (let ((buffer-undo-list t)
	    (inhibit-read-only t)
	    (inhibit-point-motion-hooks t)
50
	    (inhibit-modification-hooks t)
Gerd Moellmann's avatar
Gerd Moellmann committed
51 52 53 54
	    deactivate-mark
	    buffer-file-name
	    buffer-file-truename)
	,@body))))
Gerd Moellmann's avatar
Gerd Moellmann committed
55

56
  
Gerd Moellmann's avatar
Gerd Moellmann committed
57 58 59 60

;;; Customization.

(defcustom jit-lock-chunk-size 500
61
  "*Jit-lock chunks of this many characters, or smaller."
Gerd Moellmann's avatar
Gerd Moellmann committed
62 63 64 65 66 67 68
  :type 'integer
  :group 'jit-lock)


(defcustom jit-lock-stealth-time 3
  "*Time in seconds to wait before beginning stealth fontification.
Stealth fontification occurs if there is no input within this time.
69
If nil, stealth fontification is never performed.
Gerd Moellmann's avatar
Gerd Moellmann committed
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138

The value of this variable is used when JIT Lock mode is turned on."
  :type '(choice (const :tag "never" nil)
		 (number :tag "seconds"))
  :group 'jit-lock)


(defcustom jit-lock-stealth-nice 0.125
  "*Time in seconds to pause between chunks of stealth fontification.
Each iteration of stealth fontification is separated by this amount of time,
thus reducing the demand that stealth fontification makes on the system.
If nil, means stealth fontification is never paused.
To reduce machine load during stealth fontification, at the cost of stealth
taking longer to fontify, you could increase the value of this variable.
See also `jit-lock-stealth-load'."
  :type '(choice (const :tag "never" nil)
		 (number :tag "seconds"))	  
  :group 'jit-lock)
 

(defcustom jit-lock-stealth-load
  (if (condition-case nil (load-average) (error)) 200)
  "*Load in percentage above which stealth fontification is suspended.
Stealth fontification pauses when the system short-term load average (as
returned by the function `load-average' if supported) goes above this level,
thus reducing the demand that stealth fontification makes on the system.
If nil, means stealth fontification is never suspended.
To reduce machine load during stealth fontification, at the cost of stealth
taking longer to fontify, you could reduce the value of this variable.
See also `jit-lock-stealth-nice'."
  :type (if (condition-case nil (load-average) (error))
	    '(choice (const :tag "never" nil)
		     (integer :tag "load"))
	  '(const :format "%t: unsupported\n" nil))
  :group 'jit-lock)


(defcustom jit-lock-stealth-verbose nil
  "*If non-nil, means stealth fontification should show status messages."
  :type 'boolean
  :group 'jit-lock)


(defcustom jit-lock-defer-contextually 'syntax-driven
  "*If non-nil, means deferred fontification should be syntactically true.
If nil, means deferred fontification occurs only on those lines modified.  This
means where modification on a line causes syntactic change on subsequent lines,
those subsequent lines are not refontified to reflect their new context.
If t, means deferred fontification occurs on those lines modified and all
subsequent lines.  This means those subsequent lines are refontified to reflect
their new syntactic context, either immediately or when scrolling into them.
If any other value, e.g., `syntax-driven', means deferred syntactically true
fontification occurs only if syntactic fontification is performed using the
buffer mode's syntax table, i.e., only if `font-lock-keywords-only' is nil.

The value of this variable is used when JIT Lock mode is turned on."
  :type '(choice (const :tag "never" nil)
		 (const :tag "always" t)
		 (other :tag "syntax-driven" syntax-driven))
  :group 'jit-lock)



;;; Variables that are not customizable.

(defvar jit-lock-mode nil
  "Non-nil means Just-in-time Lock mode is active.")
(make-variable-buffer-local 'jit-lock-mode)

139 140 141
(defvar jit-lock-functions nil
  "Functions to do the actual fontification.
They are called with two arguments: the START and END of the region to fontify.")
142
(make-variable-buffer-local 'jit-lock-functions)
Gerd Moellmann's avatar
Gerd Moellmann committed
143 144

(defvar jit-lock-first-unfontify-pos nil
145
  "Consider text after this position as contextually unfontified.
146
If nil, contextual fontification is disabled.")
Gerd Moellmann's avatar
Gerd Moellmann committed
147 148 149 150 151 152 153 154 155 156
(make-variable-buffer-local 'jit-lock-first-unfontify-pos)


(defvar jit-lock-stealth-timer nil
  "Timer for stealth fontification in Just-in-time Lock mode.")

;;; JIT lock mode

(defun jit-lock-mode (arg)
  "Toggle Just-in-time Lock mode.
157
Turn Just-in-time Lock mode on if and only if ARG is non-nil.
Gerd Moellmann's avatar
Gerd Moellmann committed
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
Enable it automatically by customizing group `font-lock'.

When Just-in-time Lock mode is enabled, fontification is different in the
following ways:

- Demand-driven buffer fontification triggered by Emacs C code.
  This means initial fontification of the whole buffer does not occur.
  Instead, fontification occurs when necessary, such as when scrolling
  through the buffer would otherwise reveal unfontified areas.  This is
  useful if buffer fontification is too slow for large buffers.

- Stealthy buffer fontification if `jit-lock-stealth-time' is non-nil.
  This means remaining unfontified areas of buffers are fontified if Emacs has
  been idle for `jit-lock-stealth-time' seconds, while Emacs remains idle.
  This is useful if any buffer has any deferred fontification.

- Deferred context fontification if `jit-lock-defer-contextually' is
  non-nil.  This means fontification updates the buffer corresponding to
  true syntactic context, after `jit-lock-stealth-time' seconds of Emacs
  idle time, while Emacs remains idle.  Otherwise, fontification occurs
  on modified lines only, and subsequent lines can remain fontified
  corresponding to previous syntactic contexts.  This is useful where
  strings or comments span lines.

Stealth fontification only occurs while the system remains unloaded.
If the system load rises above `jit-lock-stealth-load' percent, stealth
fontification is suspended.  Stealth fontification intensity is controlled via
185
the variable `jit-lock-stealth-nice'."
186 187 188 189
  (setq jit-lock-mode arg)
  (cond (;; Turn Just-in-time Lock mode on.
	 jit-lock-mode

190 191
 	 ;; Mark the buffer for refontification
	 (jit-lock-refontify)
192

Gerd Moellmann's avatar
Gerd Moellmann committed
193
	 ;; Install an idle timer for stealth fontification.
194
	 (when (and jit-lock-stealth-time (null jit-lock-stealth-timer))
195
	   (setq jit-lock-stealth-timer
Gerd Moellmann's avatar
Gerd Moellmann committed
196 197 198 199
		 (run-with-idle-timer jit-lock-stealth-time
				      jit-lock-stealth-time
				      'jit-lock-stealth-fontify)))

200
	 ;; Initialize deferred contextual fontification if requested.
201
	 (when (eq jit-lock-defer-contextually t)
202 203
	   (setq jit-lock-first-unfontify-pos
		 (or jit-lock-first-unfontify-pos (point-max))))
204

205
	 ;; Setup our hooks.
206
	 (add-hook 'after-change-functions 'jit-lock-after-change nil t)
Gerd Moellmann's avatar
Gerd Moellmann committed
207 208 209 210 211 212 213 214 215
	 (add-hook 'fontification-functions 'jit-lock-function))

	;; Turn Just-in-time Lock mode off.
	(t
	 ;; Cancel our idle timer.
	 (when jit-lock-stealth-timer
	   (cancel-timer jit-lock-stealth-timer)
	   (setq jit-lock-stealth-timer nil))

216
	 ;; Remove hooks.
217
	 (remove-hook 'after-change-functions 'jit-lock-after-change t)
Gerd Moellmann's avatar
Gerd Moellmann committed
218 219
	 (remove-hook 'fontification-functions 'jit-lock-function))))

220 221
;;;###autoload
(defun jit-lock-register (fun &optional contextual)
222 223
  "Register FUN as a fontification function to be called in this buffer.
FUN will be called with two arguments START and END indicating the region
224 225
that needs to be (re)fontified.
If non-nil, CONTEXTUAL means that a contextual fontification would be useful."
226
  (add-hook 'jit-lock-functions fun nil t)
227 228
  (when (and contextual jit-lock-defer-contextually)
    (set (make-local-variable 'jit-lock-defer-contextually) t))
229 230 231
  (jit-lock-mode t))

(defun jit-lock-unregister (fun)
232
  "Unregister FUN as a fontification function.
233 234
Only applies to the current buffer."
  (remove-hook 'jit-lock-functions fun t)
235
  (unless jit-lock-functions (jit-lock-mode nil)))
Gerd Moellmann's avatar
Gerd Moellmann committed
236

237 238 239 240
;; This function is used to prevent font-lock-fontify-buffer from
;; fontifying eagerly the whole buffer.  This is important for
;; things like CWarn mode which adds/removes a few keywords and
;; does a refontify (which takes ages on large files).
241 242
(defun jit-lock-refontify (&optional beg end)
  "Force refontification of the region BEG..END (default whole buffer)."
243
  (with-buffer-prepared-for-jit-lock
244 245
   (save-restriction
     (widen)
246 247
     (add-text-properties (or beg (point-min)) (or end (point-max))
			  '(fontified nil)))))
Gerd Moellmann's avatar
Gerd Moellmann committed
248 249 250 251 252 253 254 255

;;; On demand fontification.

(defun jit-lock-function (start)
  "Fontify current buffer starting at position START.
This function is added to `fontification-functions' when `jit-lock-mode'
is active."
  (when jit-lock-mode
256
    (jit-lock-fontify-now start (+ start jit-lock-chunk-size))))
257
     
258 259 260 261

(defun jit-lock-fontify-now (&optional start end)
  "Fontify current buffer from START to END.
Defaults to the whole buffer.  END can be out of bounds."
262
  (with-buffer-prepared-for-jit-lock
263 264 265
   (save-excursion
     (save-restriction
       (widen)
266 267 268
       (unless start (setq start (point-min)))
       (setq end (if end (min end (point-max)) (point-max)))
       (let ((font-lock-beginning-of-syntax-function nil)
269
	     next)
270
	 (save-match-data
271 272 273 274 275 276 277 278 279 280 281 282 283 284
	   ;; Fontify chunks beginning at START.  The end of a
	   ;; chunk is either `end', or the start of a region
	   ;; before `end' that has already been fontified.
	   (while start
	     ;; Determine the end of this chunk.
	     (setq next (or (text-property-any start end 'fontified t)
			    end))

	     ;; Decide which range of text should be fontified.
	     ;; The problem is that START and NEXT may be in the
	     ;; middle of something matched by a font-lock regexp.
	     ;; Until someone has a better idea, let's start
	     ;; at the start of the line containing START and
	     ;; stop at the start of the line following NEXT.
285 286 287
	     (goto-char next)  (setq next (line-beginning-position 2))
	     (goto-char start) (setq start (line-beginning-position))
	     
288 289 290 291
	     ;; Fontify the chunk, and mark it as fontified.
	     ;; We mark it first, to make sure that we don't indefinitely
	     ;; re-execute this fontification if an error occurs.
	     (add-text-properties start next '(fontified t))
292
	     (run-hook-with-args 'jit-lock-functions start next)
Gerd Moellmann's avatar
Gerd Moellmann committed
293
		   
294 295
	     ;; Find the start of the next chunk, if any.
	     (setq start (text-property-any next end 'fontified nil)))))))))
Gerd Moellmann's avatar
Gerd Moellmann committed
296 297 298 299 300 301 302


;;; Stealth fontification.

(defsubst jit-lock-stealth-chunk-start (around)
  "Return the start of the next chunk to fontify around position AROUND..
Value is nil if there is nothing more to fontify."
303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322
  (if (zerop (buffer-size))
      nil
    (save-restriction
      (widen)
      (let* ((next (text-property-any around (point-max) 'fontified nil))
	     (prev (previous-single-property-change around 'fontified))
	     (prop (get-text-property (max (point-min) (1- around))
				      'fontified))
	     (start (cond
		     ((null prev)
		      ;; There is no property change between AROUND
		      ;; and the start of the buffer.  If PROP is
		      ;; non-nil, everything in front of AROUND is
		      ;; fontified, otherwise nothing is fontified.
		      (if prop
			  nil
			(max (point-min)
			     (- around (/ jit-lock-chunk-size 2)))))
		     (prop
		      ;; PREV is the start of a region of fontified
323
		      ;; text containing AROUND.  Start fontifying a
324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340
		      ;; chunk size before the end of the unfontified
		      ;; region in front of that.
		      (max (or (previous-single-property-change prev 'fontified)
			       (point-min))
			   (- prev jit-lock-chunk-size)))
		     (t
		      ;; PREV is the start of a region of unfontified
		      ;; text containing AROUND.  Start at PREV or
		      ;; chunk size in front of AROUND, whichever is
		      ;; nearer.
		      (max prev (- around jit-lock-chunk-size)))))
	     (result (cond ((null start) next)
			   ((null next) start)
			   ((< (- around start) (- next around)) start)
			   (t next))))
	result))))
	
Gerd Moellmann's avatar
Gerd Moellmann committed
341 342 343 344 345 346 347 348 349 350

(defun jit-lock-stealth-fontify ()
  "Fontify buffers stealthily.
This functions is called after Emacs has been idle for
`jit-lock-stealth-time' seconds."
  (unless (or executing-kbd-macro
	      (window-minibuffer-p (selected-window)))
    (let ((buffers (buffer-list))
	  minibuffer-auto-raise
	  message-log-max)
351
      (while (and buffers (not (input-pending-p)))
Gerd Moellmann's avatar
Gerd Moellmann committed
352 353
	(let ((buffer (car buffers)))
	  (setq buffers (cdr buffers))
354
	  
Gerd Moellmann's avatar
Gerd Moellmann committed
355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373
	  (with-current-buffer buffer
	    (when jit-lock-mode
	      ;; This is funny.  Calling sit-for with 3rd arg non-nil
	      ;; so that it doesn't redisplay, internally calls
	      ;; wait_reading_process_input also with a parameter
	      ;; saying "don't redisplay."  Since this function here
	      ;; is called periodically, this effectively leads to
	      ;; process output not being redisplayed at all because
	      ;; redisplay_internal is never called.  (That didn't
	      ;; work in the old redisplay either.)  So, we learn that
	      ;; we mustn't call sit-for that way here.  But then, we
	      ;; have to be cautious not to call sit-for in a widened
	      ;; buffer, since this could display hidden parts of that
	      ;; buffer.  This explains the seemingly weird use of
	      ;; save-restriction/widen here.

	      (with-temp-message (if jit-lock-stealth-verbose
				     (concat "JIT stealth lock "
					     (buffer-name)))
374

Gerd Moellmann's avatar
Gerd Moellmann committed
375 376 377 378 379 380
		;; Perform deferred unfontification, if any.
		(when jit-lock-first-unfontify-pos
		  (save-restriction
		    (widen)
		    (when (and (>= jit-lock-first-unfontify-pos (point-min))
			       (< jit-lock-first-unfontify-pos (point-max)))
381
		      (with-buffer-prepared-for-jit-lock
Gerd Moellmann's avatar
Gerd Moellmann committed
382 383
		       (put-text-property jit-lock-first-unfontify-pos
					  (point-max) 'fontified nil))
384
		      (setq jit-lock-first-unfontify-pos (point-max)))))
Gerd Moellmann's avatar
Gerd Moellmann committed
385 386 387 388 389 390 391 392 393 394 395 396

		;; In the following code, the `sit-for' calls cause a
		;; redisplay, so it's required that the
		;; buffer-modified flag of a buffer that is displayed
		;; has the right value---otherwise the mode line of
		;; an unmodified buffer would show a `*'.
		(let (start
		      (nice (or jit-lock-stealth-nice 0))
		      (point (point)))
		  (while (and (setq start
				    (jit-lock-stealth-chunk-start point))
			      (sit-for nice))
Gerd Moellmann's avatar
Gerd Moellmann committed
397
		    
Gerd Moellmann's avatar
Gerd Moellmann committed
398 399 400 401
		    ;; Wait a little if load is too high.
		    (when (and jit-lock-stealth-load
			       (> (car (load-average)) jit-lock-stealth-load))
		      (sit-for (or jit-lock-stealth-time 30)))
Gerd Moellmann's avatar
Gerd Moellmann committed
402
		    
Gerd Moellmann's avatar
Gerd Moellmann committed
403 404
		    ;; Unless there's input pending now, fontify.
		    (unless (input-pending-p)
405 406
		      (jit-lock-fontify-now
		       start (+ start jit-lock-chunk-size)))))))))))))
Gerd Moellmann's avatar
Gerd Moellmann committed
407 408 409 410 411 412 413 414 415 416 417 418 419 420



;;; Deferred fontification.

(defun jit-lock-after-change (start end old-len)
  "Mark the rest of the buffer as not fontified after a change.
Installed on `after-change-functions'.
START and END are the start and end of the changed text.  OLD-LEN
is the pre-change length.
This function ensures that lines following the change will be refontified
in case the syntax of those lines has changed.  Refontification
will take place when text is fontified stealthily."
  (when jit-lock-mode
421 422
    (save-excursion
      (with-buffer-prepared-for-jit-lock
423 424
       ;; If we're in text that matches a multi-line font-lock pattern,
       ;; make sure the whole text will be redisplayed.
425 426
       (when (and font-lock-multiline
		  (get-text-property start 'font-lock-multiline))
427 428 429 430
	 (setq start (or (previous-single-property-change
			  start 'font-lock-multiline)
			 (point-min))))
       
431 432 433 434 435 436
       ;; It's important that the `fontified' property be set from the
       ;; beginning of the line, else font-lock will properly change the
       ;; text's face, but the display will have been done already and will
       ;; be inconsistent with the buffer's content.
       (goto-char start)
       (setq start (line-beginning-position))
437
       
438 439 440 441 442 443 444 445
       ;; Make sure we change at least one char (in case of deletions).
       (setq end (min (max end (1+ start)) (point-max)))
       ;; Request refontification.
       (put-text-property start end 'fontified nil))
      ;; Mark the change for deferred contextual refontification.
      (when jit-lock-first-unfontify-pos
	(setq jit-lock-first-unfontify-pos
	      (min jit-lock-first-unfontify-pos start))))))
Gerd Moellmann's avatar
Gerd Moellmann committed
446 447 448 449
  
(provide 'jit-lock)

;; jit-lock.el ends here