| blob | 9d700a5ed827825f2983effb97aa6ece5bba7c23 |
1 ;;; jit-lock.el --- just-in-time fontification -*- lexical-binding: t -*-
3 ;; Copyright (C) 1998, 2000-2013 Free Software Foundation, Inc.
5 ;; Author: Gerd Moellmann <gerd@gnu.org>
6 ;; Keywords: faces files
7 ;; Package: emacs
9 ;; This file is part of GNU Emacs.
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 3 of the License, or
14 ;; (at your option) any later version.
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.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
24 ;;; Commentary:
26 ;; Just-in-time fontification, triggered by C redisplay code.
28 ;;; Code:
33 "Execute BODY in current buffer, overriding several variables.
34 Preserves the `buffer-modified-p' state of the current buffer."
39 \f
40 ;;; Customization.
43 "Font Lock support mode to fontify just-in-time."
48 "Jit-lock fontifies chunks of at most this many characters at a time.
50 This variable controls both display-time and stealth fontification."
56 "Time in seconds to wait before beginning stealth fontification.
57 Stealth fontification occurs if there is no input within this time.
58 If nil, stealth fontification is never performed.
60 The value of this variable is used when JIT Lock mode is turned on."
67 "Time in seconds to pause between chunks of stealth fontification.
68 Each iteration of stealth fontification is separated by this amount of time,
69 thus reducing the demand that stealth fontification makes on the system.
70 If nil, means stealth fontification is never paused.
71 To reduce machine load during stealth fontification, at the cost of stealth
72 taking longer to fontify, you could increase the value of this variable.
73 See also `jit-lock-stealth-load'."
81 "Load in percentage above which stealth fontification is suspended.
82 Stealth fontification pauses when the system short-term load average (as
83 returned by the function `load-average' if supported) goes above this level,
84 thus reducing the demand that stealth fontification makes on the system.
85 If nil, means stealth fontification is never suspended.
86 To reduce machine load during stealth fontification, at the cost of stealth
87 taking longer to fontify, you could reduce the value of this variable.
88 See also `jit-lock-stealth-nice'."
97 "If non-nil, means stealth fontification should show status messages."
104 "If non-nil, means fontification should be syntactically true.
105 If nil, means fontification occurs only on those lines modified. This
106 means where modification on a line causes syntactic change on subsequent lines,
107 those subsequent lines are not refontified to reflect their new context.
108 If t, means fontification occurs on those lines modified and all
109 subsequent lines. This means those subsequent lines are refontified to reflect
110 their new syntactic context, after `jit-lock-context-time' seconds.
111 If any other value, e.g., `syntax-driven', means syntactically true
112 fontification occurs only if syntactic fontification is performed using the
113 buffer mode's syntax table, i.e., only if `font-lock-keywords-only' is nil.
115 The value of this variable is used when JIT Lock mode is turned on."
122 "Idle time after which text is contextually refontified, if applicable."
127 "Idle time after which deferred fontification should take place.
128 If nil, fontification is not deferred."
132 \f
133 ;;; Variables that are not customizable.
139 "Functions to do the actual fontification.
143 "Consider text after this position as contextually unfontified.
159 \f
160 ;;; JIT lock mode
163 "Toggle Just-in-time Lock mode.
164 Turn Just-in-time Lock mode on if and only if ARG is non-nil.
165 Enable it automatically by customizing group `font-lock'.
167 When Just-in-time Lock mode is enabled, fontification is different in the
168 following ways:
170 - Demand-driven buffer fontification triggered by Emacs C code.
171 This means initial fontification of the whole buffer does not occur.
172 Instead, fontification occurs when necessary, such as when scrolling
173 through the buffer would otherwise reveal unfontified areas. This is
174 useful if buffer fontification is too slow for large buffers.
176 - Stealthy buffer fontification if `jit-lock-stealth-time' is non-nil.
177 This means remaining unfontified areas of buffers are fontified if Emacs has
178 been idle for `jit-lock-stealth-time' seconds, while Emacs remains idle.
179 This is useful if any buffer has any deferred fontification.
181 - Deferred context fontification if `jit-lock-contextually' is
182 non-nil. This means fontification updates the buffer corresponding to
183 true syntactic context, after `jit-lock-context-time' seconds of Emacs
184 idle time, while Emacs remains idle. Otherwise, fontification occurs
185 on modified lines only, and subsequent lines can remain fontified
186 corresponding to previous syntactic contexts. This is useful where
187 strings or comments span lines.
189 Stealth fontification only occurs while the system remains unloaded.
190 If the system load rises above `jit-lock-stealth-load' percent, stealth
191 fontification is suspended. Stealth fontification intensity is controlled via
192 the variable `jit-lock-stealth-nice'."
195 jit-lock-mode
197 ;; Mark the buffer for refontification.
200 ;; Install an idle timer for stealth fontification.
206 ;; Create, but do not activate, the idle timer for repeated
207 ;; stealth fontification.
213 ;; Init deferred fontification timer.
219 ;; Initialize contextual fontification if requested.
228 ;; Setup our hooks.
232 ;; Turn Just-in-time Lock mode off.
234 ;; Cancel our idle timers.
236 jit-lock-context-timer)
237 ;; Only if there's no other buffer using them.
252 ;; Remove hooks.
257 "Minor mode to help debug code run from jit-lock.
258 When this minor mode is enabled, jit-lock runs as little code as possible
259 during redisplay and moves the rest to a timer, where things
260 like `debug-on-error' and Edebug can be used."
272 "Fontify what was deferred for debugging."
277 ;; Mark the deferred regions back to `fontified = nil'
281 ;; (message "Jit-Debug %s" (buffer-name))
289 pos 'fontified
298 "Register FUN as a fontification function to be called in this buffer.
299 FUN will be called with two arguments START and END indicating the region
300 that needs to be (re)fontified.
301 If non-nil, CONTEXTUAL means that a contextual fontification would be useful."
308 "Unregister FUN as a fontification function.
309 Only applies to the current buffer."
313 ;; This function is used to prevent font-lock-fontify-buffer from
314 ;; fontifying eagerly the whole buffer. This is important for
315 ;; things like CWarn mode which adds/removes a few keywords and
316 ;; does a refontify (which takes ages on large files).
318 "Force refontification of the region BEG..END (default whole buffer)."
324 \f
325 ;;; On demand fontification.
328 "Fontify current buffer starting at position START.
329 This function is added to `fontification-functions' when `jit-lock-mode'
330 is active."
333 ;; No deferral.
335 ;; Record the buffer for later fontification.
338 ;; Mark the area as defer-fontified so that the redisplay engine
339 ;; is happy and so that the idle timer can find the places to fontify.
343 start 'fontified nil
348 "Fontify current buffer from START to END.
349 Defaults to the whole buffer. END can be out of bounds."
354 ;; This did bind `font-lock-beginning-of-syntax-function' to
355 ;; nil at some point, for an unknown reason. Don't do this; it
356 ;; can make highlighting slow due to expensive calls to
357 ;; `parse-partial-sexp' in function
358 ;; `font-lock-fontify-syntactically-region'. Example: paging
359 ;; from the end of a buffer to its start, can do repeated
360 ;; `parse-partial-sexp' starting from `point-min', which can
361 ;; take a long time in a large buffer.
364 ;; Fontify chunks beginning at START. The end of a
365 ;; chunk is either `end', or the start of a region
366 ;; before `end' that has already been fontified.
368 ;; Determine the end of this chunk.
370 end))
372 ;; Decide which range of text should be fontified.
373 ;; The problem is that START and NEXT may be in the
374 ;; middle of something matched by a font-lock regexp.
375 ;; Until someone has a better idea, let's start
376 ;; at the start of the line containing START and
377 ;; stop at the start of the line following NEXT.
381 ;; Make sure the contextual refontification doesn't re-refontify
382 ;; what's already been refontified.
386 ;; Don't move boundary forward if we have to
387 ;; refontify previous text. Otherwise, we risk moving
388 ;; it past the end of the multiline property and thus
389 ;; forget about this multiline region altogether.
393 ;; Fontify the chunk, and mark it as fontified.
394 ;; We mark it first, to make sure that we don't indefinitely
395 ;; re-execute this fontification if an error occurs.
399 ;; If the user quits (which shouldn't happen in normal on-the-fly
400 ;; jit-locking), make sure the fontification will be performed
401 ;; before displaying the block again.
405 ;; The redisplay engine has already rendered the buffer up-to
406 ;; `orig-start' and won't notice if the above jit-lock-functions
407 ;; changed the appearance of any part of the buffer prior
408 ;; to that. So if `start' is before `orig-start', we need to
409 ;; cause a new redisplay cycle after this one so that any changes
410 ;; are properly reflected on screen.
411 ;; To make such repeated redisplay happen less often, we can
412 ;; eagerly extend the refontified region with
413 ;; jit-lock-after-change-extend-region-functions.
418 ;; Find the start of the next chunk, if any.
422 "Force the display engine to re-render buffer BUF from START to END."
430 ;; Don't cause refontification (it's already been done), but just do
431 ;; some random buffer change, so as to force redisplay.
433 \f
434 ;;; Stealth fontification.
437 "Return the start of the next chunk to fontify around position AROUND.
438 Value is nil if there is nothing more to fontify."
440 nil
447 ;; There is no property change between AROUND
448 ;; and the start of the buffer. If PROP is
449 ;; non-nil, everything in front of AROUND is
450 ;; fontified, otherwise nothing is fontified.
452 nil
456 ;; PREV is the start of a region of fontified
457 ;; text containing AROUND. Start fontifying a
458 ;; chunk size before the end of the unfontified
459 ;; region in front of that.
464 ;; PREV is the start of a region of unfontified
465 ;; text containing AROUND. Start at PREV or
466 ;; chunk size in front of AROUND, whichever is
467 ;; nearer.
473 result)))
476 "Fontify buffers stealthily.
477 This function is called repeatedly after Emacs has become idle for
478 `jit-lock-stealth-time' seconds. Optional argument REPEAT is expected
479 non-nil in a repeated invocation of this function."
480 ;; Cancel timer for repeated invocations.
484 memory-full
486 ;; For first invocation set up `jit-lock-stealth-buffers'.
487 ;; In repeated invocations it's already been set up.
489 jit-lock-stealth-buffers
493 minibuffer-auto-raise
494 message-log-max
495 start)
498 ;; Wait a little if load is too high.
504 ;; Fontify one block of at most `jit-lock-chunk-size'
505 ;; characters.
511 ;; Run again after `jit-lock-stealth-nice' seconds.
513 ;; Nothing to fontify here. Remove this buffer from
514 ;; `jit-lock-stealth-buffers' and run again immediately.
516 ;; Buffer is no longer live. Remove it from
517 ;; `jit-lock-stealth-buffers' and run again immediately.
519 ;; Call us again.
525 \f
526 ;;; Deferred fontification.
529 "Fontify what was deferred."
531 ;; Mark the deferred regions back to `fontified = nil'
535 ;; (message "Jit-Defer %s" (buffer-name))
548 ;; Force fontification of the visible parts.
550 ;; (message "Jit-Defer Now")
552 ;; (message "Jit-Defer Done")
553 )))
557 "Refresh fontification to take new context into account."
562 ;; (message "Jit-Context %s" (buffer-name))
564 ;; Don't be blindsided by narrowing that starts in the middle
565 ;; of a jit-lock-defer-multiline.
569 ;; If we're in text that matches a complex multi-line
570 ;; font-lock pattern, make sure the whole text will be
571 ;; redisplayed eventually.
572 ;; Despite its name, we treat jit-lock-defer-multiline here
573 ;; rather than in jit-lock-defer since it has to do with multiple
574 ;; lines, i.e. with context.
579 jit-lock-context-unfontify-pos
583 ;; Force contextual refontification.
591 "Hook that can extend the text to refontify after a change.
592 This is run after every buffer change. The functions are called with
593 the three arguments of `after-change-functions': START END OLD-LEN.
594 The extended region to refontify is returned indirectly by modifying
595 the variables `jit-lock-start' and `jit-lock-end'.
597 Note that extending the region this way is not strictly necessary, except
598 that the nature of the redisplay code tends to otherwise leave some of
599 the rehighlighted text displayed with the old highlight until the next
603 "Mark the rest of the buffer as not fontified after a change.
604 Installed on `after-change-functions'.
605 START and END are the start and end of the changed text. OLD-LEN
606 is the pre-change length.
607 This function ensures that lines following the change will be refontified
608 in case the syntax of those lines has changed. Refontification
609 will take place when text is fontified stealthily."
615 start end old-len)
616 ;; Make sure we change at least one char (in case of deletions).
618 ;; Request refontification.
620 ;; Mark the change for deferred contextual refontification.
623 ;; Here we use `start' because nothing guarantees that the
624 ;; text between start and end will be otherwise refontified:
625 ;; usually it will be refontified by virtue of being
626 ;; displayed, but if it's outside of any displayed area in the
627 ;; buffer, only jit-lock-context-* will re-fontify it.
632 ;;; jit-lock.el ends here