usr.bin/indent/indent.1

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