xref: /csrg-svn/usr.bin/indent/indent.1 (revision 63700)
1*63700Sbostic.\" Copyright (c) 1980, 1990, 1993
2*63700Sbostic.\"	The Regents of the University of California.  All rights reserved.
335500Sbostic.\" Copyright (c) 1976 Board of Trustees of the University of Illinois.
435500Sbostic.\" All rights reserved.
519718Smckusick.\"
650518Scael.\" %sccs.include.redist.roff%
719718Smckusick.\"
8*63700Sbostic.\"	@(#)indent.1	8.1 (Berkeley) 07/01/93
943083Scael.\"
1043083Scael.Dd
1143083Scael.Dt INDENT 1
1250519Scael.Os BSD 4.2
1343083Scael.Sh NAME
1443083Scael.Nm indent
1543083Scael.Nd indent and format C program source
1643083Scael.Sh SYNOPSIS
1743083Scael.Nm indent
1843083Scael.Op Ar input-file Op Ar output-file
1950518Scael.Op Fl bad | Fl nbad
2050518Scael.Op Fl bap | Fl nbap
2150518Scael.Bk -words
2250518Scael.Op Fl bbb | Fl nbbb
2350518Scael.Ek
2450518Scael.Op Fl \&bc | Fl nbc
2550518Scael.Op Fl \&bl
2650518Scael.Op Fl \&br
2750518Scael.Op Fl c Ns Ar n
2850518Scael.Op Fl \&cd Ns Ar n
2950518Scael.Bk -words
3050518Scael.Op Fl cdb | Fl ncdb
3150518Scael.Ek
3250518Scael.Op Fl \&ce | Fl nce
3350518Scael.Op Fl \&ci Ns Ar n
3450518Scael.Op Fl cli Ns Ar n
3550518Scael.Op Fl d Ns Ar n
3650518Scael.Op Fl \&di Ns Ar n
3750518Scael.Bk -words
3850518Scael.Op Fl fc1 | Fl nfc1
3950518Scael.Ek
4050518Scael.Op Fl i Ns Ar n
4150518Scael.Op Fl \&ip | Fl nip
4250518Scael.Op Fl l Ns Ar n
4350518Scael.Op Fl \&lc Ns Ar n
4450518Scael.Op Fl \&lp | Fl nlp
4543083Scael.Op Fl npro
4650518Scael.Op Fl pcs | Fl npcs
4750518Scael.Op Fl psl | Fl npsl
4850518Scael.Op Fl \&sc | Fl nsc
4950518Scael.Bk -words
5050518Scael.Op Fl sob | Fl nsob
5150518Scael.Ek
5250518Scael.Op Fl \&st
5343083Scael.Op Fl troff
5450518Scael.Op Fl v | Fl \&nv
5543083Scael.Sh DESCRIPTION
5643083Scael.Nm Indent
5743083Scaelis a
5843083Scael.Ar C
5943083Scaelprogram formatter.  It reformats the
6043083Scael.Ar C
6143083Scaelprogram in the
6243083Scael.Ar input-file
6343083Scaelaccording to the switches.  The switches which can be
6424459Smckusickspecified are described below. They may appear before or after the file
6524459Smckusicknames.
6643083Scael.Pp
6743083Scael.Sy NOTE  :
6843083ScaelIf you only specify an
6943083Scael.Ar input-file  ,
7043083Scaelthe formatting is
7124459Smckusickdone `in-place', that is, the formatted file is written back into
7243083Scael.Ar input-file
7324459Smckusickand a backup copy of
7443083Scael.Ar input-file
7524459Smckusickis written in the current directory.  If
7643083Scael.Ar input-file
7743083Scaelis named
7843083Scael.Sq Pa /blah/blah/file ,
7943083Scaelthe backup file is named
8043083Scael.Pa file.BAK .
8143083Scael.Pp
8219718SmckusickIf
8343083Scael.Ar output-file
8419718Smckusickis specified,
8543083Scael.Nm indent
8619718Smckusickchecks to make sure it is different from
8743083Scael.Ar input-file  .
8843083Scael.Pp
8924459SmckusickThe options listed below control the formatting style imposed by
9043083Scael.Nm indent  .
9150518Scael.Bl -tag -width Op
9250518Scael.It Fl bad , nbad
9336973SbosticIf
9443083Scael.Fl bad
9536973Sbosticis specified, a blank line is forced after every block of
9643083Scaeldeclarations.  Default:
9743083Scael.Fl nbad  .
9850518Scael.It Fl bap , nbap
9935500SbosticIf
10043083Scael.Fl bap
10135500Sbosticis specified, a blank line is forced after every procedure body.  Default:
10243083Scael.Fl nbap .
10350518Scael.It Fl bbb , nbbb
10424459SmckusickIf
10543083Scael.Fl bbb
10624459Smckusickis specified, a blank line is forced before every block comment.  Default:
10743083Scael.Fl nbbb .
10850518Scael.It Fl \&bc , nbc
10919718SmckusickIf
11050518Scael.Fl \&bc
11143083Scaelis specified, then a newline is forced after each comma in a declaration.
11243083Scael.Fl nbc
11324459Smckusickturns off this option.  The default is
11450518Scael.Fl \&bc  .
11550518Scael.It Fl \&br , \&bl
11619718SmckusickSpecifying
11750518Scael.Fl \&bl
11824459Smckusicklines up compound statements like this:
11919718Smckusick.ne 4
12050518Scael.Bd -literal -offset indent
12143083Scaelif (...)
12243083Scael{
12343083Scael  code
12443083Scael}
12550518Scael.Ed
12650518Scael.Pp
12719718SmckusickSpecifying
12850518Scael.Fl \&br
12924459Smckusick(the default) makes them look like this:
13019718Smckusick.ne 3
13150518Scael.Bd -literal -offset indent
13243083Scaelif (...) {
13343083Scael  code
13443083Scael}
13550518Scael.Ed
13643083Scael.Pp
13750518Scael.It Fl c n
13843083ScaelThe column in which comments on code start.  The default is 33.
13950518Scael.It Fl cd n
14024459SmckusickThe column in which comments on declarations start.  The default
14124459Smckusickis for these comments to start in the same column as those on code.
14250518Scael.It Fl cdb , ncdb
14324459SmckusickEnables (disables) the placement of comment delimiters on blank lines.  With
14424459Smckusickthis option enabled, comments look like this:
14550518Scael.Bd -literal -offset indent
14624459Smckusick.ne 3
14724459Smckusick	/*
14843083Scael	* this is a comment
14943083Scael	*/
15050518Scael.Ed
15150518Scael.Pp
15224459SmckusickRather than like this:
15350518Scael.Bd -literal -offset indent
15424459Smckusick	/* this is a comment */
15550518Scael.Ed
15650518Scael.Pp
15736973SbosticThis only affects block comments, not comments to the right of
15836973Sbosticcode.  The default is
15943083Scael.Fl cdb  .
16050518Scael.It Fl ce , nce
16136973SbosticEnables (disables) forcing `else's to cuddle up to the immediately preceding
16224459Smckusick`}'.  The default is
16350518Scael.Fl \&ce  .
16450518Scael.It Fl \&ci Ns Ar n
16543083ScaelSets the continuation indent to be
16643083Scael.Ar n  .
16743083ScaelContinuation
16824459Smckusicklines will be indented that far from the beginning of the first line of the
16924459Smckusickstatement.  Parenthesized expressions have extra indentation added to
17043083Scaelindicate the nesting, unless
17150518Scael.Fl \&lp
17243083Scaelis in effect.
17350518Scael.Fl \&ci
17443083Scaeldefaults to the same value as
17543083Scael.Fl i  .
17650518Scael.It Fl cli Ns Ar n
17724459SmckusickCauses case labels to be indented
17843083Scael.Ar n
17943083Scaeltab stops to the right of the containing
18043083Scael.Ic switch
18143083Scaelstatement.
18243083Scael.Fl cli0 .5
18343083Scaelcauses case labels to be indented half a tab stop.  The
18424459Smckusickdefault is
18543083Scael.Fl cli0  .
18650518Scael.It Fl d Ns Ar n
18724459SmckusickControls the placement of comments which are not to the
18835500Sbosticright of code.  The default
18950518Scael.Fl \&d\&1
19024459Smckusickmeans that such comments are placed one indentation level to the
19135500Sbosticleft of code.  Specifying
19250518Scael.Fl \&d\&0
19324459Smckusicklines up these comments with the code.  See the section on comment
19424459Smckusickindentation below.
19550518Scael.It Fl \&di Ns Ar n
19624459SmckusickSpecifies the indentation, in character positions, from a declaration keyword
19724459Smckusickto the following identifier.  The default is
19843083Scael.Fl di16  .
19950518Scael.It Fl dj , ndj
20050518Scael.Fl \&dj
20124459Smckusickleft justifies declarations.
20243083Scael.Fl ndj
20324459Smckusickindents declarations the same as code.  The default is
20443083Scael.Fl ndj  .
20550518Scael.It Fl \&ei , nei
20624459SmckusickEnables (disables) special
20743083Scael.Ic else-if
20843083Scaelprocessing.  If it's enabled, an
20943083Scael.Ic if
21043083Scaelfollowing an
21143083Scael.Ic else
21236973Sbosticwill have the same indentation as the preceding
21350518Scael.Ic \&if
21443083Scaelstatement.
21550518Scael.It Fl fc1 , nfc1
21624459SmckusickEnables (disables) the formatting of comments that start in column 1.
21724459SmckusickOften, comments whose leading `/' is in column 1 have been carefully
21843083Scaelhand formatted by the programmer.  In such cases,
21943083Scael.Fl nfc1
22043083Scaelshould be
22143083Scaelused.  The default is
22243083Scael.Fl fc1  .
22350518Scael.It Fl i Ns Ar n
22435500SbosticThe number of spaces for one indentation level.  The default is 4.
22550518Scael.It Fl \&ip , nip
22624459SmckusickEnables (disables) the indentation of parameter declarations from the left
22724459Smckusickmargin.  The default is
22850518Scael.Fl \&ip  .
22950518Scael.It Fl l Ns Ar n
23035500SbosticMaximum length of an output line.  The default is 75.
23150518Scael.It Fl \&lp , nlp
23224459SmckusickLines up code surrounded by parenthesis in continuation lines.  If a line
23324459Smckusickhas a left paren which is not closed on that line, then continuation lines
23424459Smckusickwill be lined up to start at the character position just after the left
23536973Sbosticparen.  For example, here is how a piece of continued code looks with
23643083Scael.Fl nlp
23743083Scaelin effect:
23824459Smckusick.ne 2
23950518Scael.Bd -literal -offset indent
24063699Smckusickp1 = first_procedure(second_procedure(p2, p3),
24163699Smckusick\ \ third_procedure(p4,p5));
24250518Scael.Ed
24350518Scael.Pp
24424459Smckusick.ne 5
24543083ScaelWith
24643083Scael.Fl lp
24743083Scaelin effect (the default) the code looks somewhat clearer:
24850518Scael.Bd -literal -offset indent
24963699Smckusickp1\ =\ first_procedure(second_procedure(p2,\ p3),
25063699Smckusick\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,p5));
25150518Scael.Ed
25250518Scael.Pp
25324459Smckusick.ne 5
25436973SbosticInserting two more newlines we get:
25550518Scael.Bd -literal -offset indent
25663699Smckusickp1\ =\ first_procedure(second_procedure(p2,
25763699Smckusick\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p3),
25863699Smckusick\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4
25963699Smckusick\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p5));
26050518Scael.Ed
26150518Scael.It Fl npro
26243083ScaelCauses the profile files,
26343083Scael.Sq Pa ./.indent.pro
26443083Scaeland
26543083Scael.Sq Pa ~/.indent.pro ,
26643083Scaelto be ignored.
26750518Scael.It Fl pcs , npcs
26843083ScaelIf true
26943083Scael.Pq Fl pcs
27043083Scaelall procedure calls will have a space inserted between
27143083Scaelthe name and the `('.  The default is
27243083Scael.Fl npcs  .
27350518Scael.It Fl psl , npsl
27443083ScaelIf true
27543083Scael.Pq Fl psl
27643083Scaelthe names of procedures being defined are placed in
27724459Smckusickcolumn 1 \- their types, if any, will be left on the previous lines.  The
27843083Scaeldefault is
27943083Scael.Fl psl  .
28050518Scael.It Fl \&sc , nsc
28124459SmckusickEnables (disables) the placement of asterisks (`*'s) at the left edge of all
28235500Sbosticcomments.
28350518Scael.It Fl sob , nsob
28419718SmckusickIf
28543083Scael.Fl sob
28624459Smckusickis specified, indent will swallow optional blank lines.  You can use this to
28724459Smckusickget rid of blank lines after declarations.  Default:
28843083Scael.Fl nsob  .
28950518Scael.It Fl \&st
29024459SmckusickCauses
29143083Scael.Nm indent
29224459Smckusickto take its input from stdin, and put its output to stdout.
29350518Scael.It Fl T Ns Ar typename
29424459SmckusickAdds
29543083Scael.Ar typename
29624459Smckusickto the list of type keywords.  Names accumulate:
29743083Scael.Fl T
29824459Smckusickcan be specified more than once.  You need to specify all the typenames that
29943083Scaelappear in your program that are defined by
30043083Scael.Ic typedef
30143083Scael\- nothing will be
30224459Smckusickharmed if you miss a few, but the program won't be formatted as nicely as
30324459Smckusickit should.  This sounds like a painful thing to have to do, but it's really
30443083Scaela symptom of a problem in C:
30543083Scael.Ic typedef
30643083Scaelcauses a syntactic change in the
30743083Scaellanguage and
30843083Scael.Nm indent
30943083Scaelcan't find all
31043083Scaelinstances of
31143083Scael.Ic typedef .
31250518Scael.It Fl troff
31324459SmckusickCauses
31443083Scael.Nm indent
31550518Scaelto format the program for processing by
31650518Scael.Xr troff 1 .
31750518ScaelIt will produce a fancy
31824459Smckusicklisting in much the same spirit as
31943083Scael.Xr vgrind 1 .
32024459SmckusickIf the output file is not specified, the default is standard output,
32124459Smckusickrather than formatting in place.
32250518Scael.It Fl v , \&nv
32343083Scael.Fl v
32436973Sbosticturns on `verbose' mode;
32550518Scael.Fl \&nv
32624459Smckusickturns it off.  When in verbose mode,
32743083Scael.Nm indent
32824459Smckusickreports when it splits one line of input into two or more lines of output,
32924459Smckusickand gives some size statistics at completion. The default is
33050518Scael.Fl \&nv  .
33150518Scael.El
33243083Scael.Pp
33324459SmckusickYou may set up your own `profile' of defaults to
33443083Scael.Nm indent
33524459Smckusickby creating a file called
33643083Scael.Pa .indent.pro
33736973Sbosticin your login directory and/or the current directory and including
33835500Sbosticwhatever switches you like.  A `.indent.pro' in the current directory takes
33935500Sbosticprecedence over the one in your login directory.  If
34043083Scael.Nm indent
34124459Smckusickis run and a profile file exists, then it is read to set up the program's
34235500Sbosticdefaults.  Switches on the command line, though, always override profile
34335500Sbosticswitches.  The switches should be separated by spaces, tabs or newlines.
34443083Scael.Pp
34543083Scael.Ss Comments
34643083Scael.Sq Em Box
34743083Scael.Em comments .
34843083Scael.Nm Indent
34924459Smckusickassumes that any comment with a dash or star immediately after the start of
35024459Smckusickcomment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars.
35124459SmckusickEach line of such a comment is left unchanged, except that its indentation
35224459Smckusickmay be adjusted to account for the change in indentation of the first line
35324459Smckusickof the comment.
35443083Scael.Pp
35543083Scael.Em Straight text .
35624459SmckusickAll other comments are treated as straight text.
35743083Scael.Nm Indent
35824459Smckusickfits as many words (separated by blanks, tabs, or newlines) on a
35924459Smckusickline as possible.  Blank lines break paragraphs.
36043083Scael.Pp
36143083Scael.Ss Comment indentation
36224459SmckusickIf a comment is on a line with code it is started in the `comment column',
36324459Smckusickwhich is set by the
36450518Scael.Fl c Ns Ns Ar n
36524459Smckusickcommand line parameter.  Otherwise, the comment is started at
36643083Scael.Ar n
36724459Smckusickindentation levels less than where code is currently being placed, where
36843083Scael.Ar n
36919718Smckusickis specified by the
37050518Scael.Fl d Ns Ns Ar n
37124459Smckusickcommand line parameter.  If the code on a line extends past the comment
37224459Smckusickcolumn, the comment starts further to the right, and the right margin may be
37324459Smckusickautomatically extended in extreme cases.
37443083Scael.Pp
37543083Scael.Ss Preprocessor lines
37643083ScaelIn general,
37743083Scael.Nm indent
37843083Scaelleaves preprocessor lines alone.  The only
37936973Sbosticreformatting that it will do is to straighten up trailing comments.  It
38036973Sbosticleaves embedded comments alone.  Conditional compilation
38143083Scael.Pq Ic #ifdef...#endif
38243083Scaelis recognized and
38343083Scael.Nm indent
38443083Scaelattempts to correctly
38536973Sbosticcompensate for the syntactic peculiarities introduced.
38643083Scael.Pp
38743083Scael.Ss C syntax
38843083Scael.Nm Indent
38943083Scaelunderstands a substantial amount about the syntax of C, but it
39024459Smckusickhas a `forgiving' parser.  It attempts to cope with the usual sorts of
39124459Smckusickincomplete and misformed syntax.  In particular, the use of macros like:
39250518Scael.Pp
39343083Scael.Dl #define forever for(;;)
39450518Scael.Pp
39524459Smckusickis handled properly.
39643083Scael.Sh ENVIRONMENT
39743083Scael.Nm Indent
39843083Scaeluses the
39943083Scael.Ev HOME
40043083Scaelenvironment variable.
40143083Scael.Sh FILES
40250518Scael.Bl -tag -width "./.indent.pro" -compact
40350518Scael.It Pa ./.indent.pro
40443083Scaelprofile file
40550518Scael.It Pa ~/.indent.pro
40643083Scaelprofile file
40750518Scael.El
40843083Scael.Sh HISTORY
40950518ScaelThe
41050518Scael.Nm indent
41150518Scaelcommand appeared in
41250518Scael.Bx 4.2 .
41343083Scael.Sh BUGS
41443083Scael.Nm Indent
41543083Scaelhas even more switches than
41643083Scael.Xr ls 1 .
41743083Scael.Pp
41824459Smckusick.ne 5
41924459SmckusickA common mistake that often causes grief is typing:
42050518Scael.Pp
42143083Scael.Dl indent *.c
42250518Scael.Pp
42343083Scaelto the shell in an attempt to indent all the
42443083Scael.Nm C
42543083Scaelprograms in a directory.
42624459SmckusickThis is probably a bug, not a feature.
427