6.3.3 Adding and Amending Styles

If none of the built-in styles is appropriate, you’ll probably want to create a new style definition, possibly based on an existing style. To do this, put the new style’s settings into a list with the following format - the list can then be passed as an argument to the function c-add-style. You can see an example of a style definition in Sample .emacs File.

Structure of a Style Definition List

([base-style] [(variable . value) …])

Optional base-style, if present, must be a string which is the name of the base style from which this style inherits. At most one base-style is allowed in a style definition. If base-style is not specified, the style inherits from the table of factory default values21 instead. All styles eventually inherit from this internal table. Style loops generate errors. The list of pre-existing styles can be seen in Built-in Styles.

The dotted pairs (variable . value) each consist of a variable and the value it is to be set to when the style is later activated.22 The variable can be either a CC Mode style variable or an arbitrary Emacs variable. In the latter case, it is not made buffer-local by the CC Mode style system.

Two variables are treated specially in the dotted pair list:

c-offsets-alist

The value is in turn a list of dotted pairs of the form

(syntactic-symbol . offset)

as described in c-offsets-alist. These are passed to c-set-offset so there is no need to set every syntactic symbol in your style, only those that are different from the inherited style.

c-special-indent-hook

The value is added to c-special-indent-hook using add-hook, so any functions already on it are kept. If the value is a list, each element of the list is added with add-hook.

Styles are kept in the c-style-alist variable, but you should never modify this variable directly. Instead, CC Mode provides the function c-add-style for this purpose.

Function: c-add-style stylename description &optional set-p

Add or update a style called stylename, a string. description is the new style definition in the form described above. If stylename already exists in c-style-alist then it is replaced by description. (Note, this replacement is total. The old style is not merged into the new one.) Otherwise, a new style is added.

If the optional set-p is non-nil then the new style is applied to the current buffer as well. The use of this facility is deprecated and it might be removed from CC Mode in a future release. You should use c-set-style instead.

The sample .emacs file provides a concrete example of how a new style can be added and automatically set. See Sample .emacs File.

Variable: c-style-alist

This is the variable that holds the definitions for the styles. It should not be changed directly; use c-add-style instead.


Footnotes

(21)

This table is stored internally in the variable c-fallback-style.

(22)

Note that if the variable has been given a value by the Customization interface or a setq at the top level of your .emacs, this value will override the one the style system tries to give it. See Configuration Basics.