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