| blob | 0791b9ff77fddef3891291d22223274d955aad4a |
1 *indent.txt* For Vim version 7.1. Last change: 2007 Aug 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
59 as follows:
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
68 insert mode!)
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
71 line
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 ';'.
90 Special key names:
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:
94 "^F" is CTRL-F.
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
97 mode).
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
108 the word.
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.
125 *cinoptions-values*
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)
139 { { {
140 foo; foo; foo;
141 } } }
142 <
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) {
151 foo; foo; foo;
152 } } }
153 else else else
154 { { {
155 bar; bar; bar;
156 } } }
157 <
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.
162 (default 0).
164 cino= cino=n2 cino=n-2 >
165 if (cond) if (cond) if (cond)
166 foo; foo; foo;
167 else else else
168 { { {
169 bar; bar; bar;
170 } } }
171 <
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 >
178 func() func() func()
179 { { {
180 int foo; int foo; int foo;
181 <
182 {N Place opening braces N characters from the prevailing indent.
183 This applies only for opening braces that are inside other
184 braces. (default 0).
186 cino= cino={.5s cino={1s >
187 if (cond) if (cond) if (cond)
188 { { {
189 foo; foo; foo;
190 <
191 }N Place closing braces N characters from the matching opening
192 brace. (default 0).
194 cino= cino={2,}-0.5s cino=}2 >
195 if (cond) if (cond) if (cond)
196 { { {
197 foo; foo; foo;
198 } } }
199 <
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 >
206 func() func() func()
207 { { {
208 if (cond) if (cond) if (cond)
209 { { {
210 a = b; a = b; a = b;
211 } } }
212 } } }
213 <
214 :N Place case labels N characters from the indent of the switch().
215 (default 'shiftwidth').
217 cino= cino=:0 >
218 switch (x) switch(x)
219 { {
220 case 1: case 1:
221 a = b; a = b;
222 default: default:
223 } }
224 <
225 =N Place statements occurring after a case label N characters from
226 the indent of the label. (default 'shiftwidth').
228 cino= cino==10 >
229 case 11: case 11: a = a + 1;
230 a = a + 1; b = b + 1;
231 <
232 lN If N != 0 Vim will align with a case label instead of the
233 statement after it in the same line.
235 cino= cino=l1 >
236 switch (a) { switch (a) {
237 case 1: { case 1: {
238 break; break;
239 } }
240 <
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).
244 cino= cino=b1 >
245 switch (x) switch(x)
246 { {
247 case 1: case 1:
248 a = b; a = b;
249 break; break;
251 default: default:
252 a = 0; a = 0;
253 break; break;
254 } }
255 <
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:".
260 cino= cino=g0 >
261 { {
262 public: public:
263 a = b; a = b;
264 private: private:
265 } }
266 <
267 hN Place statements occurring after a C++ scope declaration N
268 characters from the indent of the label. (default
269 'shiftwidth').
271 cino= cino=h10 >
272 public: public: a = a + 1;
273 a = a + 1; b = b + 1;
274 <
275 pN Parameter declarations for K&R-style function declarations will
276 be indented N characters from the margin. (default
277 'shiftwidth').
279 cino= cino=p0 cino=p2s >
280 func(a, b) func(a, b) func(a, b)
281 int a; int a; int a;
282 char b; char b; char b;
283 <
284 tN Indent a function return type declaration N characters from the
285 margin. (default 'shiftwidth').
287 cino= cino=t0 cino=t7 >
288 int int int
289 func() func() func()
290 <
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').
296 cino= cino=i0 >
297 class MyClass : class MyClass :
298 public BaseClass public BaseClass
299 {} {}
300 MyClass::MyClass() : MyClass::MyClass() :
301 BaseClass(3) BaseClass(3)
302 {} {}
303 <
304 +N Indent a continuation line (a line that spills onto the next) N
305 additional characters. (default 'shiftwidth').
307 cino= cino=+10 >
308 a = b + 9 * a = b + 9 *
309 c; c;
310 <
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|.
315 cino= cino=c5 >
316 /* /*
317 text. text.
318 */ */
319 <
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).
324 cino=c0 cino=c0,C1 >
325 /******** /********
326 text. text.
327 ********/ ********/
328 < (Example uses ":set comments& comments-=s1:/* comments^=s0:/*")
330 /N Indent comment lines N characters extra. (default 0).
331 cino= cino=/4 >
332 a = b; a = b;
333 /* comment */ /* comment */
334 c = d; c = d;
335 <
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).
343 cino= cino=(0 >
344 if (c1 && (c2 || if (c1 && (c2 ||
345 c3)) c3))
346 foo; foo;
347 if (c1 && if (c1 &&
348 (c2 || c3)) (c2 || c3))
349 { {
350 <
351 uN Same as (N, but for one level deeper. (default 'shiftwidth').
353 cino= cino=u2 >
354 if (c123456789 if (c123456789
355 && (c22345 && (c22345
356 || c3)) || c3))
357 <
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 >
363 c = c1 && c = c1 &&
364 ( (
365 c2 || c2 ||
366 c3 c3
367 ) && c4; ) && c4;
368 <
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).
375 cino=(0 cino=(0,w1 >
376 if ( c1 if ( c1
377 && ( c2 && ( c2
378 || c3)) || c3))
379 foo; foo;
380 <
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).
388 cino=(0 cino=(0,W4 >
389 a_long_line( a_long_line(
390 argument, argument,
391 argument); argument);
392 a_short_line(argument, a_short_line(argument,
393 argument); argument);
394 <
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).
399 cino=(s cino=(s,m1 >
400 c = c1 && ( c = c1 && (
401 c2 || c2 ||
402 c3 c3
403 ) && c4; ) && c4;
404 if ( if (
405 c1 && c2 c1 && c2
406 ) )
407 foo; foo;
408 <
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.
411 (default 0).
413 cino= cino=M1 >
414 if (cond1 && if (cond1 &&
415 cond2 cond2
416 ) )
417 <
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) {
425 do_something();
426 }
427 });
428 <
429 )N Vim searches for unclosed parentheses at most N lines away.
430 This limits the time needed to search for parentheses. (default
431 20 lines).
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.
435 (default 30 lines).
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
440 lines.
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
450 "default").
451 - Any combination of indentations causes the line to have less than 0
452 indentation.
454 ==============================================================================
455 2. Indenting by expression *indent-expression*
457 The basics for using flexible indenting are explained in section |30.3| of the
458 user manual.
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|.
478 Do loops ~
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
490 follows >
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 SHELL *ft-sh-indent*
520 The amount of indent applied under various circumstances in a shell file can
521 be configured by setting the following keys in the |Dictionary|
522 b:sh_indent_defaults to a specific amount or to a |Funcref| that references a
523 function that will return the amount desired:
525 b:sh_indent_options['default'] Default amount of indent.
527 b:sh_indent_options['continuation-line']
528 Amount of indent to add to a continued line.
530 b:sh_indent_options['case-labels']
531 Amount of indent to add for case labels.
533 b:sh_indent_options['case-statement']
534 Amount of indent to add for case statements.
536 b:sh_indent_options['case-breaks']
537 Amount of indent to add (or more likely
538 remove) for case breaks.
540 VERILOG *ft-verilog-indent*
542 General block statements such as if, for, case, always, initial, function,
543 specify and begin, etc., are indented. The module block statements (first
544 level blocks) are not indented by default. you can turn on the indent with
545 setting a variable in the .vimrc as follows: >
547 let b:verilog_indent_modules = 1
549 then the module blocks will be indented. To stop this, remove the variable: >
551 :unlet b:verilog_indent_modules
553 To set the variable only for Verilog file. The following statements can be
554 used: >
556 au BufReadPost * if exists("b:current_syntax")
557 au BufReadPost * if b:current_syntax == "verilog"
558 au BufReadPost * let b:verilog_indent_modules = 1
559 au BufReadPost * endif
560 au BufReadPost * endif
562 Furthermore, setting the variable b:verilog_indent_width to change the
563 indenting width (default is 'shiftwidth'): >
565 let b:verilog_indent_width = 4
566 let b:verilog_indent_width = &sw * 2
568 In addition, you can turn the verbose mode for debug issue: >
570 let b:verilog_indent_verbose = 1
572 Make sure to do ":set cmdheight=2" first to allow the display of the message.
575 VHDL *ft-vhdl-indent*
577 Alignment of generic/port mapping statements are performed by default. This
578 causes the following alignment example: >
580 ENTITY sync IS
581 PORT (
582 clk : IN STD_LOGIC;
583 reset_n : IN STD_LOGIC;
584 data_input : IN STD_LOGIC;
585 data_out : OUT STD_LOGIC
586 );
587 END ENTITY sync;
589 To turn this off, add >
591 let g:vhdl_indent_genportmap = 0
593 to the .vimrc file, which causes the previous alignment example to change: >
595 ENTITY sync IS
596 PORT (
597 clk : IN STD_LOGIC;
598 reset_n : IN STD_LOGIC;
599 data_input : IN STD_LOGIC;
600 data_out : OUT STD_LOGIC
601 );
602 END ENTITY sync;
604 ----------------------------------------
606 Alignment of right-hand side assignment "<=" statements are performed by
607 default. This causes the following alignment example: >
609 sig_out <= (bus_a(1) AND
610 (sig_b OR sig_c)) OR
611 (bus_a(0) AND sig_d);
613 To turn this off, add >
615 let g:vhdl_indent_rhsassign = 0
617 to the .vimrc file, which causes the previous alignment example to change: >
619 sig_out <= (bus_a(1) AND
620 (sig_b OR sig_c)) OR
621 (bus_a(0) AND sig_d);
623 ----------------------------------------
625 Full-line comments (lines that begin with "--") are indented to be aligned with
626 the very previous line's comment, PROVIDED that a whitespace follows after
627 "--".
629 For example: >
631 sig_a <= sig_b; -- start of a comment
632 -- continuation of the comment
633 -- more of the same comment
635 While in Insert mode, after typing "-- " (note the space " "), hitting CTRL-F
636 will align the current "-- " with the previous line's "--".
638 If the very previous line does not contain "--", THEN the full-line comment
639 will be aligned with the start of the next non-blank line that is NOT a
640 full-line comment.
642 Indenting the following code: >
644 sig_c <= sig_d; -- comment 0
645 -- comment 1
646 -- comment 2
647 --debug_code:
648 --PROCESS(debug_in)
649 --BEGIN
650 -- FOR i IN 15 DOWNTO 0 LOOP
651 -- debug_out(8*i+7 DOWNTO 8*i) <= debug_in(15-i);
652 -- END LOOP;
653 --END PROCESS debug_code;
655 -- comment 3
656 sig_e <= sig_f; -- comment 4
657 -- comment 5
659 results in: >
661 sig_c <= sig_d; -- comment 0
662 -- comment 1
663 -- comment 2
664 --debug_code:
665 --PROCESS(debug_in)
666 --BEGIN
667 -- FOR i IN 15 DOWNTO 0 LOOP
668 -- debug_out(8*i+7 DOWNTO 8*i) <= debug_in(15-i);
669 -- END LOOP;
670 --END PROCESS debug_code;
672 -- comment 3
673 sig_e <= sig_f; -- comment 4
674 -- comment 5
676 Notice that "--debug_code:" does not align with "-- comment 2"
677 because there is no whitespace that follows after "--" in "--debug_code:".
679 Given the dynamic nature of indenting comments, indenting should be done TWICE.
680 On the first pass, code will be indented. On the second pass, full-line
681 comments will be indented according to the correctly indented code.
684 VIM *ft-vim-indent*
686 For indenting Vim scripts there is one variable that specifies the amount of
687 indent for a continuation line, a line that starts with a backslash: >
689 :let g:vim_indent_cont = &sw * 3
691 Three times shiftwidth is the default value.
694 vim:tw=78:ts=8:ft=help:norl: