diff options
Diffstat (limited to 'runtime/doc/indent.txt')
| -rw-r--r-- | runtime/doc/indent.txt | 522 |
1 files changed, 522 insertions, 0 deletions
diff --git a/runtime/doc/indent.txt b/runtime/doc/indent.txt new file mode 100644 index 000000000..a35ce54ce --- /dev/null +++ b/runtime/doc/indent.txt @@ -0,0 +1,522 @@ +*indent.txt* For Vim version 7.0aa. Last change: 2004 Apr 25 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +This file is about indenting C programs and other files. + +1. Indenting C programs |C-indenting| +2. Indenting by expression |indent-expression| + +============================================================================== +1. Indenting C programs *C-indenting* + +The basics for C indenting are explained in section |30.2| of the user manual. + +Vim has options for automatically indenting C program files. These options +affect only the indent and do not perform other formatting. For comment +formatting, see |format-comments|. + +Note that this will not work when the |+smartindent| or |+cindent| features +have been disabled at compile time. + +There are in fact four methods available for indentation: +'autoindent' uses the indent from the previous line. +'smartindent' is like 'autoindent' but also recognizes some C syntax to + increase/reduce the indent where appropriate. +'cindent' Works more cleverly than the other two and is configurable to + different indenting styles. +'indentexpr' The most flexible of all: Evaluates an expression to compute + the indent of a line. When non-empty this method overrides + the other ones. See |indent-expression|. +The rest of this section describes the 'cindent' option. + +Note that 'cindent' indenting does not work for every code scenario. Vim +is not a C compiler: it does not recognize all syntax. + +These four options control C program indenting: +'cindent' Enables Vim to perform C program indenting automatically. +'cinkeys' Specifies which keys trigger reindenting in insert mode. +'cinoptions' Sets your preferred indent style. +'cinwords' Defines keywords that start an extra indent in the next line. + +If 'lisp' is not on and 'equalprg' is empty, the "=" operator indents using +Vim's built-in algorithm rather than calling an external program. + +See |autocommand| for how to set the 'cindent' option automatically for C code +files and reset it for others. + + *cinkeys-format* *indentkeys-format* +The 'cinkeys' option is a string that controls Vim's indenting in response to +typing certain characters or commands in certain contexts. Note that this not +only triggers C-indenting. When 'indentexpr' is not empty 'indentkeys' is +used instead. The format of 'cinkeys' and 'indentkeys' is equal. + +The default is "0{,0},0),:,0#,!^F,o,O,e" which specifies that indenting occurs +as follows: + + "0{" if you type '{' as the first character in a line + "0}" if you type '}' as the first character in a line + "0)" if you type ')' as the first character in a line + ":" if you type ':' after a label or case statement + "0#" if you type '#' as the first character in a line + "!^F" if you type CTRL-F (which is not inserted) + "o" if you type a <CR> anywhere or use the "o" command (not in + insert mode!) + "O" if you use the "O" command (not in insert mode!) + "e" if you type the second 'e' for an "else" at the start of a + line + +Characters that can precede each key: +! When a '!' precedes the key, Vim will not insert the key but will + instead reindent the current line. This allows you to define a + command key for reindenting the current line. CTRL-F is the default + key for this. Be careful if you define CTRL-I for this because CTRL-I + is the ASCII code for <Tab>. +* When a '*' precedes the key, Vim will reindent the line before + inserting the key. If 'cinkeys' contains "*<Return>", Vim reindents + the current line before opening a new line. +0 When a zero precedes the key (but appears after '!' or '*') Vim will + reindent the line only if the key is the first character you type in + the line. When used before "=" Vim will only reindent the line if + there is only white space before the word. + +When neither '!' nor '*' precedes the key, Vim reindents the line after you +type the key. So ';' sets the indentation of a line which includes the ';'. + +Special key names: +<> Angle brackets mean spelled-out names of keys. For example: "<Up>", + "<Ins>" (see |key-notation|). +^ Letters preceded by a caret (^) are control characters. For example: + "^F" is CTRL-F. +o Reindent a line when you use the "o" command or when Vim opens a new + line below the current one (e.g., when you type <Enter> in insert + mode). +O Reindent a line when you use the "O" command. +e Reindent a line that starts with "else" when you type the second 'e'. +: Reindent a line when a ':' is typed which is after a label or case + statement. Don't reindent for a ":" in "class::method" for C++. To + Reindent for any ":", use "<:>". +=word Reindent when typing the last character of "word". "word" may + actually be part of another word. Thus "=end" would cause reindenting + when typing the "d" in "endif" or "endwhile". But not when typing + "bend". Also reindent when completion produces a word that starts + with "word". "0=word" reindents when there is only white space before + the word. +=~word Like =word, but ignore case. + +If you really want to reindent when you type 'o', 'O', 'e', '0', '<', '>', +'*', ':' or '!', use "<o>", "<O>", "<e>", "<0>", "<<>", "<>>", "<*>", "<:>" or +"<!>", respectively, for those keys. + +For an emacs-style indent mode where lines aren't indented every time you +press Enter but only if you press Tab, I suggest: + :set cinkeys=0{,0},:,0#,!<Tab>,!^F +You might also want to switch off 'autoindent' then. + +Note: If you change the current line's indentation manually, Vim ignores the +cindent settings for that line. This prevents vim from reindenting after you +have changed the indent by typing <BS>, <Tab>, or <Space> in the indent or +used CTRL-T or CTRL-D. + + *cinoptions-values* +The 'cinoptions' option sets how Vim performs indentation. In the list below, +"N" represents a number of your choice (the number can be negative). When +there is an 's' after the number, Vim multiplies the number by 'shiftwidth': +"1s" is 'shiftwidth', "2s" is two times 'shiftwidth', etc. You can use a +decimal point, too: "-0.5s" is minus half a 'shiftwidth'. The examples below +assume a 'shiftwidth' of 4. + + >N Amount added for "normal" indent. Used after a line that should + increase the indent (lines starting with "if", an opening brace, + etc.). (default 'shiftwidth'). + + cino= cino=>2 cino=>2s > + if (cond) if (cond) if (cond) + { { { + foo; foo; foo; + } } } +< + eN Add N to the prevailing indent inside a set of braces if the + opening brace at the End of the line (more precise: is not the + first character in a line). This is useful if you want a + different indent when the '{' is at the start of the line from + when '{' is at the end of the line. (default 0). + + cino= cino=e2 cino=e-2 > + if (cond) { if (cond) { if (cond) { + foo; foo; foo; + } } } + else else else + { { { + bar; bar; bar; + } } } +< + nN Add N to the prevailing indent for a statement after an "if", + "while", etc., if it is NOT inside a set of braces. This is + useful if you want a different indent when there is no '{' + before the statement from when there is a '{' before it. + (default 0). + + cino= cino=n2 cino=n-2 > + if (cond) if (cond) if (cond) + foo; foo; foo; + else else else + { { { + bar; bar; bar; + } } } +< + fN Place the first opening brace of a function or other block in + column N. This applies only for an opening brace that is not + inside other braces and is at the start of the line. What comes + after the brace is put relative to this brace. (default 0). + + cino= cino=f.5s cino=f1s > + func() func() func() + { { { + int foo; int foo; int foo; +< + {N Place opening braces N characters from the prevailing indent. + This applies only for opening braces that are inside other + braces. (default 0). + + cino= cino={.5s cino={1s > + if (cond) if (cond) if (cond) + { { { + foo; foo; foo; +< + }N Place closing braces N characters from the matching opening + brace. (default 0). + + cino= cino={2,}-0.5s cino=}2 > + if (cond) if (cond) if (cond) + { { { + foo; foo; foo; + } } } +< + ^N Add N to the prevailing indent inside a set of braces if the + opening brace is in column 0. This can specify a different + indent for whole of a function (some may like to set it to a + negative number). (default 0). + + cino= cino=^-2 cino=^-s > + func() func() func() + { { { + if (cond) if (cond) if (cond) + { { { + a = b; a = b; a = b; + } } } + } } } +< + :N Place case labels N characters from the indent of the switch(). + (default 'shiftwidth'). + + cino= cino=:0 > + switch (x) switch(x) + { { + case 1: case 1: + a = b; a = b; + default: default: + } } +< + =N Place statements occurring after a case label N characters from + the indent of the label. (default 'shiftwidth'). + + cino= cino==10 > + case 11: case 11: a = a + 1; + a = a + 1; b = b + 1; +< + lN If N != 0 Vim will align with a case label instead of the + statement after it in the same line. + + cino= cino=l1 > + switch (a) { switch (a) { + case 1: { case 1: { + break; break; + } } +< + bN If N != 0 Vim will align a final "break" with the case label, + so that case..break looks like a sort of block. (default: 0). + + cino= cino=b1 > + switch (x) switch(x) + { { + case 1: case 1: + a = b; a = b; + break; break; + + default: default: + a = 0; a = 0; + break; break; + } } +< + gN Place C++ scope declarations N characters from the indent of the + block they are in. (default 'shiftwidth'). A scope declaration + can be "public:", "protected:" or "private:". + + cino= cino=g0 > + { { + public: public: + a = b; a = b; + private: private: + } } +< + hN Place statements occurring after a C++ scope declaration N + characters from the indent of the label. (default + 'shiftwidth'). + + cino= cino=h10 > + public: public: a = a + 1; + a = a + 1; b = b + 1; +< + pN Parameter declarations for K&R-style function declarations will + be indented N characters from the margin. (default + 'shiftwidth'). + + cino= cino=p0 cino=p2s > + func(a, b) func(a, b) func(a, b) + int a; int a; int a; + char b; char b; char b; +< + tN Indent a function return type declaration N characters from the + margin. (default 'shiftwidth'). + + cino= cino=t0 cino=t7 > + int int int + func() func() func() +< + iN Indent C++ base class declarations and contructor + initializations, if they start in a new line (otherwise they + are aligned at the right side of the ':'). + (default 'shiftwidth'). + + cino= cino=i0 > + class MyClass : class MyClass : + public BaseClass public BaseClass + {} {} + MyClass::MyClass() : MyClass::MyClass() : + BaseClass(3) BaseClass(3) + {} {} +< + +N Indent a continuation line (a line that spills onto the next) N + additional characters. (default 'shiftwidth'). + + cino= cino=+10 > + a = b + 9 * a = b + 9 * + c; c; +< + cN Indent comment lines after the comment opener, when there is no + other text with which to align, N characters from the comment + opener. (default 3). See also |format-comments|. + + cino= cino=c5 > + /* /* + text. text. + */ */ +< + CN When N is non-zero, indent comment lines by the amount specified + with the c flag above even if there is other text behind the + comment opener. (default 0). + + cino=c0 cino=c0,C1 > + /******** /******** + text. text. + ********/ ********/ +< (Example uses ":set comments& comments-=s1:/* comments^=s0:/*") + + /N Indent comment lines N characters extra. (default 0). + cino= cino=/4 > + a = b; a = b; + /* comment */ /* comment */ + c = d; c = d; +< + (N When in unclosed parentheses, indent N characters from the line + with the unclosed parentheses. Add a 'shiftwidth' for every + unclosed parentheses. When N is 0 or the unclosed parentheses + is the first non-white character in its line, line up with the + next non-white character after the unclosed parentheses. + (default 'shiftwidth' * 2). + + cino= cino=(0 > + if (c1 && (c2 || if (c1 && (c2 || + c3)) c3)) + foo; foo; + if (c1 && if (c1 && + (c2 || c3)) (c2 || c3)) + { { +< + uN Same as (N, but for one level deeper. (default 'shiftwidth'). + + cino= cino=u2 > + if (c123456789 if (c123456789 + && (c22345 && (c22345 + || c3)) || c3)) +< + UN When N is non-zero, do not ignore the indenting specified by + ( or u in case that the unclosed parentheses is the first + non-white character in its line. (default 0). + + cino= or cino=(s cino=(s,U1 > + c = c1 && c = c1 && + ( ( + c2 || c2 || + c3 c3 + ) && c4; ) && c4; +< + wN When in unclosed parentheses and N is non-zero and either + using "(0" or "u0", respectively, or using "U0" and the unclosed + parentheses is the first non-white character in its line, line + up with the character immediately after the unclosed parentheses + rather than the first non-white character. (default 0). + + cino=(0 cino=(0,w1 > + if ( c1 if ( c1 + && ( c2 && ( c2 + || c3)) || c3)) + foo; foo; +< + WN When in unclosed parentheses and N is non-zero and either + using "(0" or "u0", respectively and the unclosed parentheses is + the last non-white character in its line and it is not the + closing parentheses, indent the following line N characters + relative to the outer context (i.e. start of the line or the + next unclosed parentheses). (default: 0). + + cino=(0 cino=(0,W4 > + a_long_line( a_long_line( + argument, argument, + argument); argument); + a_short_line(argument, a_short_line(argument, + argument); argument); +< + mN When N is non-zero, line up a line starting with a closing + parentheses with the first character of the line with the + matching opening parentheses. (default 0). + + cino=(s cino=(s,m1 > + c = c1 && ( c = c1 && ( + c2 || c2 || + c3 c3 + ) && c4; ) && c4; + if ( if ( + c1 && c2 c1 && c2 + ) ) + foo; foo; +< + *java-cinoptions* *java-indenting* + jN Indent java anonymous classes correctly. The value 'N' is + currently unused but must be non-zero (e.g. 'j1'). 'j1' will + indent for example the following code snippet correctly: > + + object.add(new ChangeListener() { + public void stateChanged(ChangeEvent e) { + do_something(); + } + }); +< + )N Vim searches for unclosed parentheses at most N lines away. + This limits the time needed to search for parentheses. (default + 20 lines). + + *N Vim searches for unclosed comments at most N lines away. This + limits the time needed to search for the start of a comment. + (default 30 lines). + + +The defaults, spelled out in full, are: + cinoptions=>s,e0,n0,f0,{0,}0,^0,:s,=s,l0,gs,hs,ps,ts,+s,c3,C0,(2s,us, + \U0,w0,m0,j0,)20,*30 + +Vim puts a line in column 1 if: +- It starts with '#' (preprocessor directives), if 'cinkeys' contains '#'. +- It starts with a label (a keyword followed by ':', other than "case" and + "default"). +- Any combination of indentations causes the line to have less than 0 + indentation. + +============================================================================== +2. Indenting by expression *indent-expression* + +The basics for using flexible indenting are explained in section |30.3| of the +user manual. + +If you want to write your own indent file, it must set the 'indentexpr' +option. Setting the 'indentkeys' option is often useful. See the +$VIMRUNTIME/indent directory for examples. + + +REMARKS ABOUT SPECIFIC INDENT FILES ~ + + +FORTRAN *fortran-indent* + +Block if, select case, and where constructs are indented. Comments, labelled +statements and continuation lines are indented if the Fortran is in free +source form, whereas they are not indented if the Fortran is in fixed source +form because of the left margin requirements. Hence manual indent corrections +will be necessary for labelled statements and continuation lines when fixed +source form is being used. For further discussion of the method used for the +detection of source format see |fortran-syntax|. + +Do loops ~ +All do loops are left unindented by default. Do loops can be unstructured in +Fortran with (possibly multiple) loops ending on a labelled executable +statement of almost arbitrary type. Correct indentation requires +compiler-quality parsing. Old code with do loops ending on labelled statements +of arbitrary type can be indented with elaborate programs such as Tidy +(http://www.unb.ca/chem/ajit/f_tidy.htm). Structured do/continue loops are +also left unindented because continue statements are also used for purposes +other than ending a do loop. Programs such as Tidy can convert structured +do/continue loops to the do/enddo form. Do loops of the do/enddo variety can +be indented. If you use only structured loops of the do/enddo form, you should +declare this by setting the fortran_do_enddo variable in your .vimrc as +follows > + + let fortran_do_enddo=1 + +in which case do loops will be indented. If all your loops are of do/enddo +type only in, say, .f90 files, then you should set a buffer flag with an +autocommand such as > + + au! BufRead,BufNewFile *.f90 let b:fortran_do_enddo=1 + +to get do loops indented in .f90 files and left alone in Fortran files with +other extensions such as .for. + + +VERILOG *verilog-indent* + +General block statements such as if, for, case, always, initial, function, +specify and begin, etc., are indented. The module block statements (first +level blocks) are not indented by default. you can turn on the indent with +setting a variable in the .vimrc as follows: > + + let b:verilog_indent_modules = 1 + +then the module blocks will be indented. To stop this, remove the variable: > + + :unlet b:verilog_indent_modules + +To set the variable only for Verilog file. The following statements can be +used: > + + au BufReadPost * if exists("b:current_syntax") + au BufReadPost * if b:current_syntax == "verilog" + au BufReadPost * let b:verilog_indent_modules = 1 + au BufReadPost * endif + au BufReadPost * endif + +Furthermore, setting the variable b:verilog_indent_width to change the +indenting width (default is 'shiftwidth'): > + + let b:verilog_indent_width = 4 + let b:verilog_indent_width = &sw * 2 + +In addition, you can turn the verbose mode for debug issue: > + + let b:verilog_indent_verbose = 1 + +Make sure to do ":set cmdheight=2" first to allow the display of the message. + + vim:tw=78:ts=8:ft=help:norl: |