5. Font Locking

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 (emacs)Font Lock section ‘Font Lock’ in GNU Emacs Manual, for ways to enable font locking in CC Mode buffers.

Please note: The font locking in AWK mode is currently not integrated with the rest of CC Mode. Only the last section of this chapter, AWK Mode Font Locking, applies to AWK. The other sections apply to the other languages.

5.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 peculiarities 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 (see (emacs)Font Lock section ‘Font Lock’ in GNU Emacs Manual).

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 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 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 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. Fontifying the whole buffer at once can easily get bothersomely slow even on contemporary hardware.

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.

5.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 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.

5.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.

The default value for c-doc-comment-style is ((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc)).

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’ll 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.

gtkdoc

For GtkDoc markup, widely used in the Gnome community.

doxygen

For Doxygen markup, which can be used with C, C++, Java and variety of other languages.

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 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’. It is even possible, to a limited extent, to fontify constructs inside a doc comment with other faces. For an example, see pike autodoc comment style towards the end of ‘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.

5.4 Marking “Wrong” style comments

Most languages supported by CC Mode have two styles of comments, namely block comments and line comments. Your project may have such a strong preference for one of them, that you wish “wrong” style comments to be clearly marked.

You can get CC Mode to do this by setting the default comment style, if necessary, (see section Minor Modes) and setting the customizable option c-mark-wrong-style-of-comment to non-nil.

Variable: c-mark-wrong-style-of-comment

When this customizable option is non-nil, comment delimiters which aren’t of the default style will be fontified with font-lock-warning-face.

5.5 Miscellaneous Font Locking

Some compilers, notably GCC, allow the character ‘$’ to be a constituent of identifiers in the languages C, C++, and Objective C. CC Mode defaults to accepting these ‘$’ characters and fontifying the identifiers in which they appear like any others.

However, the compiler you’re using, or your project coding standards may disallow such use. In such cases, you can set c-warn-ids-with-dollar to non-nil. This causes these invalid identifiers to be fontified distinctively.

Variable: c-warn-ids-with-dollar

When this customization option is non-nil, identifiers containing the ‘$’ character are fontified with font-lock-warning-face.

In some languages, particularly in C++, there are constructs which are syntactically ambiguous—they could be either declarations or expressions, and CC Mode cannot tell for sure which. Often such a construct is one of the operators ‘*’ or ‘&’ surrounded by two identifiers.

Experience shows that very often when such a construct is a declaration it will be written with the operator touching exactly one of the identifiers, like:

foo *bar

or

foo& bar

. Whether such code is fontified depends on the setting of c-asymmetry-fontification-flag.

Variable: c-asymmetry-fontification-flag

When c-asymmetry-fontification-flag is non-nil (which it is by default), code like the above, with white space either before or after the operator, but not both, is fontified as a declaration. When the variable is nil, such a construct gets the default face.

When the construct is an expression there will often be white space both before and after the operator or there will be no white space around it at all, like:

foo * bar

or

foo&bar

.

Such code is not fontified as a declaration. (Typically, the identifiers don’t get a non-default face.)

For clarity’s sake, we emphasize that the “asymmetry” rule in this section only applies when CC Mode cannot disambiguate a construct in any other way.

5.6 AWK Mode Font Locking

The general appearance of font-locking in AWK mode is much like in any other programming mode. See (elisp)Faces For Font Lock section ‘Faces For Font Lock’ in GNU Emacs Lisp Reference Manual.

The following faces are, however, used in a non-standard fashion in AWK mode:

font-lock-variable-name-face

This face was intended for variable declarations. Since variables are not declared in AWK, this face is used instead for AWK system variables (such as NF) and “Special File Names” (such as "/dev/stderr").

font-lock-builtin-face (Emacs)/font-lock-preprocessor-face (XEmacs)

This face is normally used for preprocessor directives in CC Mode. There are no such things in AWK, so this face is used instead for standard functions (such as match).

font-lock-string-face

As well as being used for strings, including localizable strings, (delimited by ‘"’ and ‘_"’), this face is also used for AWK regular expressions (delimited by ‘/’).

font-lock-warning-face (Emacs)/c-invalid-face (XEmacs)

This face highlights the following syntactically invalid AWK constructs:

• An unterminated string or regular expression. Here the opening delimiter (‘"’ or ‘/’ or ‘_"’) is displayed in font-lock-warning-face. This is most noticeable when typing in a new string/regular expression into a buffer, when the warning-face serves as a continual reminder to terminate the construct.

  AWK mode fontifies unterminated strings/regular expressions differently from other modes: Only the text up to the end of the line is fontified as a string (escaped newlines being handled correctly), rather than the text up to the next string quote.

• A space between the function name and opening parenthesis when calling a user function. The last character of the function name and the opening parenthesis are highlighted. This font-locking rule will spuriously highlight a valid concatenation expression where an identifier precedes a parenthesized expression. Unfortunately.
• Whitespace following the ‘\’ in what otherwise looks like an escaped newline. The ‘\’ is highlighted.

This document was generated on September 26, 2026 using texi2html 1.82.