Mercurial > emacs
comparison lispref/modes.texi @ 63133:2244564c10de
(Mode Line Data): Minor cleanup.
(Customizing Keywords): Node split out of Search-based Fontification.
Add example of using font-lock-add-keywords from a hook.
Clarify when MODE should be non-nil, and when nil.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Wed, 08 Jun 2005 15:32:01 +0000 |
parents | 91cd19004788 |
children | 99e9892a51d9 173dee4e2611 |
comparison
equal
deleted
inserted
replaced
63132:2dd78739b46c | 63133:2244564c10de |
---|---|
1648 properties specified by @var{props} to the result. The argument | 1648 properties specified by @var{props} to the result. The argument |
1649 @var{props} should consist of zero or more pairs @var{text-property} | 1649 @var{props} should consist of zero or more pairs @var{text-property} |
1650 @var{value}. (This feature is new as of Emacs 22.1.) | 1650 @var{value}. (This feature is new as of Emacs 22.1.) |
1651 | 1651 |
1652 @item (@var{symbol} @var{then} @var{else}) | 1652 @item (@var{symbol} @var{then} @var{else}) |
1653 A list whose first element is a symbol that is not a keyword specifies a | 1653 A list whose first element is a symbol that is not a keyword specifies |
1654 conditional. Its meaning depends on the value of @var{symbol}. If the | 1654 a conditional. Its meaning depends on the value of @var{symbol}. If |
1655 value is non-@code{nil}, the second element, @var{then}, is processed | 1655 @var{symbol} has a non-@code{nil} value, the second element, |
1656 recursively as a mode-line element. But if the value of @var{symbol} is | 1656 @var{then}, is processed recursively as a mode-line element. |
1657 @code{nil}, the third element, @var{else}, is processed recursively. | 1657 Otherwise, the third element, @var{else}, is processed recursively. |
1658 You may omit @var{else}; then the mode-line element displays nothing if | 1658 You may omit @var{else}; then the mode-line element displays nothing |
1659 the value of @var{symbol} is @code{nil}. | 1659 if the value of @var{symbol} is @code{nil} or void. |
1660 | 1660 |
1661 @item (@var{width} @var{rest}@dots{}) | 1661 @item (@var{width} @var{rest}@dots{}) |
1662 A list whose first element is an integer specifies truncation or | 1662 A list whose first element is an integer specifies truncation or |
1663 padding of the results of @var{rest}. The remaining elements | 1663 padding of the results of @var{rest}. The remaining elements |
1664 @var{rest} are processed recursively as mode-line constructs and | 1664 @var{rest} are processed recursively as mode-line constructs and |
2317 Search-based fontification happens second. | 2317 Search-based fontification happens second. |
2318 | 2318 |
2319 @menu | 2319 @menu |
2320 * Font Lock Basics:: Overview of customizing Font Lock. | 2320 * Font Lock Basics:: Overview of customizing Font Lock. |
2321 * Search-based Fontification:: Fontification based on regexps. | 2321 * Search-based Fontification:: Fontification based on regexps. |
2322 * Customizing Keywords:: Customizing search-based fontification. | |
2322 * Other Font Lock Variables:: Additional customization facilities. | 2323 * Other Font Lock Variables:: Additional customization facilities. |
2323 * Levels of Font Lock:: Each mode can define alternative levels | 2324 * Levels of Font Lock:: Each mode can define alternative levels |
2324 so that the user can select more or less. | 2325 so that the user can select more or less. |
2325 * Precalculated Fontification:: How Lisp programs that produce the buffer | 2326 * Precalculated Fontification:: How Lisp programs that produce the buffer |
2326 contents can also specify how to fontify it. | 2327 contents can also specify how to fontify it. |
2622 @defvar font-lock-keywords-case-fold-search | 2623 @defvar font-lock-keywords-case-fold-search |
2623 Non-@code{nil} means that regular expression matching for the sake of | 2624 Non-@code{nil} means that regular expression matching for the sake of |
2624 @code{font-lock-keywords} should be case-insensitive. | 2625 @code{font-lock-keywords} should be case-insensitive. |
2625 @end defvar | 2626 @end defvar |
2626 | 2627 |
2627 You can use @code{font-lock-add-keywords} to add additional | 2628 @node Customizing Keywords |
2629 @subsection Customizing Search-Based Fontification | |
2630 | |
2631 You can use @code{font-lock-add-keywords} to add additional | |
2628 search-based fontification rules to a major mode, and | 2632 search-based fontification rules to a major mode, and |
2629 @code{font-lock-remove-keywords} to removes rules. | 2633 @code{font-lock-remove-keywords} to removes rules. |
2630 | 2634 |
2631 @defun font-lock-add-keywords mode keywords &optional append | 2635 @defun font-lock-add-keywords mode keywords &optional append |
2632 This function adds highlighting @var{keywords} for @var{mode}. The | 2636 This function adds highlighting @var{keywords}, for the current buffer |
2633 argument @var{keywords} should be a list with the same format as the | 2637 or for major mode @var{mode}. The argument @var{keywords} should be a |
2634 variable @code{font-lock-keywords}. @var{mode} should be a symbol, | 2638 list with the same format as the variable @code{font-lock-keywords}. |
2635 the major mode command name, such as @code{c-mode}. When Font Lock | 2639 |
2636 mode is turned on in @var{mode}, it adds @var{keywords} to | 2640 If @var{mode} is a symbol which is a major mode command name, such as |
2637 @code{font-lock-keywords}. @var{mode} can also be @code{nil}; the | 2641 @code{c-mode}, the effect is that enabling Font Lock mode in |
2638 highlighting @var{keywords} are immediately added to | 2642 @var{mode} will add @var{keywords} to @code{font-lock-keywords}. |
2639 @code{font-lock-keywords} in the current buffer in that case. | 2643 Calling with a non-@code{nil} value of @var{mode} is correct only in |
2644 your @file{~/.emacs} file. | |
2645 | |
2646 If @var{mode} is @code{nil}, this function adds @var{keywords} to | |
2647 @code{font-lock-keywords} in the current buffer. This way of calling | |
2648 @code{font-lock-add-keywords} is usually used in mode hook functions. | |
2640 | 2649 |
2641 By default, @var{keywords} are added at the beginning of | 2650 By default, @var{keywords} are added at the beginning of |
2642 @code{font-lock-keywords}. If the optional argument @var{append} is | 2651 @code{font-lock-keywords}. If the optional argument @var{append} is |
2643 @code{set}, they are used to replace the value of | 2652 @code{set}, they are used to replace the value of |
2644 @code{font-lock-keywords}. If @var{append} is any other | 2653 @code{font-lock-keywords}. If @var{append} is any other |
2645 non-@code{nil} value, they are added at the end of | 2654 non-@code{nil} value, they are added at the end of |
2646 @code{font-lock-keywords}. | 2655 @code{font-lock-keywords}. |
2647 | 2656 |
2648 For example: | 2657 Some modes provide specialized support you can use in additional |
2658 highlighting patterns. See the variables | |
2659 @code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types}, | |
2660 @code{objc-font-lock-extra-types} and | |
2661 @code{java-font-lock-extra-types}, for example. | |
2662 | |
2663 @strong{Warning:} major mode functions must not call | |
2664 @code{font-lock-add-keywords} under any circumstances, either directly | |
2665 or indirectly, except through their mode hooks. (Doing so would lead | |
2666 to incorrect behavior for some minor modes.) They should set up their | |
2667 rules for search-based fontification by setting | |
2668 @code{font-lock-keywords}. | |
2669 @end defun | |
2670 | |
2671 @defun font-lock-remove-keywords mode keywords | |
2672 This function removes @var{keywords} from @code{font-lock-keywords} | |
2673 for the current buffer or for major mode @var{mode}. As in | |
2674 @code{font-lock-add-keywords}, @var{mode} should be a major mode | |
2675 command name or @code{nil}. All the caveats and requirments for | |
2676 @code{font-lock-add-keywords} apply here too. | |
2677 @end defun | |
2678 | |
2679 For example, this code | |
2649 | 2680 |
2650 @smallexample | 2681 @smallexample |
2651 (font-lock-add-keywords 'c-mode | 2682 (font-lock-add-keywords 'c-mode |
2652 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) | 2683 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) |
2653 ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face))) | 2684 ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face))) |
2654 @end smallexample | 2685 @end smallexample |
2655 | 2686 |
2687 @noindent | |
2656 adds two fontification patterns for C mode: one to fontify the word | 2688 adds two fontification patterns for C mode: one to fontify the word |
2657 @samp{FIXME}, even in comments, and another to fontify the words | 2689 @samp{FIXME}, even in comments, and another to fontify the words |
2658 @samp{and}, @samp{or} and @samp{not} as keywords. | 2690 @samp{and}, @samp{or} and @samp{not} as keywords. |
2659 | 2691 |
2660 Some modes have specialized support for additional patterns. See the | 2692 @noindent |
2661 variables @code{c-font-lock-extra-types}, | 2693 That example affects only C mode proper. To add the same patterns to |
2662 @code{c++-font-lock-extra-types}, @code{objc-font-lock-extra-types} | 2694 C mode @emph{and} all modes derived from it, do this instead: |
2663 and @code{java-font-lock-extra-types}, for example. | 2695 |
2664 @end defun | 2696 @smallexample |
2665 | 2697 (add-hook 'c-mode-hook |
2666 @defun font-lock-remove-keywords mode keywords | 2698 (lambda () |
2667 This function removes highlighting @var{keywords} for @var{mode}. As | 2699 (font-lock-add-keywords nil |
2668 in @code{font-lock-add-keywords}, @var{mode} should be a major mode | 2700 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) |
2669 command name or @code{nil}. If @code{nil}, the highlighting | 2701 ("\\<\\(and\\|or\\|not\\)\\>" . |
2670 @var{keywords} are immediately removed in the current buffer. | 2702 font-lock-keyword-face))))) |
2671 @end defun | 2703 @end smallexample |
2672 | |
2673 @strong{Warning:} Only use a non-@code{nil} @var{mode} argument when | |
2674 you use @code{font-lock-add-keywords} or | |
2675 @code{font-lock-remove-keywords} in your @file{.emacs} file. When you | |
2676 use these functions from a Lisp program (such as a minor mode), we | |
2677 recommend that you use @code{nil} for @var{mode} (and place the call | |
2678 on a hook) to avoid subtle problems due to the details of the | |
2679 implementation. | |
2680 | 2704 |
2681 @node Other Font Lock Variables | 2705 @node Other Font Lock Variables |
2682 @subsection Other Font Lock Variables | 2706 @subsection Other Font Lock Variables |
2683 | 2707 |
2684 This section describes additional variables that a major mode can | 2708 This section describes additional variables that a major mode can |