Debian Codegraph @

src/tools/pg_bsd_indent/indent.1

raw
1 .\" Copyright (c) 1980, 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
3 .\" Copyright (c) 1976 Board of Trustees of the University of Illinois.
4 .\" 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 .\" @(#)indent.1 8.1 (Berkeley) 7/1/93
31 .\" $FreeBSD: head/usr.bin/indent/indent.1 309524 2016-12-04 03:10:25Z pfg $
32 .\"
33 .Dd December 2, 2016
34 .Dt INDENT 1
35 .Os
36 .Sh NAME
37 .Nm indent
38 .Nd indent and format C program source
39 .Sh SYNOPSIS
40 .Nm
41 .Op Ar input-file Op Ar output-file
42 .Op Fl bacc | Fl nbacc
43 .Op Fl bad | Fl nbad
44 .Op Fl badp | Fl nbadp
45 .Op Fl bap | Fl nbap
46 .Op Fl bbb | Fl nbbb
47 .Op Fl \&bc | Fl nbc
48 .Op Fl \&bl | Fl \&br
49 .Op Fl bs | Fl nbs
50 .Op Fl c Ns Ar n
51 .Op Fl cp Ns Ar n
52 .Op Fl \&cd Ns Ar n
53 .Bk -words
54 .Op Fl cdb | Fl ncdb
55 .Ek
56 .Op Fl \&ce | Fl nce
57 .Op Fl \&ci Ns Ar n
58 .Op Fl cli Ns Ar n
59 .Op Fl d Ns Ar n
60 .Op Fl \&di Ns Ar n
61 .Op Fl dj | Fl ndj
62 .Bk -words
63 .Op Fl ei | Fl nei
64 .Op Fl eei | Fl neei
65 .Ek
66 .Bk -words
67 .Op Fl fbs | Fl nfbs
68 .Op Fl fc1 | Fl nfc1
69 .Op Fl fcb | Fl nfcb
70 .Ek
71 .Op Fl i Ns Ar n
72 .Op Fl \&ip | Fl nip
73 .Op Fl l Ns Ar n
74 .Op Fl \&lc Ns Ar n
75 .Op Fl \&ldi Ns Ar n
76 .Op Fl \&lp | Fl nlp
77 .Op Fl \&lpl | Fl nlpl
78 .Op Fl npro
79 .Op Fl P Ns Ar file
80 .Op Fl pcs | Fl npcs
81 .Op Fl psl | Fl npsl
82 .Op Fl sac | Fl nsac
83 .Op Fl \&sc | Fl nsc
84 .Bk -words
85 .Op Fl sob | Fl nsob
86 .Ek
87 .Op Fl \&st
88 .Op Fl \&ta
89 .Op Fl T Ns Ar typename
90 .Op Fl tpg | Fl ntpg
91 .Op Fl ts Ns Ar n
92 .Op Fl U Ns Ar file
93 .Op Fl ut | Fl nut
94 .Op Fl v | Fl \&nv
95 .Op Fl -version
96 .Sh DESCRIPTION
97 The
98 .Nm
99 utility is a
100 .Em C
101 program formatter.
102 It reformats the
103 .Em C
104 program in the
105 .Ar input-file
106 according to the switches.
107 The switches which can be
108 specified are described below.
109 They may appear before or after the file
110 names.
111 .Pp
112 .Sy NOTE :
113 If you only specify an
114 .Ar input-file ,
115 the formatting is
116 done `in-place', that is, the formatted file is written back into
117 .Ar input-file
118 and a backup copy of
119 .Ar input-file
120 is written in the current directory.
121 If
122 .Ar input-file
123 is named
124 .Sq Pa /blah/blah/file ,
125 the backup file is named
126 .Sq Pa file.BAK .
127 .Pp
128 If
129 .Ar output-file
130 is specified,
131 .Nm
132 checks to make sure that it is different from
133 .Ar input-file .
134 .Pp
135 The options listed below control the formatting style imposed by
136 .Nm .
137 .Bl -tag -width Op
138 .It Fl bacc , nbacc
139 If
140 .Fl bacc
141 is specified, a blank line is forced around every conditional
142 compilation block.
143 For example, in front of every #ifdef and after every #endif.
144 Other blank lines surrounding such blocks will be swallowed.
145 Default:
146 .Fl nbacc .
147 .It Fl bad , nbad
148 If
149 .Fl bad
150 is specified, a blank line is forced after every block of
151 declarations.
152 Default:
153 .Fl nbad .
154 .It Fl badp , nbadp
155 This is vaguely similar to
156 .Fl bad
157 except that it only applies to the first set of declarations
158 in a procedure (just after the first `{') and it causes a blank
159 line to be generated even if there are no declarations.
160 The default is
161 .Fl nbadp.
162 .It Fl bap , nbap
163 If
164 .Fl bap
165 is specified, a blank line is forced after every procedure body.
166 Default:
167 .Fl nbap .
168 .It Fl bbb , nbbb
169 If
170 .Fl bbb
171 is specified, a blank line is forced before every block comment.
172 Default:
173 .Fl nbbb .
174 .It Fl \&bc , nbc
175 If
176 .Fl \&bc
177 is specified, then a newline is forced after each comma in a declaration.
178 .Fl nbc
179 turns off this option.
180 Default:
181 .Fl \&nbc .
182 .It Fl \&bl , \&br
183 Specifying
184 .Fl \&bl
185 lines up compound statements like this:
186 .Bd -literal -offset indent
187 if (...)
188 {
189 code
190 }
191 .Ed
192 .Pp
193 Specifying
194 .Fl \&br
195 (the default) makes them look like this:
196 .Bd -literal -offset indent
197 if (...) {
198 code
199 }
200 .Ed
201 .It Fl bs , nbs
202 Whether a blank should always be inserted after sizeof.
203 The default is
204 .Fl nbs.
205 .It Fl c Ns Ar n
206 The column in which comments on code start.
207 The default is 33.
208 .It Fl cp Ns Ar n
209 The column in which comments on #else and #endif start.
210 The default is 0, which effectively separates the directives from comments by
211 a single space.
212 .It Fl cd Ns Ar n
213 The column in which comments on declarations start.
214 The default
215 is for these comments to start in the same column as those on code.
216 .It Fl cdb , ncdb
217 Enables (disables) the placement of comment delimiters on blank lines.
218 With
219 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 The default is
234 .Fl cdb .
235 .It Fl ce , nce
236 Enables (disables) forcing of `else's to cuddle up to the immediately preceding
237 `}'.
238 The default is
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 or the continuation indent is exactly half of the main indent.
251 .Fl \&ci
252 defaults to the same value as
253 .Fl i .
254 .It Fl cli Ns Ar n
255 Causes case labels to be indented
256 .Ar n
257 tab stops to the right of the containing
258 .Ic switch
259 statement.
260 .Fl cli0.5
261 causes case labels to be indented half a tab stop.
262 The
263 default is
264 .Fl cli0 .
265 .It Fl d Ns Ar n
266 Controls the placement of comments which are not to the
267 right of code.
268 For example,
269 .Fl \&d\&1
270 means that such comments are placed one indentation level to the
271 left of code.
272 Specifying the default
273 .Fl \&d\&0
274 lines up these comments with the code.
275 See the section on comment
276 indentation below.
277 .It Fl \&di Ns Ar n
278 Specifies the indentation, in character positions,
279 of global variable names and all struct/union member names
280 relative to the beginning of their type declaration.
281 The default is
282 .Fl di16 .
283 .It Fl dj , ndj
284 .Fl \&dj
285 left justifies declarations.
286 .Fl ndj
287 indents declarations the same as code.
288 The default is
289 .Fl ndj .
290 .It Fl \&ei , nei
291 Enables (disables) special
292 .Ic else-if
293 processing.
294 If it is enabled, an
295 .Ic if
296 following an
297 .Ic else
298 will have the same indentation as the preceding
299 .Ic \&if
300 statement.
301 The default is
302 .Fl ei .
303 .It Fl eei , neei
304 Enables (disables) extra indentation on continuation lines of
305 the expression part of
306 .Ic if
307 and
308 .Ic while
309 statements.
310 These continuation lines will be indented one extra level.
311 The default is
312 .Fl neei .
313 .It Fl fbs , nfbs
314 Enables (disables) splitting the function declaration and opening brace
315 across two lines.
316 The default is
317 .Fl fbs .
318 .It Fl fc1 , nfc1
319 Enables (disables) the formatting of comments that start in column 1.
320 Often, comments whose leading `/' is in column 1 have been carefully
321 hand formatted by the programmer.
322 In such cases,
323 .Fl nfc1
324 should be
325 used.
326 The default is
327 .Fl fc1 .
328 .It Fl fcb , nfcb
329 Enables (disables) the formatting of block comments (ones that begin
330 with `/*\\n').
331 Often, block comments have been not so carefully hand formatted by the
332 programmer, but reformatting that would just change the line breaks is not
333 wanted.
334 In such cases,
335 .Fl nfcb
336 should be used.
337 Block comments are then handled like box comments.
338 The default is
339 .Fl fcb .
340 .It Fl i Ns Ar n
341 The number of columns for one indentation level.
342 The default is 8.
343 .It Fl \&ip , nip
344 Enables (disables) the indentation of parameter declarations from the left
345 margin.
346 The default is
347 .Fl \&ip .
348 .It Fl l Ns Ar n
349 Maximum length of an output line.
350 The default is 78.
351 .It Fl lc Ns Ar n
352 Maximum length of an output line in a block comment.
353 The default is 0, which means to limit block comment lines in accordance with
354 .Fl l.
355 .It Fl \&ldi Ns Ar n
356 Specifies the indentation, in character positions,
357 of local variable names
358 relative to the beginning of their type declaration.
359 The default is for local variable names to be indented
360 by the same amount as global ones.
361 .It Fl \&lp , nlp
362 Lines up code surrounded by parentheses in continuation lines.
363 With
364 .Fl \&lp ,
365 if a line
366 has a left paren which is not closed on that line, then continuation lines
367 will be lined up to start at the character position just after the left
368 paren.
369 For example, here is how a piece of continued code looks with
370 .Fl nlp
371 in effect:
372 .Bd -literal -offset indent
373 p1 = first_procedure(second_procedure(p2, p3),
374 \ \ third_procedure(p4, p5));
375 .Ed
376 .Pp
377 With
378 .Fl lp
379 in effect (the default) the code looks somewhat clearer:
380 .Bd -literal -offset indent
381 p1\ =\ first_procedure(second_procedure(p2,\ p3),
382 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,\ p5));
383 .Ed
384 .Pp
385 Inserting two more newlines we get:
386 .Bd -literal -offset indent
387 p1\ =\ first_procedure(second_procedure(p2,
388 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p3),
389 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,
390 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p5));
391 .Ed
392 .It Fl \&lpl , nlpl
393 With
394 .Fl \&lpl ,
395 code surrounded by parentheses in continuation lines is lined up even if it
396 would extend past the right margin.
397 With
398 .Fl \&nlpl
399 (the default), such a line that would extend past the right margin is moved
400 left to keep it within the margin, if that does not require placing it to
401 the left of the prevailing indentation level.
402 These switches have no effect if
403 .Fl nlp
404 is selected.
405 .It Fl npro
406 Causes the profile files,
407 .Sq Pa ./.indent.pro
408 and
409 .Sq Pa ~/.indent.pro ,
410 to be ignored.
411 .It Fl P Ns Ar file
412 Read profile from
413 .Ar file .
414 .It Fl pcs , npcs
415 If true
416 .Pq Fl pcs
417 all procedure calls will have a space inserted between
418 the name and the `('.
419 The default is
420 .Fl npcs .
421 .It Fl psl , npsl
422 If true
423 .Pq Fl psl
424 the names of procedures being defined are placed in
425 column 1 \- their types, if any, will be left on the previous lines.
426 The
427 default is
428 .Fl psl .
429 .It Fl sac , nsac
430 Control whether parenthesized type names in casts are followed by a space or
431 not.
432 The default is
433 .Fl nsac .
434 .It Fl \&sc , nsc
435 Enables (disables) the placement of asterisks (`*'s) at the left edge of all
436 comments.
437 The default is
438 .Fl sc .
439 .It Fl sob , nsob
440 If
441 .Fl sob
442 is specified, indent will swallow optional blank lines.
443 You can use this to
444 get rid of blank lines after declarations.
445 Default:
446 .Fl nsob .
447 .It Fl \&st
448 Causes
449 .Nm
450 to take its input from stdin and put its output to stdout.
451 .It Fl ta
452 Automatically add all identifiers ending in "_t" to the list
453 of type keywords.
454 .It Fl T Ns Ar typename
455 Adds
456 .Ar typename
457 to the list of type keywords.
458 Names accumulate:
459 .Fl T
460 can be specified more than once.
461 You need to specify all the typenames that
462 appear in your program that are defined by
463 .Ic typedef
464 \- nothing will be
465 harmed if you miss a few, but the program will not be formatted as nicely as
466 it should.
467 This sounds like a painful thing to have to do, but it is really
468 a symptom of a problem in C:
469 .Ic typedef
470 causes a syntactic change in the
471 language and
472 .Nm
473 cannot find all
474 instances of
475 .Ic typedef .
476 .It Fl tpg , ntpg
477 If
478 .Fl tpg
479 is specified, follow Postgres rules about when to use spaces versus
480 tabs for indentation, that is, use a space instead of a tab if the
481 tab would move only one column and no tab will follow it.
482 Default:
483 .Fl ntpg .
484 .It Fl ts Ns Ar n
485 Assumed distance between tab stops.
486 The default is 8.
487 .It Fl U Ns Ar file
488 Adds type names from
489 .Ar file
490 to the list of type keywords.
491 .It Fl ut , nut
492 Enables (disables) the use of tab characters in the output.
493 The default is
494 .Fl ut .
495 .It Fl v , \&nv
496 .Fl v
497 turns on `verbose' mode;
498 .Fl \&nv
499 turns it off.
500 When in verbose mode,
501 .Nm
502 reports when it splits one line of input into two or more lines of output,
503 and gives some size statistics at completion.
504 The default is
505 .Fl \&nv .
506 .It Fl -version
507 Causes
508 .Nm
509 to print its version number and exit.
510 .El
511 .Pp
512 You may set up your own `profile' of defaults to
513 .Nm
514 by creating a file called
515 .Pa .indent.pro
516 in your login directory and/or the current directory and including
517 whatever switches you like.
518 A `.indent.pro' in the current directory takes
519 precedence over the one in your login directory.
520 If
521 .Nm
522 is run and a profile file exists, then it is read to set up the program's
523 defaults.
524 Switches on the command line, though, always override profile
525 switches.
526 The switches should be separated by spaces, tabs or newlines.
527 .Pp
528 .Ss Comments
529 .Sq Em Box
530 .Em comments .
531 The
532 .Nm
533 utility
534 assumes that any comment with a dash or star immediately after the start of
535 comment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars.
536 Each line of such a comment is left unchanged, except that its indentation
537 may be adjusted to account for the change in indentation of the first line
538 of the comment.
539 .Pp
540 .Em Straight text .
541 All other comments are treated as straight text.
542 The
543 .Nm
544 utility fits as many words (separated by blanks, tabs, or newlines) on a
545 line as possible.
546 Blank lines break paragraphs.
547 .Ss Comment indentation
548 If a comment is on a line with code it is started in the `comment column',
549 which is set by the
550 .Fl c Ns Ns Ar n
551 command line parameter.
552 Otherwise, the comment is started at
553 .Ar n
554 indentation levels less than where code is currently being placed, where
555 .Ar n
556 is specified by the
557 .Fl d Ns Ns Ar n
558 command line parameter.
559 If the code on a line extends past the comment
560 column, the comment starts further to the right, and the right margin may be
561 automatically extended in extreme cases.
562 .Ss Preprocessor lines
563 In general,
564 .Nm
565 leaves preprocessor lines alone.
566 The only
567 reformatting that it will do is to straighten up trailing comments.
568 It
569 leaves embedded comments alone.
570 Conditional compilation
571 .Pq Ic #ifdef...#endif
572 is recognized and
573 .Nm
574 attempts to correctly
575 compensate for the syntactic peculiarities introduced.
576 .Ss C syntax
577 The
578 .Nm
579 utility understands a substantial amount about the syntax of C, but it
580 has a `forgiving' parser.
581 It attempts to cope with the usual sorts of
582 incomplete and malformed syntax.
583 In particular, the use of macros like:
584 .Pp
585 .Dl #define forever for(;;)
586 .Pp
587 is handled properly.
588 .Sh ENVIRONMENT
589 The
590 .Nm
591 utility uses the
592 .Ev HOME
593 environment variable.
594 .Sh FILES
595 .Bl -tag -width "./.indent.pro" -compact
596 .It Pa ./.indent.pro
597 profile file
598 .It Pa ~/.indent.pro
599 profile file
600 .El
601 .Sh HISTORY
602 The
603 .Nm
604 command appeared in
605 .Bx 4.2 .
606 .Sh BUGS
607 The
608 .Nm
609 utility has even more switches than
610 .Xr ls 1 .
611 .Pp
612 A common mistake is to try to indent all the
613 .Em C
614 programs in a directory by typing:
615 .Pp
616 .Dl indent *.c
617 .Pp
618 This is probably a bug, not a feature.