1 *indent.txt* For Vim version 7.0. Last change: 2007 Mar 17
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 This file is about indenting C programs and other files.
9 1. Indenting C programs |C-indenting|
10 2. Indenting by expression |indent-expression|
12 ==============================================================================
13 1. Indenting C programs *C-indenting*
15 The basics for C indenting are explained in section |30.2| of the user manual.
17 Vim has options for automatically indenting C program files. These options
18 affect only the indent and do not perform other formatting. For comment
19 formatting, see |format-comments|.
21 Note that this will not work when the |+smartindent| or |+cindent| features
22 have been disabled at compile time.
24 There are in fact four methods available for indentation:
25 'autoindent' uses the indent from the previous line.
26 'smartindent' is like 'autoindent' but also recognizes some C syntax to
27 increase/reduce the indent where appropriate.
28 'cindent' Works more cleverly than the other two and is configurable to
29 different indenting styles.
30 'indentexpr' The most flexible of all: Evaluates an expression to compute
31 the indent of a line. When non-empty this method overrides
32 the other ones. See |indent-expression|.
33 The rest of this section describes the 'cindent' option.
35 Note that 'cindent' indenting does not work for every code scenario. Vim
36 is not a C compiler: it does not recognize all syntax. One requirement is
37 that toplevel functions have a '{' in the first column. Otherwise they are
38 easily confused with declarations.
40 These four options control C program indenting:
41 'cindent' Enables Vim to perform C program indenting automatically.
42 'cinkeys' Specifies which keys trigger reindenting in insert mode.
43 'cinoptions' Sets your preferred indent style.
44 'cinwords' Defines keywords that start an extra indent in the next line.
46 If 'lisp' is not on and 'equalprg' is empty, the "=" operator indents using
47 Vim's built-in algorithm rather than calling an external program.
49 See |autocommand| for how to set the 'cindent' option automatically for C code
50 files and reset it for others.
52 *cinkeys-format* *indentkeys-format*
53 The 'cinkeys' option is a string that controls Vim's indenting in response to
54 typing certain characters or commands in certain contexts. Note that this not
55 only triggers C-indenting. When 'indentexpr' is not empty 'indentkeys' is
56 used instead. The format of 'cinkeys' and 'indentkeys' is equal.
58 The default is "0{,0},0),:,0#,!^F,o,O,e" which specifies that indenting occurs
61 "0{" if you type '{' as the first character in a line
62 "0}" if you type '}' as the first character in a line
63 "0)" if you type ')' as the first character in a line
64 ":" if you type ':' after a label or case statement
65 "0#" if you type '#' as the first character in a line
66 "!^F" if you type CTRL-F (which is not inserted)
67 "o" if you type a <CR> anywhere or use the "o" command (not in
69 "O" if you use the "O" command (not in insert mode!)
70 "e" if you type the second 'e' for an "else" at the start of a
73 Characters that can precede each key: *i_CTRL-F*
74 ! When a '!' precedes the key, Vim will not insert the key but will
75 instead reindent the current line. This allows you to define a
76 command key for reindenting the current line. CTRL-F is the default
77 key for this. Be careful if you define CTRL-I for this because CTRL-I
78 is the ASCII code for <Tab>.
79 * When a '*' precedes the key, Vim will reindent the line before
80 inserting the key. If 'cinkeys' contains "*<Return>", Vim reindents
81 the current line before opening a new line.
82 0 When a zero precedes the key (but appears after '!' or '*') Vim will
83 reindent the line only if the key is the first character you type in
84 the line. When used before "=" Vim will only reindent the line if
85 there is only white space before the word.
87 When neither '!' nor '*' precedes the key, Vim reindents the line after you
88 type the key. So ';' sets the indentation of a line which includes the ';'.
91 <> Angle brackets mean spelled-out names of keys. For example: "<Up>",
92 "<Ins>" (see |key-notation|).
93 ^ Letters preceded by a caret (^) are control characters. For example:
95 o Reindent a line when you use the "o" command or when Vim opens a new
96 line below the current one (e.g., when you type <Enter> in insert
98 O Reindent a line when you use the "O" command.
99 e Reindent a line that starts with "else" when you type the second 'e'.
100 : Reindent a line when a ':' is typed which is after a label or case
101 statement. Don't reindent for a ":" in "class::method" for C++. To
102 Reindent for any ":", use "<:>".
103 =word Reindent when typing the last character of "word". "word" may
104 actually be part of another word. Thus "=end" would cause reindenting
105 when typing the "d" in "endif" or "endwhile". But not when typing
106 "bend". Also reindent when completion produces a word that starts
107 with "word". "0=word" reindents when there is only white space before
109 =~word Like =word, but ignore case.
111 If you really want to reindent when you type 'o', 'O', 'e', '0', '<', '>',
112 '*', ':' or '!', use "<o>", "<O>", "<e>", "<0>", "<<>", "<>>", "<*>", "<:>" or
113 "<!>", respectively, for those keys.
115 For an emacs-style indent mode where lines aren't indented every time you
116 press Enter but only if you press Tab, I suggest:
117 :set cinkeys=0{,0},:,0#,!<Tab>,!^F
118 You might also want to switch off 'autoindent' then.
120 Note: If you change the current line's indentation manually, Vim ignores the
121 cindent settings for that line. This prevents vim from reindenting after you
122 have changed the indent by typing <BS>, <Tab>, or <Space> in the indent or
123 used CTRL-T or CTRL-D.
126 The 'cinoptions' option sets how Vim performs indentation. In the list below,
127 "N" represents a number of your choice (the number can be negative). When
128 there is an 's' after the number, Vim multiplies the number by 'shiftwidth':
129 "1s" is 'shiftwidth', "2s" is two times 'shiftwidth', etc. You can use a
130 decimal point, too: "-0.5s" is minus half a 'shiftwidth'. The examples below
131 assume a 'shiftwidth' of 4.
133 >N Amount added for "normal" indent. Used after a line that should
134 increase the indent (lines starting with "if", an opening brace,
135 etc.). (default 'shiftwidth').
137 cino= cino=>2 cino=>2s >
138 if (cond) if (cond) if (cond)
143 eN Add N to the prevailing indent inside a set of braces if the
144 opening brace at the End of the line (more precise: is not the
145 first character in a line). This is useful if you want a
146 different indent when the '{' is at the start of the line from
147 when '{' is at the end of the line. (default 0).
149 cino= cino=e2 cino=e-2 >
150 if (cond) { if (cond) { if (cond) {
158 nN Add N to the prevailing indent for a statement after an "if",
159 "while", etc., if it is NOT inside a set of braces. This is
160 useful if you want a different indent when there is no '{'
161 before the statement from when there is a '{' before it.
164 cino= cino=n2 cino=n-2 >
165 if (cond) if (cond) if (cond)
172 fN Place the first opening brace of a function or other block in
173 column N. This applies only for an opening brace that is not
174 inside other braces and is at the start of the line. What comes
175 after the brace is put relative to this brace. (default 0).
177 cino= cino=f.5s cino=f1s >
180 int foo; int foo; int foo;
182 {N Place opening braces N characters from the prevailing indent.
183 This applies only for opening braces that are inside other
186 cino= cino={.5s cino={1s >
187 if (cond) if (cond) if (cond)
191 }N Place closing braces N characters from the matching opening
194 cino= cino={2,}-0.5s cino=}2 >
195 if (cond) if (cond) if (cond)
200 ^N Add N to the prevailing indent inside a set of braces if the
201 opening brace is in column 0. This can specify a different
202 indent for whole of a function (some may like to set it to a
203 negative number). (default 0).
205 cino= cino=^-2 cino=^-s >
208 if (cond) if (cond) if (cond)
214 :N Place case labels N characters from the indent of the switch().
215 (default 'shiftwidth').
225 =N Place statements occurring after a case label N characters from
226 the indent of the label. (default 'shiftwidth').
229 case 11: case 11: a = a + 1;
230 a = a + 1; b = b + 1;
232 lN If N != 0 Vim will align with a case label instead of the
233 statement after it in the same line.
236 switch (a) { switch (a) {
241 bN If N != 0 Vim will align a final "break" with the case label,
242 so that case..break looks like a sort of block. (default: 0).
256 gN Place C++ scope declarations N characters from the indent of the
257 block they are in. (default 'shiftwidth'). A scope declaration
258 can be "public:", "protected:" or "private:".
267 hN Place statements occurring after a C++ scope declaration N
268 characters from the indent of the label. (default
272 public: public: a = a + 1;
273 a = a + 1; b = b + 1;
275 pN Parameter declarations for K&R-style function declarations will
276 be indented N characters from the margin. (default
279 cino= cino=p0 cino=p2s >
280 func(a, b) func(a, b) func(a, b)
282 char b; char b; char b;
284 tN Indent a function return type declaration N characters from the
285 margin. (default 'shiftwidth').
287 cino= cino=t0 cino=t7 >
291 iN Indent C++ base class declarations and constructor
292 initializations, if they start in a new line (otherwise they
293 are aligned at the right side of the ':').
294 (default 'shiftwidth').
297 class MyClass : class MyClass :
298 public BaseClass public BaseClass
300 MyClass::MyClass() : MyClass::MyClass() :
301 BaseClass(3) BaseClass(3)
304 +N Indent a continuation line (a line that spills onto the next) N
305 additional characters. (default 'shiftwidth').
308 a = b + 9 * a = b + 9 *
311 cN Indent comment lines after the comment opener, when there is no
312 other text with which to align, N characters from the comment
313 opener. (default 3). See also |format-comments|.
320 CN When N is non-zero, indent comment lines by the amount specified
321 with the c flag above even if there is other text behind the
322 comment opener. (default 0).
328 < (Example uses ":set comments& comments-=s1:/* comments^=s0:/*")
330 /N Indent comment lines N characters extra. (default 0).
333 /* comment */ /* comment */
336 (N When in unclosed parentheses, indent N characters from the line
337 with the unclosed parentheses. Add a 'shiftwidth' for every
338 unclosed parentheses. When N is 0 or the unclosed parentheses
339 is the first non-white character in its line, line up with the
340 next non-white character after the unclosed parentheses.
341 (default 'shiftwidth' * 2).
344 if (c1 && (c2 || if (c1 && (c2 ||
348 (c2 || c3)) (c2 || c3))
351 uN Same as (N, but for one level deeper. (default 'shiftwidth').
354 if (c123456789 if (c123456789
355 && (c22345 && (c22345
358 UN When N is non-zero, do not ignore the indenting specified by
359 ( or u in case that the unclosed parentheses is the first
360 non-white character in its line. (default 0).
362 cino= or cino=(s cino=(s,U1 >
369 wN When in unclosed parentheses and N is non-zero and either
370 using "(0" or "u0", respectively, or using "U0" and the unclosed
371 parentheses is the first non-white character in its line, line
372 up with the character immediately after the unclosed parentheses
373 rather than the first non-white character. (default 0).
381 WN When in unclosed parentheses and N is non-zero and either
382 using "(0" or "u0", respectively and the unclosed parentheses is
383 the last non-white character in its line and it is not the
384 closing parentheses, indent the following line N characters
385 relative to the outer context (i.e. start of the line or the
386 next unclosed parentheses). (default: 0).
389 a_long_line( a_long_line(
391 argument); argument);
392 a_short_line(argument, a_short_line(argument,
393 argument); argument);
395 mN When N is non-zero, line up a line starting with a closing
396 parentheses with the first character of the line with the
397 matching opening parentheses. (default 0).
400 c = c1 && ( c = c1 && (
409 MN When N is non-zero, line up a line starting with a closing
410 parentheses with the first character of the previous line.
414 if (cond1 && if (cond1 &&
418 *java-cinoptions* *java-indenting*
419 jN Indent java anonymous classes correctly. The value 'N' is
420 currently unused but must be non-zero (e.g. 'j1'). 'j1' will
421 indent for example the following code snippet correctly: >
423 object.add(new ChangeListener() {
424 public void stateChanged(ChangeEvent e) {
429 )N Vim searches for unclosed parentheses at most N lines away.
430 This limits the time needed to search for parentheses. (default
433 *N Vim searches for unclosed comments at most N lines away. This
434 limits the time needed to search for the start of a comment.
437 #N When N is non-zero recognize shell/Perl comments, starting with
438 '#'. Default N is zero: don't recognizes '#' comments. Note
439 that lines starting with # will still be seen as preprocessor
443 The defaults, spelled out in full, are:
444 cinoptions=>s,e0,n0,f0,{0,}0,^0,:s,=s,l0,b0,gs,hs,ps,ts,is,+s,c3,C0,
445 /0,(2s,us,U0,w0,W0,m0,j0,)20,*30,#0
447 Vim puts a line in column 1 if:
448 - It starts with '#' (preprocessor directives), if 'cinkeys' contains '#'.
449 - It starts with a label (a keyword followed by ':', other than "case" and
451 - Any combination of indentations causes the line to have less than 0
454 ==============================================================================
455 2. Indenting by expression *indent-expression*
457 The basics for using flexible indenting are explained in section |30.3| of the
460 If you want to write your own indent file, it must set the 'indentexpr'
461 option. Setting the 'indentkeys' option is often useful. See the
462 $VIMRUNTIME/indent directory for examples.
465 REMARKS ABOUT SPECIFIC INDENT FILES ~
468 FORTRAN *ft-fortran-indent*
470 Block if, select case, and where constructs are indented. Comments, labelled
471 statements and continuation lines are indented if the Fortran is in free
472 source form, whereas they are not indented if the Fortran is in fixed source
473 form because of the left margin requirements. Hence manual indent corrections
474 will be necessary for labelled statements and continuation lines when fixed
475 source form is being used. For further discussion of the method used for the
476 detection of source format see |ft-fortran-syntax|.
479 All do loops are left unindented by default. Do loops can be unstructured in
480 Fortran with (possibly multiple) loops ending on a labelled executable
481 statement of almost arbitrary type. Correct indentation requires
482 compiler-quality parsing. Old code with do loops ending on labelled statements
483 of arbitrary type can be indented with elaborate programs such as Tidy
484 (http://www.unb.ca/chem/ajit/f_tidy.htm). Structured do/continue loops are
485 also left unindented because continue statements are also used for purposes
486 other than ending a do loop. Programs such as Tidy can convert structured
487 do/continue loops to the do/enddo form. Do loops of the do/enddo variety can
488 be indented. If you use only structured loops of the do/enddo form, you should
489 declare this by setting the fortran_do_enddo variable in your .vimrc as
492 let fortran_do_enddo=1
494 in which case do loops will be indented. If all your loops are of do/enddo
495 type only in, say, .f90 files, then you should set a buffer flag with an
496 autocommand such as >
498 au! BufRead,BufNewFile *.f90 let b:fortran_do_enddo=1
500 to get do loops indented in .f90 files and left alone in Fortran files with
501 other extensions such as .for.
504 PYTHON *ft-python-indent*
506 The amount of indent can be set for the following situations. The examples
507 given are de the defaults. Note that the variables are set to an expression,
508 so that you can change the value of 'shiftwidth' later.
510 Indent after an open paren: >
511 let g:pyindent_open_paren = '&sw * 2'
512 Indent after a nested paren: >
513 let g:pyindent_nested_paren = '&sw'
514 Indent for a continuation line: >
515 let g:pyindent_continue = '&sw * 2'
518 VERILOG *ft-verilog-indent*
520 General block statements such as if, for, case, always, initial, function,
521 specify and begin, etc., are indented. The module block statements (first
522 level blocks) are not indented by default. you can turn on the indent with
523 setting a variable in the .vimrc as follows: >
525 let b:verilog_indent_modules = 1
527 then the module blocks will be indented. To stop this, remove the variable: >
529 :unlet b:verilog_indent_modules
531 To set the variable only for Verilog file. The following statements can be
534 au BufReadPost * if exists("b:current_syntax")
535 au BufReadPost * if b:current_syntax == "verilog"
536 au BufReadPost * let b:verilog_indent_modules = 1
537 au BufReadPost * endif
538 au BufReadPost * endif
540 Furthermore, setting the variable b:verilog_indent_width to change the
541 indenting width (default is 'shiftwidth'): >
543 let b:verilog_indent_width = 4
544 let b:verilog_indent_width = &sw * 2
546 In addition, you can turn the verbose mode for debug issue: >
548 let b:verilog_indent_verbose = 1
550 Make sure to do ":set cmdheight=2" first to allow the display of the message.
555 For indenting Vim scripts there is one variable that specifies the amount of
556 indent for a continuation line, a line that starts with a backslash: >
558 :let g:vim_indent_cont = &sw * 3
560 Three times shiftwidth is the default value.
563 vim:tw=78:ts=8:ft=help:norl: