Info file: indent.info, -*-Text-*- produced by texinfo-format-buffer from file: indent.texinfo Copyright (C) 1989 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this documentation provided that the copyright notice and this permission notice are preserved on all copies. File: indent.info Node: Top, Prev: (dir), Up: (dir) `indent': Indent and Format C Program Source ********************************************* The `indent' program changes the appearance of a C program by inserting or deleting whitespace. It can be used to make code easier to read. It can also convert from one style of writing C to another. `indent' understands a substantial amount about the syntax of C, but it also attempts to cope with incomplete and misformed syntax. * Menu: * Invoking indent:: How to run the indent program. * Common styles:: Common styles of formatting C programs. * Blank lines:: Options to control addition or deletion of blank lines. * Comments:: How indent affects comments. * Statements:: Options involving statements. * Declarations:: Options involving declarations. * Indentation:: How far each line is indented from the left margin. * Miscellaneous options:: Troff and verbose modes, and getting indent's version number. * Copyright:: Copyright notice for the indent program. * Option summary:: Alphabetical list of options with short descriptions. File: indent.info Node: Invoking indent, Prev: Top, Up: Top, Next: Common styles Invoking `indent' ================= The format of the `indent' command is: indent [INPUT-FILE [OUTPUT-FILE]] [OPTIONS] Options begin with `-', and can appear anywhere in the command. These options control how programs are formatted (for a list of options, *Note Option summary::). For example, to indent the program `munch.c' and write the indented C program to `munch.out', you would use the command indent munch.c munch.out If an input file is specified but no output file is specified, the formatted file is written back into the input file, and a backup copy of the input file is written in the current directory. The name of the backup copy is formed by adding `.BAK' to the end of the name of the input file. For example: indent -br test/munch.c -l85 This will indent the program `test/munch.c' using the `-br' and `-l85' options, write the output back to `test/munch.c', and copy the original contents of `test/munch.c' to `munch.c.BAK' in the current directory. Note that it does not work to type `indent *.c' to indent all the programs in a directory. The shell expands this command into a command such as `indent foo.c bar.c baz.c'. If there are more than 2 files in the current directory ending in `.c', you will get an error message; if there are exactly 2 such files you will overwrite the second one with the indented version of the first. The exact command to indent all the C programs in the current directory depends on what shell you are using; for `bash' or similar shells you would use the following: for file in *.c; do indent $file done To cause `indent' to read from standard input and write to standard output, use the `-st' option. If an input file (and/or output file) is specified in addition to `-st', `indent' will use the specified file rather than standard input (and/or output). If you find that you often use `indent' with the same options, you may put those options into a file called `.indent.pro'. Upon starting up, `indent' first reads `.indent.pro' in the your login directory, then reads `.indent.pro' in the current directory, and then processes command line switches. Options specified later override arguments specified earlier, with one exception: Explicitly specified options always override background options (*Note Common styles::). You can prevent `indent' from reading the `.indent.pro' files by specifying the `-npro' option. File: indent.info Node: Common styles, Prev: Invoking indent, Up: Top, Next: Blank lines Common styles ============= There are a number of common styles of formatting C code. These include the default `indent' style, the GNU style, and the Kernighan & Ritchie style. `indent' allows you to select one of these styles with a single "background" option. A background option provides settings for all other options, but explicitly specified options always override options implied by a background option. If you do not give any background option, `indent' will use its own list of default options. The indent defaults were decided at the University of California at Berkeley, which originally wrote `indent'. The indent defaults are: -nbap -nbad -nbbb -bc -br -c33 -cd33 -cdb -ce -ci4 -cli0 -d4 -di16 -fc1 -i4 -ip4 -l75 -lp -npcs -psl -sc -nsob -fca -cp33 -nss The Kernighan & Ritchie style is the one used in their influential book `The C Programming Language'. It is enabled with the `-kr' option. The Kernighan & Ritchie style corresponds to the following set of options: -nbad -bap -nbbb -nbc -br -c33 -cd33 -ncdb -ce -ci4 -cli0 -d0 -di1 -nfc1 -i4 -ip0 -l75 -lp -npcs -npsl -nsc -nsob -nfca -cp33 -nss Kernighan & Ritchie do not put comments to the right of code in the same column at all times (nor do they use only one space to the right of the code), so `indent' in this mode has arbitrarily picked column 33. The GNU coding style is the preferred style for writing code for the GNU project. It is also the style that the GNU emacs C mode encourages. People interested in writing programs for GNU should get a copy of the GNU coding standards, which also cover semantic issues such as memory usage, the size of integers, etc. To tell `indent' to use GNU coding standards, specify the `-gnu' option, which has the same effect as the following options: -nbad -bap -nbbb -nbc -bl -c33 -cd33 -ncdb -nce -di0 -nfc1 -i2 -ip5 -lp -pcs -psl -nsc -nsob -bli2 -ss -cp1 -nfca -cli0 File: indent.info Node: Blank lines, Prev: Common styles, Up: Top, Next: Comments Blank lines =========== Various programming styles use blank lines in different places. `indent' has a number of options to insert or delete blank lines in specific places. The `-bad' option causes `indent' to force a blank line after every block of declarations. The `-nbad' option causes `indent' not to force such blank lines. The `-bap' option forces a blank line after every procedure body. The `-nbap' option forces no such blank line. The `-bbb' option forces a blank line before every block comment. The exact definition of a block comment is unclear. The `-nbbb' option does not force such blank lines. The `-sob' option causes `indent' to swallow optional blank lines (that is, any optional blank lines present in the input will be removed from the output). If the `-nsob' is specified, any blank lines present in the input file will be copied to the output file. * Menu: * -bad:: More on the `-bad' option. * -bap:: More on the `-bap' option. File: indent.info Node: -bad, Prev: Blank lines, Up: Blank lines, Next: -bap The `-bad' option forces a blank line after every block of declarations. The `-nbad' option does not add any such blank lines. For example, given the input char *foo; char *bar; /* This separates blocks of declarations. */ int baz; `indent -bad' produces char *foo; char *bar; /* This separates blocks of declarations. */ int baz; and `indent -nbad' produces char *foo; char *bar; /* This separates blocks of declarations. */ int baz; File: indent.info Node: -bap, Prev: -bad, Up: Blank lines The `-bap' option forces a blank line after every procedure body. For example, given the input int foo () { puts("Hi"); } /* The procedure bar is even less interesting. */ char * bar () { puts("Hello"); } `indent -bap' produces int foo () { puts ("Hi"); } /* The procedure bar is even less interesting. */ char * bar () { puts ("Hello"); } and `indent -nbap' produces int foo () { puts ("Hi"); } /* The procedure bar is even less interesting. */ char * bar () { puts ("Hello"); } There is a bug with `-nbap' whereby if the end of a procedure is followed by something such as the name of a type, with no intervening comment, the blank line will not be added. For example, given the input int foo () { puts ("Hi"); } char * bar () { puts ("Hello"); } no blank line will be added after the procedure `foo'. File: indent.info Node: Comments, Prev: Blank lines, Up: Top, Next: Statements Comments ======== By default, `indent' treats comments as straight text. Newlines in the input file are ignored and as many words (separated by blanks, tabs, or newlines) as possible are put onto a line in the output file. Blank lines break paragraphs. The length of the lines in the output file is controlled by the `-l' numeric option. Because this reformatting will often not give good results, it can be disabled with the `-nfca' option, which is also implicitly specified by the `-gnu' and `-kr' options. All comments starting with `-' or `*' immediately following the opening `/*' are assumed to be carefully formatted, so reformatting is disabled. If comments starting in the first column have been carefully formatted, the `-nfc1' option can be used to disable reformatting of such comments. In cases where reformatting is disabled, the indentation of a comment may still be adjusted. The indentation of comments which do not appear to the right of code is set by the `-d' option, which specifies the number of spaces to the left of the surrounding code that the comment appears. For example, `-d2' places comments two spaces to the left of code; `-d0' lines up comments with the code. The `-cdb' option controls whether the `/*' and `*/' are placed on blank lines. With `-cdb', comments look like this: /* * this is a comment */ With `-ncdb', comments look like this: /* this is a comment */ `-cdb' only affects block comments, not comments to the right of code. Comments which appear on the same line as code are placed to the right. The column in which comments on code start is controlled by the `-c' option. The column in which comments to the right of declarations start is controlled by the `-cd' option. By default, they start in the same column as comments to the right of code. The column number for comments to the right of `#else' and `#endif' statements is controlled by the `-cp' option. If the code on a line extends past the comment column, the comment starts further to the right, and the right margin may be automatically extended in extreme cases. If the `-sc' option is specified, `*' is placed at the left edge of all comments. For example: /* This is a comment which extends from one line onto the next line, * thus causing us to consider how it should continue. */ instead of /* This is a comment which extends from one line onto the next line, thus causing us to consider how it should continue. */ File: indent.info Node: Statements, Prev: Comments, Up: Top, Next: Declarations Statements ========== Use the `-br' or `-bl' option to specify how you want braces to be formatted. Using `-br' lines up braces like this: if (x > 0) { x--; } Using `-bl' makes them look like this: if (x > 0) { x--; } If you use the `-bl' option, you may also want to specify the `-bli' option. This option gives the number of spaces that the braces are indented. `-bli0' gives the result shown above. `-bli2' results in the following appearance: if (x > 0) { x--; } The `-ce' option causes the `else' in an if-then-else construct to cuddle up to the immediately preceding `}'. For example, with `-ce' you would get if (x > 0) { x--; } else { fprintf (stderr, "You seem to have done something wrong.\n"); } With `-nce' that code would appear as if (x > 0) { x--; } else { fprintf (stderr, "You seem to have done something wrong.\n"); } The `-cli' option specifies the number of spaces that case labels should be indented to the right of the containing `switch' statement. If a semicolon is on the same line as a `for' or `while' statement, the `-ss' option will cause a space to be placed before the semicolon. This emphasizes the semicolon, making it clear that the body of the `for' or `while' statement is an empty statement. The `-pcs' option causes a space to be placed between the name of the procedure being called and the `(' (for example `puts ("Hi");'. The `-npcs' option would give `puts("Hi");'). If the `-cs' option is specified, `indent' puts a space after a cast operator. File: indent.info Node: Declarations, Prev: Statements, Up: Top, Next: Indentation Declarations ============ By default `indent' will line up identifiers, in the column specified by the `-di' option. For example, the default `-di16' makes things look like: int foo; char * bar; The `-di1' option can be used to cause the indentifiers to be placed in the first available position, for example int foo; char *bar; If the `-bc' option is specified, a newline is forced after each comma in a declaration. For example, int a, b, c; With the `-nbc' option this would look like int a, b, c; The `-psl' option causes the type of a procedure being defined to be placed on the line before the name of the procedure. This style is required for the `etags' program to work correctly. If you are not using the `-di1' option to place variables being declared immediately after their type, you will need to use the `-T' option to tell `indent' the name of all the typenames in your program that are defined by `typedef'. `-T' can be specified more than once, and all names specified are used. For example, if your program contains typedef unsigned long CODE_ADDR; typedef enum {red, blue, green} COLOR; you would use the options `-T CODE_ADDR -T COLOR'. File: indent.info Node: Indentation, Prev: Declarations, Up: Top, Next: Miscellaneous options Indentation =========== One issue in the formatting of code is how far each line should be indented from the left margin. Both on reading the input and writing the output `indent' assumes that tabs are placed at eight character intervals. A tab is treated no differently than the number of spaces that correspond to the effect of the tab. When the beginning of a statement such as `if' or `for' is encountered, the indentation level is increased by the value specified by the `-i' option. For example, use `-i8' to specify an eight character indentation for each level. When a statement is continued from a previous line, it is indented by a number of additional spaces specified by the `-ci' option. `-ci' defaults to the same value as `-i'. However, if the `-lp' option is specified, and a line has a left parenthesis which is not closed on that line, then continuation lines will be lined up to start at the character position just after the left parenthesis. This processing also applies to `[' and applies to `{' when it occurs in initialization lists. For example, a piece of continued code might look like this with `-nlp -ci3' in effect: p1 = first_procedure (second_procedure (p2, p3), third_procedure (p4, p5)); With `-lp' in effect the code looks somewhat clearer: p1 = first_procedure (second_procedure (p2, p3), third_procedure (p4, p5)); The indentation of type declarations in old-style function definitions is controlled by the `-ip' parameter. This is a numeric parameter specifying how many spaces to indent type declarations. For example, with `-ip5' specified a function definition might look like this: char * create_world (x, y, scale) int x; int y; float scale; { . . . } File: indent.info Node: Miscellaneous options, Prev: Indentation, Up: Top, Next: Copyright Miscellaneous options ===================== To find out what version of `indent' you have, use the command `indent -version'. This will report the version number of `indent', without doing any of the normal processing. If you are printing your program, you may wish to use the `-troff' option to produce output suitable for processing by the `troff' program. When the `-troff' option is specified, if the output file is not specified, the default is standard output, rather than formatting in place. The `-v' option can be used to turn on verbose mode. When in verbose mode, `indent' reports when it splits one line of input into two more more lines of output, and gives some size statistics at completion. File: indent.info Node: Copyright, Prev: Miscellaneous options, Up: Top, Next: Option summary Copyright ========= Copyright (c) 1989 Free Software Foundation Copyright (c) 1985 Sun Microsystems, Inc. Copyright (c) 1980 The Regents of the University of California. Copyright (c) 1976 Board of Trustees of the University of Illinois. All rights reserved. Redistribution and use in source and binary forms are permitted provided that the above copyright notice and this paragraph are duplicated in all such forms and that any documentation, advertising materials, and other materials related to such distribution and use acknowledge that the software was developed by the University of California, Berkeley, the University of Illinois, Urbana, and Sun Microsystems, Inc. The name of either University or Sun Microsystems may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. File: indent.info Node: Option summary, Prev: Copyright, Up: Top Option summary ============== `-bad' Force blank lines after declarations. *Note Blank lines::. `-bap' Force blank lines after procedure bodies. *Note Blank lines::. `-bbb' Force blank lines after block comments. *Note Blank lines::. `-bc' Force newline after comma in declaration. *Note Declarations::. `-bl' Put braces on line after `if', etc. *Note Statements::. `-br' Put braces on line with `if', etc. *Note Statements::. `-cN' Put comments to the right of code in column N. *Note Comments::. `-cdN' Put comments to the right of declarations in column N. *Note Comments::. `-cdb' Put comment delimiters on blank lines. *Note Comments::. `-ce' Cuddle else and preceeding `}'. *Note Comments::. `-ciN' Continuation indent of N spaces. *Note Statements::. `-cliN' Case label indent of N spaces. *Note Statements::. `-cs' Put a space after a cast operator. *Note Statements::. `-dN' Set indentation of comments not to the right of code to N spaces. *Note Comments::. `-diN' Put variables in column N. *Note Declarations::. `-fc1' Format comments in the first column. *Note Comments::. `-fca' Do not disable all formatting of comments. *Note Comments:: `-gnu' Use GNU coding style. *Note Common styles::. `-iN' Set indentation level to N spaces. *Note Indentation::. `-ipN' Indent parameter types in old-style function defitions by N spaces. *Note Indentation::. `-kr' Use Kernighan & Ritchie coding style. *Note Common styles::. `-lN' Set maximum line length to N. *Note Comments::. `-lp' Line up continued lines at parentheses. *Note Indentation::. `-pcs' Put a space after the function in function calls. *Note Statements::. `-nbad' Do not force blank lines after declarations. *Note Blank lines::. `-nbap' Do not force blank lines after procedure bodies. *Note Blank lines::. `-nbbb' Do not force blanklines after block comments. *Note Blank lines::. `-nbc' Do not force newlines after commas in declarations. *Note Declarations::. `-ncdb' Do not put comment delimiters on blank lines. *Note Comments::. `-nce' Do not cuddle `}' and `else'. *Note Statements::. `-ncs' Do not put a space after cast operators. `-nfc1' Do not format comments in the first column as normal. *Note Comments::. `-nfca' Do not format any comments. *Note Comments::. `-nlp' Do not line up parentheses. *Note Statements::. `-npcs' Do not put space after the function in function calls. *Note Statements::. `-npsl' Put the type of a procedure on the same line as its name. *Note Declarations::. `-nsc' Do not put the `*' character at the left of comments. *Note Comments::. `-nsob' Do not swallow optional blank lines. *Note Blank lines::. `-nv' Disable verbose mode. *Note Miscellaneous options::. `-npro' Do not read `.indent.pro' files. *Note Invoking indent::. `-psl' Put the type of a procedure on the line before its name. *Note Declarations::. `-sc' Put the `*' character at the left of comments. *Note Comments::. `-sob' Swallow optional blank lines. *Note Blank lines::. `-st' Read from standard input and write to standard output. *Note Invoking indent::. `-troff' Format the program for printing with `troff'. *Note Miscellaneous options::. `-v' Enable verbose mode. *Note Miscellaneous options::. `-version' Output the version number of `indent'. *Note Miscellaneous options::.