GNU Info

(ccmode)Customizing Indentation

---

Next: Syntactic Symbols Prev: Commands Up: Top

---

Enter node , (file) or (file)node

Customizing Indentation
***********************

   The style variable `c-offsets-alist' contains the mappings between
syntactic symbols and the offsets to apply for those symbols.  It's set
at mode initialization from a _style_ you may specify.  Styles are
groupings of syntactic symbol offsets and other style variable values.
Most likely, you'll find that one of the pre-defined styles will suit
your needs.  Note: Styles, for an explanation of how to set up named
styles.

   Only syntactic symbols not already bound on `c-offsets-alist' will
be set from styles.  This means that any association you set on it, be
it before or after mode initialization, will not be changed.  The
`c-offsets-alist' variable may therefore be used from e.g. the
Customization interface(1) to easily change indentation offsets without
having to bother about styles.  Initially `c-offsets-alist' is empty,
so that all syntactic symbols are set by the style system.

   You can use the command `C-c C-o' (`c-set-offset') as the way to set
offsets, both interactively and from your mode hook(2).

   The offset associated with any particular syntactic symbol can be
any of an integer, a function or lambda expression, a variable name, a
vector, a list, or one of the following symbols: `+', `-', `++', `--',
`*', or `/'.

   Those last special symbols describe an offset in multiples of the
value of the style variable `c-basic-offset'.  By defining a style's
indentation in terms of this fundamental variable, you can change the
amount of whitespace given to an indentation level while maintaining the
same basic shape of your code.  Here are the values that the special
symbols correspond to:

`+'
     `c-basic-offset' times 1

`-'
     `c-basic-offset' times -1

`++'
     `c-basic-offset' times 2

`--'
     `c-basic-offset' times -2

`*'
     `c-basic-offset' times 0.5

`/'
     `c-basic-offset' times -0.5

   When a function is used as offset, it's called an "indentation
function".  Such functions are useful when more context than just the
syntactic symbol is needed to get the desired indentation.  Note:
Indentation Functions, and Note: Custom Indentation Functions, for
details about them.

   If the offset is a vector, its first element sets the absolute
indentation column, which will override any relative indentation.

   The offset can also be a list, in which case it is evaluated
recursively using the semantics described above.  The first element of
the list that returns a non-`nil' value succeeds and the evaluation
stops.  If none of the list elements return a non-`nil' value, then an
offset of 0 (zero) is used(3).

   So, for example, because most of the default offsets are defined in
terms of `+', `-', and `0', if you like the general indentation style,
but you use 4 spaces instead of 2 spaces per level, you can probably
achieve your style just by changing `c-basic-offset' like so(4):

     _M-x set-variable RET_
     Set variable: _c-basic-offset RET_
     Set c-basic-offset to value: _4 RET_

This would change

     int add( int val, int incr, int doit )
     {
       if( doit )
         {
           return( val + incr );
         }
       return( val );
     }

to

     int add( int val, int incr, int doit )
     {
         if( doit )
             {
                 return( val + incr );
             }
         return( val );
     }

   To change indentation styles more radically, you will want to change
the offsets associated with other syntactic symbols.  First, I'll show
you how to do that interactively, then I'll describe how to make
changes to your `.emacs' file so that your changes are more permanent.

Interactive Customization

Permanent Customization

Hooks

Styles

Advanced Customizations

   ---------- Footnotes ----------

   (1) Available in Emacs 20 and later, and XEmacs 19.15 and later.

   (2) Obviously, you use the key binding interactively, and the
function call programmatically!

   (3) There is however a variable `c-strict-syntax-p' that, when set
to non-`nil', will cause an error to be signalled in that case.  It's
now considered obsolete since it doesn't work well with some of the
alignment functions that now returns `nil' instead of zero to be more
usable in lists.  You should therefore leave `c-strict-syntax-p' set to
`nil'.

   (4) You can try this interactively in a C buffer by typing the text
that appears in italics.