1 *indent.txt* For Vim version 7.3. Last change: 2011 Sep 02
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 This file is about indenting C programs and other files.
9 1. Indenting C style programs |C-indenting|
10 2. Indenting by expression |indent-expression|
12 ==============================================================================
13 1. Indenting C style programs *C-indenting*
15 The basics for C style indenting are explained in section |30.2| of the user
18 Vim has options for automatically indenting C style program files. Many
19 programming languages including Java and C++ follow very closely the
20 formatting conventions established with C. These options affect only the
21 indent and do not perform other formatting. There are additional options that
22 affect other kinds of formatting as well as indenting, see |format-comments|,
23 |fo-table|, |gq| and |formatting| for the main ones.
25 Note that this will not work when the |+smartindent| or |+cindent| features
26 have been disabled at compile time.
28 There are in fact four main methods available for indentation, each one
29 overrides the previous if it is enabled, or non-empty for 'indentexpr':
30 'autoindent' uses the indent from the previous line.
31 'smartindent' is like 'autoindent' but also recognizes some C syntax to
32 increase/reduce the indent where appropriate.
33 'cindent' Works more cleverly than the other two and is configurable to
34 different indenting styles.
35 'indentexpr' The most flexible of all: Evaluates an expression to compute
36 the indent of a line. When non-empty this method overrides
37 the other ones. See |indent-expression|.
38 The rest of this section describes the 'cindent' option.
40 Note that 'cindent' indenting does not work for every code scenario. Vim
41 is not a C compiler: it does not recognize all syntax. One requirement is
42 that toplevel functions have a '{' in the first column. Otherwise they are
43 easily confused with declarations.
45 These four options control C program indenting:
46 'cindent' Enables Vim to perform C program indenting automatically.
47 'cinkeys' Specifies which keys trigger reindenting in insert mode.
48 'cinoptions' Sets your preferred indent style.
49 'cinwords' Defines keywords that start an extra indent in the next line.
51 If 'lisp' is not on and 'equalprg' is empty, the "=" operator indents using
52 Vim's built-in algorithm rather than calling an external program.
54 See |autocommand| for how to set the 'cindent' option automatically for C code
55 files and reset it for others.
57 *cinkeys-format* *indentkeys-format*
58 The 'cinkeys' option is a string that controls Vim's indenting in response to
59 typing certain characters or commands in certain contexts. Note that this not
60 only triggers C-indenting. When 'indentexpr' is not empty 'indentkeys' is
61 used instead. The format of 'cinkeys' and 'indentkeys' is equal.
63 The default is "0{,0},0),:,0#,!^F,o,O,e" which specifies that indenting occurs
66 "0{" if you type '{' as the first character in a line
67 "0}" if you type '}' as the first character in a line
68 "0)" if you type ')' as the first character in a line
69 ":" if you type ':' after a label or case statement
70 "0#" if you type '#' as the first character in a line
71 "!^F" if you type CTRL-F (which is not inserted)
72 "o" if you type a <CR> anywhere or use the "o" command (not in
74 "O" if you use the "O" command (not in insert mode!)
75 "e" if you type the second 'e' for an "else" at the start of a
78 Characters that can precede each key: *i_CTRL-F*
79 ! When a '!' precedes the key, Vim will not insert the key but will
80 instead reindent the current line. This allows you to define a
81 command key for reindenting the current line. CTRL-F is the default
82 key for this. Be careful if you define CTRL-I for this because CTRL-I
83 is the ASCII code for <Tab>.
84 * When a '*' precedes the key, Vim will reindent the line before
85 inserting the key. If 'cinkeys' contains "*<Return>", Vim reindents
86 the current line before opening a new line.
87 0 When a zero precedes the key (but appears after '!' or '*') Vim will
88 reindent the line only if the key is the first character you type in
89 the line. When used before "=" Vim will only reindent the line if
90 there is only white space before the word.
92 When neither '!' nor '*' precedes the key, Vim reindents the line after you
93 type the key. So ';' sets the indentation of a line which includes the ';'.
96 <> Angle brackets mean spelled-out names of keys. For example: "<Up>",
97 "<Ins>" (see |key-notation|).
98 ^ Letters preceded by a caret (^) are control characters. For example:
100 o Reindent a line when you use the "o" command or when Vim opens a new
101 line below the current one (e.g., when you type <Enter> in insert
103 O Reindent a line when you use the "O" command.
104 e Reindent a line that starts with "else" when you type the second 'e'.
105 : Reindent a line when a ':' is typed which is after a label or case
106 statement. Don't reindent for a ":" in "class::method" for C++. To
107 Reindent for any ":", use "<:>".
108 =word Reindent when typing the last character of "word". "word" may
109 actually be part of another word. Thus "=end" would cause reindenting
110 when typing the "d" in "endif" or "endwhile". But not when typing
111 "bend". Also reindent when completion produces a word that starts
112 with "word". "0=word" reindents when there is only white space before
114 =~word Like =word, but ignore case.
116 If you really want to reindent when you type 'o', 'O', 'e', '0', '<', '>',
117 '*', ':' or '!', use "<o>", "<O>", "<e>", "<0>", "<<>", "<>>", "<*>", "<:>" or
118 "<!>", respectively, for those keys.
120 For an emacs-style indent mode where lines aren't indented every time you
121 press <Enter> but only if you press <Tab>, I suggest:
122 :set cinkeys=0{,0},:,0#,!<Tab>,!^F
123 You might also want to switch off 'autoindent' then.
125 Note: If you change the current line's indentation manually, Vim ignores the
126 cindent settings for that line. This prevents vim from reindenting after you
127 have changed the indent by typing <BS>, <Tab>, or <Space> in the indent or
128 used CTRL-T or CTRL-D.
131 The 'cinoptions' option sets how Vim performs indentation. The value after
132 the option character can be one of these (N is any number):
134 -N indent N spaces to the left
135 Ns N times 'shiftwidth' spaces
136 -Ns N times 'shiftwidth' spaces to the left
139 "N" represents a number of your choice (the number can be negative). When
140 there is an 's' after the number, Vim multiplies the number by 'shiftwidth':
141 "1s" is 'shiftwidth', "2s" is two times 'shiftwidth', etc. You can use a
142 decimal point, too: "-0.5s" is minus half a 'shiftwidth'.
143 The examples below assume a 'shiftwidth' of 4.
145 >N Amount added for "normal" indent. Used after a line that should
146 increase the indent (lines starting with "if", an opening brace,
147 etc.). (default 'shiftwidth').
149 cino= cino=>2 cino=>2s >
150 if (cond) if (cond) if (cond)
156 eN Add N to the prevailing indent inside a set of braces if the
157 opening brace at the End of the line (more precise: is not the
158 first character in a line). This is useful if you want a
159 different indent when the '{' is at the start of the line from
160 when '{' is at the end of the line. (default 0).
162 cino= cino=e2 cino=e-2 >
163 if (cond) { if (cond) { if (cond) {
172 nN Add N to the prevailing indent for a statement after an "if",
173 "while", etc., if it is NOT inside a set of braces. This is
174 useful if you want a different indent when there is no '{'
175 before the statement from when there is a '{' before it.
178 cino= cino=n2 cino=n-2 >
179 if (cond) if (cond) if (cond)
187 fN Place the first opening brace of a function or other block in
188 column N. This applies only for an opening brace that is not
189 inside other braces and is at the start of the line. What comes
190 after the brace is put relative to this brace. (default 0).
192 cino= cino=f.5s cino=f1s >
195 int foo; int foo; int foo;
198 {N Place opening braces N characters from the prevailing indent.
199 This applies only for opening braces that are inside other
202 cino= cino={.5s cino={1s >
203 if (cond) if (cond) if (cond)
208 }N Place closing braces N characters from the matching opening
211 cino= cino={2,}-0.5s cino=}2 >
212 if (cond) if (cond) if (cond)
218 ^N Add N to the prevailing indent inside a set of braces if the
219 opening brace is in column 0. This can specify a different
220 indent for whole of a function (some may like to set it to a
221 negative number). (default 0).
223 cino= cino=^-2 cino=^-s >
226 if (cond) if (cond) if (cond)
233 LN Controls placement of jump labels. If N is negative, the label
234 will be placed at column 1. If N is non-negative, the indent of
235 the label will be the prevailing indent minus N. (default -1).
237 cino= cino=L2 cino=Ls >
247 :N Place case labels N characters from the indent of the switch().
248 (default 'shiftwidth').
259 =N Place statements occurring after a case label N characters from
260 the indent of the label. (default 'shiftwidth').
263 case 11: case 11: a = a + 1;
264 a = a + 1; b = b + 1;
267 lN If N != 0 Vim will align with a case label instead of the
268 statement after it in the same line.
271 switch (a) { switch (a) {
277 bN If N != 0 Vim will align a final "break" with the case label,
278 so that case..break looks like a sort of block. (default: 0).
279 When using 1, consider adding "0=break" to 'cinkeys'.
294 gN Place C++ scope declarations N characters from the indent of the
295 block they are in. (default 'shiftwidth'). A scope declaration
296 can be "public:", "protected:" or "private:".
306 hN Place statements occurring after a C++ scope declaration N
307 characters from the indent of the label. (default
311 public: public: a = a + 1;
312 a = a + 1; b = b + 1;
315 NN Indent inside C++ namespace N characters extra compared to a
316 normal block. (default 0).
319 namespace { namespace {
320 void function(); void function();
323 namespace my namespace my
325 void function(); void function();
329 pN Parameter declarations for K&R-style function declarations will
330 be indented N characters from the margin. (default
333 cino= cino=p0 cino=p2s >
334 func(a, b) func(a, b) func(a, b)
336 char b; char b; char b;
339 tN Indent a function return type declaration N characters from the
340 margin. (default 'shiftwidth').
342 cino= cino=t0 cino=t7 >
347 iN Indent C++ base class declarations and constructor
348 initializations, if they start in a new line (otherwise they
349 are aligned at the right side of the ':').
350 (default 'shiftwidth').
353 class MyClass : class MyClass :
354 public BaseClass public BaseClass
356 MyClass::MyClass() : MyClass::MyClass() :
357 BaseClass(3) BaseClass(3)
361 +N Indent a continuation line (a line that spills onto the next)
362 inside a function N additional characters. (default
364 Outside of a function, when the previous line ended in a
365 backslash, the 2 * N is used.
368 a = b + 9 * a = b + 9 *
372 cN Indent comment lines after the comment opener, when there is no
373 other text with which to align, N characters from the comment
374 opener. (default 3). See also |format-comments|.
382 CN When N is non-zero, indent comment lines by the amount specified
383 with the c flag above even if there is other text behind the
384 comment opener. (default 0).
390 < (Example uses ":set comments& comments-=s1:/* comments^=s0:/*")
393 /N Indent comment lines N characters extra. (default 0).
396 /* comment */ /* comment */
400 (N When in unclosed parentheses, indent N characters from the line
401 with the unclosed parentheses. Add a 'shiftwidth' for every
402 unclosed parentheses. When N is 0 or the unclosed parentheses
403 is the first non-white character in its line, line up with the
404 next non-white character after the unclosed parentheses.
405 (default 'shiftwidth' * 2).
408 if (c1 && (c2 || if (c1 && (c2 ||
412 (c2 || c3)) (c2 || c3))
416 uN Same as (N, but for one level deeper. (default 'shiftwidth').
419 if (c123456789 if (c123456789
420 && (c22345 && (c22345
424 UN When N is non-zero, do not ignore the indenting specified by
425 ( or u in case that the unclosed parentheses is the first
426 non-white character in its line. (default 0).
428 cino= or cino=(s cino=(s,U1 >
436 wN When in unclosed parentheses and N is non-zero and either
437 using "(0" or "u0", respectively, or using "U0" and the unclosed
438 parentheses is the first non-white character in its line, line
439 up with the character immediately after the unclosed parentheses
440 rather than the first non-white character. (default 0).
449 WN When in unclosed parentheses and N is non-zero and either
450 using "(0" or "u0", respectively and the unclosed parentheses is
451 the last non-white character in its line and it is not the
452 closing parentheses, indent the following line N characters
453 relative to the outer context (i.e. start of the line or the
454 next unclosed parentheses). (default: 0).
457 a_long_line( a_long_line(
459 argument); argument);
460 a_short_line(argument, a_short_line(argument,
461 argument); argument);
464 mN When N is non-zero, line up a line starting with a closing
465 parentheses with the first character of the line with the
466 matching opening parentheses. (default 0).
469 c = c1 && ( c = c1 && (
479 MN When N is non-zero, line up a line starting with a closing
480 parentheses with the first character of the previous line.
484 if (cond1 && if (cond1 &&
488 *java-cinoptions* *java-indenting* *cino-j*
489 jN Indent Java anonymous classes correctly. Also works well for
490 Javascript. The value 'N' is currently unused but must be
491 non-zero (e.g. 'j1'). 'j1' will indent for example the
492 following code snippet correctly: >
494 object.add(new ChangeListener() {
495 public void stateChanged(ChangeEvent e) {
500 *javascript-cinoptions* *javascript-indenting* *cino-J*
501 JN Indent JavaScript object declarations correctly by not confusing
502 them with labels. The value 'N' is currently unused but must be
503 non-zero (e.g. 'J1'). If you enable this you probably also want
520 )N Vim searches for unclosed parentheses at most N lines away.
521 This limits the time needed to search for parentheses. (default
525 *N Vim searches for unclosed comments at most N lines away. This
526 limits the time needed to search for the start of a comment.
527 If your /* */ comments stop indenting afer N lines this is the
528 value you will want to change.
532 #N When N is non-zero recognize shell/Perl comments, starting with
533 '#'. Default N is zero: don't recognizes '#' comments. Note
534 that lines starting with # will still be seen as preprocessor
538 The defaults, spelled out in full, are:
539 cinoptions=>s,e0,n0,f0,{0,}0,^0,L-1,:s,=s,l0,b0,gs,hs,N0,ps,ts,is,+s,
540 c3,C0,/0,(2s,us,U0,w0,W0,m0,j0,J0,)20,*70,#0
542 Vim puts a line in column 1 if:
543 - It starts with '#' (preprocessor directives), if 'cinkeys' contains '#'.
544 - It starts with a label (a keyword followed by ':', other than "case" and
545 "default") and 'cinoptions' does not contain an 'L' entry with a positive
547 - Any combination of indentations causes the line to have less than 0
550 ==============================================================================
551 2. Indenting by expression *indent-expression*
553 The basics for using flexible indenting are explained in section |30.3| of the
556 If you want to write your own indent file, it must set the 'indentexpr'
557 option. Setting the 'indentkeys' option is often useful. See the
558 $VIMRUNTIME/indent directory for examples.
561 REMARKS ABOUT SPECIFIC INDENT FILES ~
564 FORTRAN *ft-fortran-indent*
566 Block if, select case, where, and forall constructs are indented. So are
567 type, interface, associate, block, and enum constructs. The indenting of
568 subroutines, functions, modules, and program blocks is optional. Comments,
569 labelled statements and continuation lines are indented if the Fortran is in
570 free source form, whereas they are not indented if the Fortran is in fixed
571 source form because of the left margin requirements. Hence manual indent
572 corrections will be necessary for labelled statements and continuation lines
573 when fixed source form is being used. For further discussion of the method
574 used for the detection of source format see |ft-fortran-syntax|.
577 All do loops are left unindented by default. Do loops can be unstructured in
578 Fortran with (possibly multiple) loops ending on a labelled executable
579 statement of almost arbitrary type. Correct indentation requires
580 compiler-quality parsing. Old code with do loops ending on labelled statements
581 of arbitrary type can be indented with elaborate programs such as Tidy
582 (http://www.unb.ca/chem/ajit/f_tidy.htm). Structured do/continue loops are
583 also left unindented because continue statements are also used for purposes
584 other than ending a do loop. Programs such as Tidy can convert structured
585 do/continue loops to the do/enddo form. Do loops of the do/enddo variety can
586 be indented. If you use only structured loops of the do/enddo form, you should
587 declare this by setting the fortran_do_enddo variable in your .vimrc as
590 let fortran_do_enddo=1
592 in which case do loops will be indented. If all your loops are of do/enddo
593 type only in, say, .f90 files, then you should set a buffer flag with an
594 autocommand such as >
596 au! BufRead,BufNewFile *.f90 let b:fortran_do_enddo=1
598 to get do loops indented in .f90 files and left alone in Fortran files with
599 other extensions such as .for.
602 The indenting of program units (subroutines, functions, modules, and program
603 blocks) is enabled by default but can be suppressed if a lighter, screen-width
604 preserving indent style is desired. To suppress the indenting of program
605 units for all fortran files set the global fortran_indent_less variable in
606 your .vimrc as follows >
608 let fortran_indent_less=1
610 A finer level of suppression can be achieved by setting the corresponding
611 buffer-local variable as follows >
613 let b:fortran_indent_less=1
616 PHP *ft-php-indent* *php-indent* *php-indenting*
618 NOTE: PHP files will be indented correctly only if PHP |syntax| is active.
620 If you are editing a file in Unix 'fileformat' and '\r' characters are present
621 before new lines, indentation won't proceed correctly ; you have to remove
622 those useless characters first with a command like: >
626 Or, you can simply |:let| the variable PHP_removeCRwhenUnix to 1 and the
627 script will silently remove them when Vim loads a PHP file (at each|BufRead|).
631 PHP indenting can be altered in several ways by modifying the values of some
635 To not enable auto-formating of comments by default (if you want to use your
636 own 'formatoptions'): >
637 :let g:PHP_autoformatcomment = 0
639 Else, 't' will be removed from the 'formatoptions' string and "qrowcb" will be
640 added, see|fo-table|for more information.
643 To add an extra indent to every PHP lines with N being the number of
644 'shiftwidth' to add: >
645 :let g:PHP_default_indenting = N
647 For example, with N = 1, this will give:
650 if (!isset($History_lst_sel))
651 if (!isset($History_lst_sel))
652 if (!isset($History_lst_sel)) {
657 $command_hist = TRUE;
659 (Notice the extra indent between the PHP container markers and the code)
662 To indent PHP tags as the surrounding code: >
663 :let g:PHP_outdentphpescape = 0
666 To automatically remove '\r' characters when the 'fileformat' is set to Unix: >
667 :let g:PHP_removeCRwhenUnix = 1
670 To indent braces at the same level than the code they contain: >
671 :let g:PHP_BracesAtCodeLevel = 1
673 This will give the following result: >
684 NOTE: Indenting will be a bit slower if this option is used because some
685 optimizations won't be available.
688 To indent 'case:' and 'default:' statements in switch() blocks: >
689 :let g:PHP_vintage_case_default_indent = 1
691 (Since in PHP braces are not required inside 'case/default' blocks, by default they are indented at the same level than the 'switch()' to avoid
692 unnecessary indentation)
695 PYTHON *ft-python-indent*
697 The amount of indent can be set for the following situations. The examples
698 given are the defaults. Note that the variables are set to an expression, so
699 that you can change the value of 'shiftwidth' later.
701 Indent after an open paren: >
702 let g:pyindent_open_paren = '&sw * 2'
703 Indent after a nested paren: >
704 let g:pyindent_nested_paren = '&sw'
705 Indent for a continuation line: >
706 let g:pyindent_continue = '&sw * 2'
711 Function arguments are aligned if they span for multiple lines. If you prefer
712 do not have the arguments of functions aligned, put in your |vimrc|:
714 let r_indent_align_args = 0
716 All lines beginning with a comment character, #, get the same indentation
717 level of the normal R code. Users of Emacs/ESS may be used to have lines
718 beginning with a single # indented in the 40th column, ## indented as R code,
719 and ### not indented. If you prefer that lines beginning with comment
720 characters are aligned as they are by Emacs/ESS, put in your |vimrc|:
722 let r_indent_ess_comments = 1
724 If you prefer that lines beginning with a single # are aligned at a column
725 different from the 40th one, you should set a new value to the variable
726 r_indent_comment_column, as in the example below:
728 let r_indent_comment_column = 30
730 Any code after a line that ends with "<-" is indented. Emacs/ESS does not
731 indent the code if it is a top level function. If you prefer that the
732 Vim-R-plugin behaves like Emacs/ESS in this regard, put in your |vimrc|:
734 let r_indent_ess_compatible = 1
736 Below is an example of indentation with and without this option enabled:
738 ### r_indent_ess_compatible = 1 ### r_indent_ess_compatible = 0
740 function(x) function(x)
748 The amount of indent applied under various circumstances in a shell file can
749 be configured by setting the following keys in the |Dictionary|
750 b:sh_indent_defaults to a specific amount or to a |Funcref| that references a
751 function that will return the amount desired:
753 b:sh_indent_options['default'] Default amount of indent.
755 b:sh_indent_options['continuation-line']
756 Amount of indent to add to a continued line.
758 b:sh_indent_options['case-labels']
759 Amount of indent to add for case labels.
760 (not actually implemented)
762 b:sh_indent_options['case-statements']
763 Amount of indent to add for case statements.
765 b:sh_indent_options['case-breaks']
766 Amount of indent to add (or more likely
767 remove) for case breaks.
769 VERILOG *ft-verilog-indent*
771 General block statements such as if, for, case, always, initial, function,
772 specify and begin, etc., are indented. The module block statements (first
773 level blocks) are not indented by default. you can turn on the indent with
774 setting a variable in the .vimrc as follows: >
776 let b:verilog_indent_modules = 1
778 then the module blocks will be indented. To stop this, remove the variable: >
780 :unlet b:verilog_indent_modules
782 To set the variable only for Verilog file. The following statements can be
785 au BufReadPost * if exists("b:current_syntax")
786 au BufReadPost * if b:current_syntax == "verilog"
787 au BufReadPost * let b:verilog_indent_modules = 1
788 au BufReadPost * endif
789 au BufReadPost * endif
791 Furthermore, setting the variable b:verilog_indent_width to change the
792 indenting width (default is 'shiftwidth'): >
794 let b:verilog_indent_width = 4
795 let b:verilog_indent_width = &sw * 2
797 In addition, you can turn the verbose mode for debug issue: >
799 let b:verilog_indent_verbose = 1
801 Make sure to do ":set cmdheight=2" first to allow the display of the message.
804 VHDL *ft-vhdl-indent*
806 Alignment of generic/port mapping statements are performed by default. This
807 causes the following alignment example: >
812 reset_n : IN STD_LOGIC;
813 data_input : IN STD_LOGIC;
814 data_out : OUT STD_LOGIC
818 To turn this off, add >
820 let g:vhdl_indent_genportmap = 0
822 to the .vimrc file, which causes the previous alignment example to change: >
827 reset_n : IN STD_LOGIC;
828 data_input : IN STD_LOGIC;
829 data_out : OUT STD_LOGIC
833 ----------------------------------------
835 Alignment of right-hand side assignment "<=" statements are performed by
836 default. This causes the following alignment example: >
838 sig_out <= (bus_a(1) AND
840 (bus_a(0) AND sig_d);
842 To turn this off, add >
844 let g:vhdl_indent_rhsassign = 0
846 to the .vimrc file, which causes the previous alignment example to change: >
848 sig_out <= (bus_a(1) AND
850 (bus_a(0) AND sig_d);
852 ----------------------------------------
854 Full-line comments (lines that begin with "--") are indented to be aligned with
855 the very previous line's comment, PROVIDED that a whitespace follows after
860 sig_a <= sig_b; -- start of a comment
861 -- continuation of the comment
862 -- more of the same comment
864 While in Insert mode, after typing "-- " (note the space " "), hitting CTRL-F
865 will align the current "-- " with the previous line's "--".
867 If the very previous line does not contain "--", THEN the full-line comment
868 will be aligned with the start of the next non-blank line that is NOT a
871 Indenting the following code: >
873 sig_c <= sig_d; -- comment 0
879 -- FOR i IN 15 DOWNTO 0 LOOP
880 -- debug_out(8*i+7 DOWNTO 8*i) <= debug_in(15-i);
882 --END PROCESS debug_code;
885 sig_e <= sig_f; -- comment 4
890 sig_c <= sig_d; -- comment 0
896 -- FOR i IN 15 DOWNTO 0 LOOP
897 -- debug_out(8*i+7 DOWNTO 8*i) <= debug_in(15-i);
899 --END PROCESS debug_code;
902 sig_e <= sig_f; -- comment 4
905 Notice that "--debug_code:" does not align with "-- comment 2"
906 because there is no whitespace that follows after "--" in "--debug_code:".
908 Given the dynamic nature of indenting comments, indenting should be done TWICE.
909 On the first pass, code will be indented. On the second pass, full-line
910 comments will be indented according to the correctly indented code.
915 For indenting Vim scripts there is one variable that specifies the amount of
916 indent for a continuation line, a line that starts with a backslash: >
918 :let g:vim_indent_cont = &sw * 3
920 Three times shiftwidth is the default value.
923 vim:tw=78:ts=8:ft=help:norl: