| blob | 0d4d10c6d7388f79000f2a3f52a13bb96bd62d27 |
1 .\" $NetBSD: indent.1,v 1.23 2014/09/04 04:06:07 mrg Exp $
2 .\"
3 .\" Copyright (c) 1980, 1990, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" Copyright (c) 1985 Sun Microsystems, Inc.
31 .\" Copyright (c) 1976 Board of Trustees of the University of Illinois.
32 .\" All rights reserved.
33 .\"
34 .\" Redistribution and use in source and binary forms, with or without
35 .\" modification, are permitted provided that the following conditions
36 .\" are met:
37 .\" 1. Redistributions of source code must retain the above copyright
38 .\" notice, this list of conditions and the following disclaimer.
39 .\" 2. Redistributions in binary form must reproduce the above copyright
40 .\" notice, this list of conditions and the following disclaimer in the
41 .\" documentation and/or other materials provided with the distribution.
42 .\" 3. All advertising materials mentioning features or use of this software
43 .\" must display the following acknowledgement:
44 .\" This product includes software developed by the University of
45 .\" California, Berkeley and its contributors.
46 .\" 4. Neither the name of the University nor the names of its contributors
47 .\" may be used to endorse or promote products derived from this software
48 .\" without specific prior written permission.
49 .\"
50 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
51 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
52 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
53 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
54 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
55 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
56 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
57 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
58 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
59 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
60 .\" SUCH DAMAGE.
61 .\"
62 .\" from: @(#)indent.1 8.1 (Berkeley) 7/1/93
63 .\"
64 .Dd September 2, 2014
65 .Dt INDENT 1
66 .Os
67 .Sh NAME
68 .Nm indent
69 .Nd indent and format C program source
70 .Sh SYNOPSIS
71 .Nm
72 .Op Ar input-file Op Ar output-file
73 .Op Fl bacc | Fl nbacc
74 .Op Fl bad | Fl nbad
75 .Op Fl bap | Fl nbap
76 .Op Fl bbb | Fl nbbb
77 .Op Fl \&bc | Fl nbc
78 .Op Fl \&bl
79 .Op Fl \&br
80 .Op Fl c Ns Ar n
81 .Op Fl \&cd Ns Ar n
82 .Op Fl cdb | Fl ncdb
83 .Op Fl \&ce | Fl nce
84 .Op Fl \&ci Ns Ar n
85 .Op Fl cli Ns Ar n
86 .Op Fl d Ns Ar n
87 .Op Fl \&di Ns Ar n
88 .Op Fl fc1 | Fl nfc1
89 .Op Fl i Ns Ar n
90 .Op Fl \&ip | Fl nip
91 .Op Fl l Ns Ar n
92 .Op Fl \&lc Ns Ar n
93 .Op Fl \&lp | Fl nlp
94 .Op Fl npro
95 .Op Fl pcs | Fl npcs
96 .Op Fl psl | Fl npsl
97 .Op Fl \&sc | Fl nsc
98 .Op Fl sob | Fl nsob
99 .Op Fl \&st
100 .Op Fl troff
101 .Op Fl ut | Fl nut
102 .Op Fl v | Fl \&nv
103 .Sh DESCRIPTION
104 .Nm
105 is a
106 .Tn C
107 program formatter.
108 It reformats the
109 .Tn C
110 program in the
111 .Ar input-file
112 according to the switches.
113 The switches which can be specified are described below.
114 They may appear before or after the file names.
115 .Pp
116 .Sy NOTE :
117 If you only specify an
118 .Ar input-file ,
119 the formatting is
120 done `in-place', that is, the formatted file is written back into
121 .Ar input-file
122 and a backup copy of
123 .Ar input-file
124 is written in the current directory.
125 If
126 .Ar input-file
127 is named
128 .Sq Pa /blah/blah/file ,
129 the backup file is named
130 .Pa file.BAK .
131 .Pp
132 If
133 .Ar output-file
134 is specified,
135 .Nm
136 checks to make sure it is different from
137 .Ar input-file .
138 .Pp
139 If no
140 .Ar input-file
141 is specified
142 input is read from stdin and the formatted file is written to stdout.
143 .Pp
144 The options listed below control the formatting style imposed by
145 .Nm .
146 .Bl -tag -width Op
147 .It Fl bacc , nbacc
148 If
149 .Fl bacc
150 is specified, a blank line is forced around every conditional
151 compilation block.
152 For example, in front of every #ifdef and after every #endif.
153 Other blank lines surrounding such blocks will be swallowed.
154 Default:
155 .Fl nbacc .
156 .It Fl bad , nbad
157 If
158 .Fl bad
159 is specified, a blank line is forced after every block of
160 declarations.
161 Default:
162 .Fl nbad .
163 .It Fl bap , nbap
164 If
165 .Fl bap
166 is specified, a blank line is forced after every procedure body.
167 Default:
168 .Fl nbap .
169 .It Fl bbb , nbbb
170 If
171 .Fl bbb
172 is specified, a blank line is forced before every block comment.
173 Default:
174 .Fl nbbb .
175 .It Fl \&bc , nbc
176 If
177 .Fl \&bc
178 is specified, then a newline is forced after each comma in a declaration.
179 .Fl nbc
180 turns off this option.
181 Default:
182 .Fl \&bc .
183 .It Fl \&br , \&bl
184 Specifying
185 .Fl \&bl
186 lines up compound statements like this:
187 .Bd -literal -offset indent
188 if (...)
189 {
190 code
191 }
192 .Ed
193 .Pp
194 Specifying
195 .Fl \&br
196 (the default) makes them look like this:
197 .Bd -literal -offset indent
198 if (...) {
199 code
200 }
201 .Ed
202 .It Fl bs , Fl nbs
203 If
204 .Fl bs
205 is specified, a blank is forced after
206 .Ic sizeof .
207 Default:
208 .Fl nbs .
209 .It Fl c Ns Ar n
210 The column in which comments on code start.
211 Default:
212 .Fl c33 .
213 .It Fl cd Ns Ar n
214 The column in which comments on declarations start.
215 The default
216 is for these comments to start in the same column as those on code.
217 .It Fl cdb , ncdb
218 Enables (disables) the placement of comment delimiters on blank lines.
219 With this option enabled, comments look like this:
220 .Bd -literal -offset indent
221 /*
222 * this is a comment
223 */
224 .Ed
225 .Pp
226 Rather than like this:
227 .Bd -literal -offset indent
228 /* this is a comment */
229 .Ed
230 .Pp
231 This only affects block comments, not comments to the right of
232 code.
233 Default:
234 .Fl cdb .
235 .It Fl ce , nce
236 Enables (disables) forcing `else's to cuddle up to the immediately preceding
237 `}'.
238 Default:
239 .Fl \&ce .
240 .It Fl \&ci Ns Ar n
241 Sets the continuation indent to be
242 .Ar n .
243 Continuation
244 lines will be indented that far from the beginning of the first line of the
245 statement.
246 Parenthesized expressions have extra indentation added to
247 indicate the nesting, unless
248 .Fl \&lp
249 is in effect.
250 .Fl \&ci
251 defaults to the same value as
252 .Fl i .
253 .It Fl cli Ns Ar n
254 Causes case labels to be indented
255 .Ar n
256 tab stops to the right of the containing
257 .Ic switch
258 statement.
259 .Fl cli0.5
260 causes case labels to be indented half a tab stop.
261 Default:
262 .Fl cli0 .
263 .It Fl d Ns Ar n
264 Controls the placement of comments which are not to the right of code.
265 For example,
266 .Fl \&d\&1
267 means that such comments are placed one indentation level to the left of code.
268 Specifying the default
269 .Fl \&d\&0
270 lines up these comments with the code.
271 See the section on comment
272 indentation below.
273 .It Fl \&di Ns Ar n
274 Specifies the indentation, in character positions, from a declaration keyword
275 to the following identifier.
276 Default:
277 .Fl di16 .
278 .It Fl dj , ndj
279 .Fl \&dj
280 left justifies declarations.
281 .Fl ndj
282 indents declarations the same as code.
283 Default:
284 .Fl ndj .
285 .It Fl \&ei , nei
286 Enables (disables) special
287 .Ic else-if
288 processing.
289 If it's enabled, an
290 .Ic if
291 following an
292 .Ic else
293 will have the same indentation as the preceding
294 .Ic \&if
295 statement.
296 Default:
297 .Fl ei .
298 .It Fl eei , neei
299 Enables (disables) extra indentation on continuation lines of
300 the expression part of
301 .Ic if
302 and
303 .Ic while
304 statements.
305 These continuation lines will be indented one extra level.
306 Default:
307 .Fl neei .
308 .It Fl fc1 , nfc1
309 Enables (disables) the formatting of comments that start in column 1.
310 Often, comments whose leading `/' is in column 1 have been carefully
311 hand formatted by the programmer.
312 In such cases,
313 .Fl nfc1
314 should be used.
315 Default:
316 .Fl fc1 .
317 .It Fl i Ns Ar n
318 The number of spaces for one indentation level.
319 Default:
320 .Fl i8 .
321 .It Fl \&ip , nip
322 Enables (disables) the indentation of parameter declarations from the left
323 margin.
324 Default:
325 .Fl \&ip .
326 .It Fl l Ns Ar n
327 Maximum length of an output line.
328 Default:
329 .Fl l78 .
330 .It Fl \&lp , nlp
331 Lines up code surrounded by parenthesis in continuation lines.
332 If a line has a left parenthesis which is not closed on that line, then
333 continuation lines will be lined up to start at the character
334 position just after the left parenthesis.
335 For example, here is how a piece of continued code looks with
336 .Fl nlp
337 in effect:
338 .Bd -literal -offset indent
339 p1 = first_procedure(second_procedure(p2, p3),
340 \ \ third_procedure(p4,p5));
341 .Ed
342 .Pp
343 With
344 .Fl lp
345 in effect (the default) the code looks somewhat clearer:
346 .Bd -literal -offset indent
347 p1\ =\ first_procedure(second_procedure(p2,\ p3),
348 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,p5));
349 .Ed
350 .Pp
351 Inserting two more newlines we get:
352 .Bd -literal -offset indent
353 p1\ =\ first_procedure(second_procedure(p2,
354 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p3),
355 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4
356 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p5));
357 .Ed
358 .It Fl npro
359 Causes the profile files,
360 .Sq Pa ./.indent.pro
361 and
362 .Sq Pa ~/.indent.pro ,
363 to be ignored.
364 .It Fl pcs , npcs
365 If true
366 .Pq Fl pcs
367 all procedure calls will have a space inserted between
368 the name and the `('.
369 Default:
370 .Fl npcs .
371 .It Fl psl , npsl
372 If true
373 .Pq Fl psl
374 the names of procedures being defined are placed in
375 column 1 \- their types, if any, will be left on the previous lines.
376 Default:
377 .Fl psl .
378 .It Fl \&sc , nsc
379 Enables (disables) the placement of asterisks (`*'s) at the left edge of all
380 comments.
381 Default:
382 .Fl sc .
383 .It Fl sob , nsob
384 If
385 .Fl sob
386 is specified, indent will swallow optional blank lines.
387 You can use this to get rid of blank lines after declarations.
388 Default:
389 .Fl nsob .
390 .It Fl \&st
391 Causes
392 .Nm
393 to take its input from stdin, and put its output to stdout.
394 .It Fl T Ns Ar typename
395 Adds
396 .Ar typename
397 to the list of type keywords.
398 Names accumulate:
399 .Fl T
400 can be specified more than once.
401 You need to specify all the typenames that
402 appear in your program that are defined by
403 .Ic typedef
404 \- nothing will be
405 harmed if you miss a few, but the program won't be formatted as nicely as
406 it should.
407 This sounds like a painful thing to have to do, but it's really
408 a symptom of a problem in C:
409 .Ic typedef
410 causes a syntactic change in the
411 language and
412 .Nm
413 can't find all
414 instances of
415 .Ic typedef .
416 .It Fl troff
417 Causes
418 .Nm
419 to format the program for processing by
420 .Xr troff 1 .
421 It will produce a fancy
422 listing in much the same spirit as
423 .Xr vgrind 1 .
424 If the output file is not specified, the default is standard output,
425 rather than formatting in place.
426 .It Fl ut , nut
427 Enables (disables) the use of tab characters in the output.
428 Tabs are assumed to be aligned on columns divisible by 8.
429 The default is
430 .Fl ut .
431 .It Fl v , \&nv
432 .Fl v
433 turns on `verbose' mode;
434 .Fl \&nv
435 turns it off.
436 When in verbose mode,
437 .Nm
438 reports when it splits one line of input into two or more lines of output,
439 and gives some size statistics at completion.
440 Default:
441 .Fl \&nv .
442 .El
443 .Pp
444 You may set up your own `profile' of defaults to
445 .Nm
446 by creating a file called
447 .Pa .indent.pro
448 in your login directory and/or the current directory and including
449 whatever switches you like.
450 A `.indent.pro' in the current directory takes
451 precedence over the one in your login directory.
452 If
453 .Nm
454 is run and a profile file exists, then it is read to set up the program's
455 defaults.
456 Switches on the command line, though, always override profile switches.
457 The switches should be separated by spaces, tabs or newlines.
458 .Ss Comments
459 .Sq Em Box
460 .Em comments .
461 .Nm
462 assumes that any comment with a dash or star immediately after the start of
463 comment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars.
464 Each line of such a comment is left unchanged, except that its indentation
465 may be adjusted to account for the change in indentation of the first line
466 of the comment.
467 .Pp
468 .Em Straight text .
469 All other comments are treated as straight text.
470 .Nm
471 fits as many words (separated by blanks, tabs, or newlines) on a
472 line as possible.
473 Blank lines break paragraphs.
474 .Ss Comment indentation
475 If a comment is on a line with code it is started in the `comment column',
476 which is set by the
477 .Fl c Ns Ns Ar n
478 command line parameter.
479 Otherwise, the comment is started at
480 .Ar n
481 indentation levels less than where code is currently being placed, where
482 .Ar n
483 is specified by the
484 .Fl d Ns Ns Ar n
485 command line parameter.
486 If the code on a line extends past the comment
487 column, the comment starts further to the right, and the right margin may be
488 automatically extended in extreme cases.
489 .Ss Preprocessor lines
490 In general,
491 .Nm
492 leaves preprocessor lines alone.
493 The only reformatting that it will do is to straighten up trailing comments.
494 It leaves embedded comments alone.
495 Conditional compilation
496 .Pq Ic #ifdef...#endif
497 is recognized and
498 .Nm
499 attempts to correctly
500 compensate for the syntactic peculiarities introduced.
501 .Ss C syntax
502 .Nm
503 understands a substantial amount about the syntax of C, but it
504 has a `forgiving' parser.
505 It attempts to cope with the usual sorts of incomplete and misformed syntax.
506 In particular, the use of macros like:
507 .Pp
508 .Dl #define forever for(;;)
509 .Pp
510 is handled properly.
511 .Sh ENVIRONMENT
512 .Nm
513 uses the
514 .Ev HOME
515 environment variable.
516 .Sh FILES
517 .Bl -tag -width "./.indent.pro" -compact
518 .It Pa ./.indent.pro
519 profile file
520 .It Pa ~/.indent.pro
521 profile file
522 .El
523 .Sh HISTORY
524 The
525 .Nm
526 command appeared in
527 .Bx 4.2 .
528 .Sh BUGS
529 .Nm
530 has even more switches than
531 .Xr ls 1 .
532 .Pp
533 A common mistake that often causes grief is typing:
534 .Pp
535 .Dl indent *.c
536 .Pp
537 to the shell in an attempt to indent all the
538 .Tn C
539 programs in a directory.
540 This is probably a bug, not a feature.