Copyright © 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.

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.

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, see 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 (see Common styles).  You can prevent indent from reading the .indent.pro files by specifying the -npro option.

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

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.

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;

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.

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.  */

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.

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.

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;
     {
       . . .
     }

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.

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.

Option summary
==============

-bad
     Force blank lines after declarations.  See Blank lines.

-bap
     Force blank lines after procedure bodies.  See Blank lines.

-bbb
     Force blank lines after block comments.  See Blank lines.

-bc
     Force newline after comma in declaration.  See Declarations.

-bl
     Put braces on line after if, etc.  See Statements.

-br
     Put braces on line with if, etc.  See Statements.

-cN
     Put comments to the right of code in column N.  See Comments.

-cdN
     Put comments to the right of declarations in column N. See Comments.

-cdb
     Put comment delimiters on blank lines.  See Comments.

-ce
     Cuddle else and preceeding }.  See Comments.

-ciN
     Continuation indent of N spaces.  See Statements.

-cliN
     Case label indent of N spaces.  See Statements.

-cs
     Put a space after a cast operator.  See Statements.

-dN
     Set indentation of comments not to the right of code to N spaces. See Comments.

-diN
     Put variables in column N.  See Declarations.

-fc1
     Format comments in the first column.  See Comments.

-fca
     Do not disable all formatting of comments.  See Comments

-gnu
     Use GNU coding style.  See Common styles.

-iN
     Set indentation level to N spaces.  See Indentation.

-ipN
     Indent parameter types in old-style function defitions by N spaces. See Indentation.

-kr
     Use Kernighan & Ritchie coding style.  See Common styles.

-lN
     Set maximum line length to N.  See Comments.

-lp
     Line up continued lines at parentheses.  See Indentation.

-pcs
     Put a space after the function in function calls.  See Statements.

-nbad
     Do not force blank lines after declarations.  See Blank lines.

-nbap
     Do not force blank lines after procedure bodies.  See Blank lines.

-nbbb
     Do not force blanklines after block comments.  See Blank lines.

-nbc
     Do not force newlines after commas in declarations. See Declarations.

-ncdb
     Do not put comment delimiters on blank lines.  See Comments.

-nce
     Do not cuddle } and else.  See Statements.

-ncs
     Do not put a space after cast operators.

-nfc1
     Do not format comments in the first column as normal.  See Comments.

-nfca
     Do not format any comments.  See Comments.

-nlp
     Do not line up parentheses.  See Statements.

-npcs
     Do not put space after the function in function calls. See Statements.

-npsl
     Put the type of a procedure on the same line as its name. See Declarations.

-nsc
     Do not put the * character at the left of comments. See Comments.

-nsob
     Do not swallow optional blank lines.  See Blank lines.

-nv
     Disable verbose mode.  See Miscellaneous options.

-npro
     Do not read .indent.pro files.  See Invoking indent.

-psl
     Put the type of a procedure on the line before its name. See Declarations.

-sc
     Put the * character at the left of comments. See Comments.

-sob
     Swallow optional blank lines.  See Blank lines.

-st
     Read from standard input and write to standard output. See Invoking indent.

-troff
     Format the program for printing with troff. See Miscellaneous options.

-v
     Enable verbose mode.  See Miscellaneous options.

-version
     Output the version number of indent.  See Miscellaneous options.