blob: e00358334a0d21addb94221c1af2697b086385b5 [file] [log] [blame]
Bram Moolenaar1423b9d2006-05-07 15:16:06 +00001*indent.txt* For Vim version 7.0. Last change: 2006 Apr 30
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7This file is about indenting C programs and other files.
8
91. Indenting C programs |C-indenting|
102. Indenting by expression |indent-expression|
11
12==============================================================================
131. Indenting C programs *C-indenting*
14
15The basics for C indenting are explained in section |30.2| of the user manual.
16
17Vim has options for automatically indenting C program files. These options
18affect only the indent and do not perform other formatting. For comment
19formatting, see |format-comments|.
20
21Note that this will not work when the |+smartindent| or |+cindent| features
22have been disabled at compile time.
23
24There 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|.
33The rest of this section describes the 'cindent' option.
34
35Note that 'cindent' indenting does not work for every code scenario. Vim
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +000036is not a C compiler: it does not recognize all syntax. One requirement is
37that toplevel functions have a '{' in the first column. Otherwise they are
38easily confused with declarations.
Bram Moolenaar071d4272004-06-13 20:20:40 +000039
40These 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.
45
46If 'lisp' is not on and 'equalprg' is empty, the "=" operator indents using
47Vim's built-in algorithm rather than calling an external program.
48
49See |autocommand| for how to set the 'cindent' option automatically for C code
50files and reset it for others.
51
52 *cinkeys-format* *indentkeys-format*
53The 'cinkeys' option is a string that controls Vim's indenting in response to
54typing certain characters or commands in certain contexts. Note that this not
55only triggers C-indenting. When 'indentexpr' is not empty 'indentkeys' is
56used instead. The format of 'cinkeys' and 'indentkeys' is equal.
57
58The default is "0{,0},0),:,0#,!^F,o,O,e" which specifies that indenting occurs
59as follows:
60
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
72
Bram Moolenaare2f98b92006-03-29 21:18:24 +000073Characters that can precede each key: *i_CTRL-F*
Bram Moolenaar071d4272004-06-13 20:20:40 +000074! 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.
820 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.
86
87When neither '!' nor '*' precedes the key, Vim reindents the line after you
88type the key. So ';' sets the indentation of a line which includes the ';'.
89
90Special 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.
95o 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).
98O Reindent a line when you use the "O" command.
99e 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.
110
111If 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.
114
115For an emacs-style indent mode where lines aren't indented every time you
116press Enter but only if you press Tab, I suggest:
117 :set cinkeys=0{,0},:,0#,!<Tab>,!^F
118You might also want to switch off 'autoindent' then.
119
120Note: If you change the current line's indentation manually, Vim ignores the
121cindent settings for that line. This prevents vim from reindenting after you
122have changed the indent by typing <BS>, <Tab>, or <Space> in the indent or
123used CTRL-T or CTRL-D.
124
125 *cinoptions-values*
126The '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
128there 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
130decimal point, too: "-0.5s" is minus half a 'shiftwidth'. The examples below
131assume a 'shiftwidth' of 4.
132
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').
136
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).
148
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).
163
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).
176
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).
185
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).
193
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).
204
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').
216
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').
227
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.
234
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,
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000242 so that case..break looks like a sort of block. (default: 0).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000243
244 cino= cino=b1 >
245 switch (x) switch(x)
246 { {
247 case 1: case 1:
248 a = b; a = b;
249 break; break;
250
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:".
259
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').
270
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').
278
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').
286
287 cino= cino=t0 cino=t7 >
288 int int int
289 func() func() func()
290<
Bram Moolenaar551dbcc2006-04-25 22:13:59 +0000291 iN Indent C++ base class declarations and constructor
Bram Moolenaar071d4272004-06-13 20:20:40 +0000292 initializations, if they start in a new line (otherwise they
293 are aligned at the right side of the ':').
294 (default 'shiftwidth').
295
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').
306
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|.
314
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).
323
324 cino=c0 cino=c0,C1 >
325 /******** /********
326 text. text.
327 ********/ ********/
328< (Example uses ":set comments& comments-=s1:/* comments^=s0:/*")
329
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000330 /N Indent comment lines N characters extra. (default 0).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000331 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).
342
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').
352
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).
361
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).
374
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
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000386 next unclosed parentheses). (default: 0).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000387
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).
398
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<
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000409 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).
412
413 cino= cino=M1 >
414 if (cond1 && if (cond1 &&
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000415 cond2 cond2
416 ) )
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000417<
Bram Moolenaar071d4272004-06-13 20:20:40 +0000418 *java-cinoptions* *java-indenting*
419 jN Indent java anonymous classes correctly. The value 'N' is
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000420 currently unused but must be non-zero (e.g. 'j1'). 'j1' will
Bram Moolenaar071d4272004-06-13 20:20:40 +0000421 indent for example the following code snippet correctly: >
422
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).
432
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).
436
437
438The defaults, spelled out in full, are:
Bram Moolenaar8299df92004-07-10 09:47:34 +0000439 cinoptions=>s,e0,n0,f0,{0,}0,^0,:s,=s,l0,b0,gs,hs,ps,ts,is,+s,c3,C0,
440 /0,(2s,us,U0,w0,W0,m0,j0,)20,*30
Bram Moolenaar071d4272004-06-13 20:20:40 +0000441
442Vim puts a line in column 1 if:
443- It starts with '#' (preprocessor directives), if 'cinkeys' contains '#'.
444- It starts with a label (a keyword followed by ':', other than "case" and
445 "default").
446- Any combination of indentations causes the line to have less than 0
447 indentation.
448
449==============================================================================
4502. Indenting by expression *indent-expression*
451
452The basics for using flexible indenting are explained in section |30.3| of the
453user manual.
454
455If you want to write your own indent file, it must set the 'indentexpr'
456option. Setting the 'indentkeys' option is often useful. See the
457$VIMRUNTIME/indent directory for examples.
458
459
460REMARKS ABOUT SPECIFIC INDENT FILES ~
461
462
Bram Moolenaarda2303d2005-08-30 21:55:26 +0000463FORTRAN *ft-fortran-indent*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000464
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000465Block if, select case, and where constructs are indented. Comments, labelled
Bram Moolenaar071d4272004-06-13 20:20:40 +0000466statements and continuation lines are indented if the Fortran is in free
467source form, whereas they are not indented if the Fortran is in fixed source
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000468form because of the left margin requirements. Hence manual indent corrections
Bram Moolenaar071d4272004-06-13 20:20:40 +0000469will be necessary for labelled statements and continuation lines when fixed
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000470source form is being used. For further discussion of the method used for the
Bram Moolenaarda2303d2005-08-30 21:55:26 +0000471detection of source format see |ft-fortran-syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000472
473Do loops ~
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000474All do loops are left unindented by default. Do loops can be unstructured in
Bram Moolenaar071d4272004-06-13 20:20:40 +0000475Fortran with (possibly multiple) loops ending on a labelled executable
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000476statement of almost arbitrary type. Correct indentation requires
477compiler-quality parsing. Old code with do loops ending on labelled statements
Bram Moolenaar071d4272004-06-13 20:20:40 +0000478of arbitrary type can be indented with elaborate programs such as Tidy
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000479(http://www.unb.ca/chem/ajit/f_tidy.htm). Structured do/continue loops are
Bram Moolenaar071d4272004-06-13 20:20:40 +0000480also left unindented because continue statements are also used for purposes
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000481other than ending a do loop. Programs such as Tidy can convert structured
482do/continue loops to the do/enddo form. Do loops of the do/enddo variety can
483be indented. If you use only structured loops of the do/enddo form, you should
Bram Moolenaar071d4272004-06-13 20:20:40 +0000484declare this by setting the fortran_do_enddo variable in your .vimrc as
485follows >
486
487 let fortran_do_enddo=1
488
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000489in which case do loops will be indented. If all your loops are of do/enddo
Bram Moolenaar071d4272004-06-13 20:20:40 +0000490type only in, say, .f90 files, then you should set a buffer flag with an
491autocommand such as >
492
493 au! BufRead,BufNewFile *.f90 let b:fortran_do_enddo=1
494
495to get do loops indented in .f90 files and left alone in Fortran files with
496other extensions such as .for.
497
498
Bram Moolenaarda2303d2005-08-30 21:55:26 +0000499PYTHON *ft-python-indent*
Bram Moolenaar05159a02005-02-26 23:04:13 +0000500
501The amount of indent can be set for the following situations. The examples
502given are de the defaults. Note that the variables are set to an expression,
503so that you can change the value of 'shiftwidth' later.
504
505Indent after an open paren: >
506 let g:pyindent_open_paren = '&sw * 2'
507Indent after a nested paren: >
508 let g:pyindent_nested_paren = '&sw'
509Indent for a continuation line: >
510 let g:pyindent_continue = '&sw * 2'
511
512
Bram Moolenaarda2303d2005-08-30 21:55:26 +0000513VERILOG *ft-verilog-indent*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000514
515General block statements such as if, for, case, always, initial, function,
516specify and begin, etc., are indented. The module block statements (first
517level blocks) are not indented by default. you can turn on the indent with
518setting a variable in the .vimrc as follows: >
519
520 let b:verilog_indent_modules = 1
521
522then the module blocks will be indented. To stop this, remove the variable: >
523
524 :unlet b:verilog_indent_modules
525
526To set the variable only for Verilog file. The following statements can be
527used: >
528
529 au BufReadPost * if exists("b:current_syntax")
530 au BufReadPost * if b:current_syntax == "verilog"
531 au BufReadPost * let b:verilog_indent_modules = 1
532 au BufReadPost * endif
533 au BufReadPost * endif
534
535Furthermore, setting the variable b:verilog_indent_width to change the
536indenting width (default is 'shiftwidth'): >
537
538 let b:verilog_indent_width = 4
539 let b:verilog_indent_width = &sw * 2
540
541In addition, you can turn the verbose mode for debug issue: >
542
543 let b:verilog_indent_verbose = 1
544
545Make sure to do ":set cmdheight=2" first to allow the display of the message.
546
Bram Moolenaard4755bb2004-09-02 19:12:26 +0000547
Bram Moolenaarda2303d2005-08-30 21:55:26 +0000548VIM *ft-vim-indent*
Bram Moolenaard4755bb2004-09-02 19:12:26 +0000549
550For indenting Vim scripts there is one variable that specifies the amount of
551indent for a continuation line, a line that starts with a backslash: >
552
553 :let g:vim_indent_cont = &sw * 3
554
555Three times shiftwidth is the default value.
556
557
Bram Moolenaar071d4272004-06-13 20:20:40 +0000558 vim:tw=78:ts=8:ft=help:norl: