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