7. Font Locking

Please note: The font locking in AWK mode is currently not integrated with the rest of CC Mode, so this section does not apply there. See section 12.2 AWK Mode Font Locking, instead.

CC Mode provides font locking for its supported languages by supplying patterns for use with Font Lock mode. This means that you get distinct faces on the various syntactic parts such as comments, strings, keywords and types, which is very helpful in telling them apart at a glance and discovering syntactic errors. See section `Font Lock' in The Emacs Editor, for ways to enable font locking in CC Mode buffers.

7.1 Font Locking Preliminaries

The font locking for most of the CC Mode languages were provided directly by the Font Lock package prior to version 5.30 of CC Mode. In the transition to CC Mode the patterns have been reworked completely and are applied uniformly across all the languages except AWK mode, just like the indentation rules (although each language still has some pecularities of its own, of course). Since the languages previously had completely separate font locking patterns, this means that it's a bit different in most languages now.

The main goal for the font locking in CC Mode is accuracy, to provide a dependable aid in recognizing the various constructs. Some, like strings and comments, are easy to recognize while others like declarations and types can be very tricky. CC Mode can go to great lengths to recognize declarations and casts correctly, especially when the types aren't recognized by standard patterns. This is a fairly demanding analysis which can be slow on older hardware, and it can therefore be disabled by choosing a lower decoration level with the variable font-lock-maximum-decoration.

The decoration levels are used as follows:

1. Minimal font locking: Fontify only comments, strings and preprocessor directives (in the languages that use cpp).

2. Fast normal font locking: In addition to level 1, fontify keywords, simple types and declarations that are easy to recognize. The variables *-font-lock-extra-types (where `*' is the name of the language) are used to recognize types (see below). Documentation comments like Javadoc are fontified according to c-doc-comment-style (see section 7.3 Documentation Comments).

   Use this if you think the font locking is too slow. It's the closest corresponding level to level 3 in the old font lock patterns.

3. Accurate normal font locking: Like level 2 but uses a different approach that can recognize types and declarations much more accurately. The *-font-lock-extra-types variables are still used, but user defined types are recognized correctly anyway in most cases. Therefore those variables should be fairly restrictive and not contain patterns that are uncertain.

   This level is designed for fairly modern hardware and a font lock support mode like Lazy Lock or Just-in-time Lock mode that only fontifies the parts that are actually shown.

Since user defined types are hard to recognize you can provide additional regexps to match those you use:

User Option: c-font-lock-extra-types

User Option: c++-font-lock-extra-types

User Option: objc-font-lock-extra-types

User Option: java-font-lock-extra-types

User Option: idl-font-lock-extra-types

User Option: pike-font-lock-extra-types

For each language there's a variable *-font-lock-extra-types, where `*' stands for the language in question. It contains a list of regexps that matches identifiers that should be recognized as types, e.g. `\\sw+_t' to recognize all identifiers ending with `_t' as is customary in C code. Each regexp should not match more than a single identifier.

The default values contain regexps for many types in standard runtime libraries that are otherwise difficult to recognize, and patterns for standard type naming conventions like the `_t' suffix in C and C++. Java, Objective-C and Pike have as a convention to start class names with capitals, so there are patterns for that in those languages.

Despite the names of these variables, they are not only used for fontification but in other places as well where CC Mode needs to recognize types.

7.2 Faces

CC Mode attempts to use the standard faces for programming languages in accordance with their intended purposes as far as possible. No extra faces are currently provided, with the exception of a replacement face c-invalid-face for emacsen that don't provide font-lock-warning-face.

• Normal comments are fontified in font-lock-comment-face.

• Comments that are recognized as documentation (see section 7.3 Documentation Comments) get font-lock-doc-face (Emacs) or font-lock-doc-string-face (XEmacs) if those faces exist. If they don't then font-lock-comment-face is used.

• String and character literals are fontified in font-lock-string-face.

• Keywords are fontified with font-lock-keyword-face.

• font-lock-function-name-face is used for function names in declarations and definitions, and classes in those contexts. It's also used for preprocessor defines with arguments.

• Variables in declarations and definitions, and other identifiers in such variable contexts, get font-lock-variable-name-face. It's also used for preprocessor defines without arguments.

• Builtin constants are fontified in font-lock-constant-face if it exists, font-lock-reference-face otherwise. As opposed to the preceding two faces, this is used on the names in expressions, and it's not used in declarations, even if there happen to be a `const' in them somewhere.

• font-lock-type-face is put on types (both predefined and user defined) and classes in type contexts.

• Label identifiers get font-lock-constant-face if it exists, font-lock-reference-face otherwise.

• Name qualifiers and identifiers for scope constructs are fontified like labels.

• Special markup inside documentation comments are also fontified like labels.

• Preprocessor directives get font-lock-preprocessor-face if it exists (i.e. XEmacs). In Emacs they get font-lock-builtin-face or font-lock-reference-face, for lack of a closer equivalent.

• Some kinds of syntactic errors are fontified with font-lock-warning-face in Emacs. In older XEmacs versions there's no corresponding standard face, so there a special c-invalid-face is used, which is defined to stand out sharply by default.

  Note that it's not used for `#error' or `#warning' directives, since those aren't syntactic errors in themselves.

7.3 Documentation Comments

There are various tools to supply documentation in the source as specially structured comments, e.g. the standard Javadoc tool in Java. CC Mode provides an extensible mechanism to fontify such comments and the special markup inside them.

User Option: c-doc-comment-style

This is a style variable that specifies which documentation comment style to recognize, e.g. javadoc for Javadoc comments.

The value may also be a list of styles, in which case all of them are recognized simultaneously (presumably with markup cues that don't conflict).

The value may also be an association list to specify different comment styles for different languages. The symbol for the major mode is then looked up in the alist, and the value of that element is interpreted as above if found. If it isn't found then the symbol `other' is looked up and its value is used instead.

Note that CC Mode uses this variable to set other variables that handle fontification etc. That's done at mode initialization or when you switch to a style which sets this variable. Thus, if you change it in some other way, e.g. interactively in a CC Mode buffer, you will need to do M-x java-mode (or whatever mode you're currently using) to reinitialize.

Note also that when CC Mode starts up, the other variables are modified before the mode hooks are run. If you change this variable in a mode hook, you have to call c-setup-doc-comment-style afterwards to redo that work.

CC Mode currently provides handing of the following doc comment styles:

javadoc

Javadoc comments, the standard tool in Java.

autodoc

For Pike autodoc markup, the standard in Pike.

The above is by no means complete. If you'd like to see support for other doc comment styles, please let us know (see section C. Mailing Lists and Submitting Bug Reports).

You can also write your own doc comment fontification support to use with c-doc-comment-style: Supply a variable or function *-font-lock-keywords where `*' is the name you want to use in c-doc-comment-style. If it's a variable, it's prepended to font-lock-keywords. If it's a function, it's called at mode initialization and the result is prepended. For an example, see javadoc-font-lock-keywords in `cc-fonts.el'.

If you add support for another doc comment style, please consider contributing it -- send a note to bug-cc-mode@gnu.org.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.