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 .\" 4. 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 .Pp
 171 .It Fl bs , nbs
 172 If
 173 .Fl bs
 174 is specified, then a space is inserted after
 175 .Ic sizeof .
 176 .Fl nbs
 177 turns off this option.
 178 Default:
 179 .Fl nbs .
 180 .It Fl c Ns Ar n
 181 The column in which comments on code start.
 182 The default is 33.
 183 .It Fl cd Ns Ar n
 184 The column in which comments on declarations start.
 185 The default is for these comments to start in the same column as those on code.
 186 .It Fl cdb , ncdb
 187 Enables (disables) the placement of comment delimiters on blank lines.
 188 With this option enabled, comments look like this:
 189 .Bd -literal -offset indent
 190         /*
 191          * this is a comment
 192          */
 193 .Ed
 194 .Pp
 195 Rather than like this:
 196 .Bd -literal -offset indent
 197         /* this is a comment */
 198 .Ed
 199 .Pp
 200 This only affects block comments, not comments to the right of code.
 201 The default is
 202 .Fl cdb .
 203 .It Fl ce , nce
 204 Enables (disables) forcing of `else's to cuddle up to the immediately preceding
 205 `}'.
 206 The default is
 207 .Fl \&ce .
 208 .It Fl \&ci Ns Ar n
 209 Sets the continuation indent to be
 210 .Ar n .
 211 Continuation
 212 lines will be indented that far from the beginning of the first line of the
 213 statement.
 214 Parenthesized expressions have extra indentation added to
 215 indicate the nesting, unless
 216 .Fl \&lp
 217 is in effect 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 default is
 230 .Fl cli0 .
 231 .It Fl d Ns Ar n
 232 Controls the placement of comments which are not to the right of code.
 233 For example,
 234 .Fl \&d\&1
 235 means that such comments are placed one indentation level to the left of code.
 236 Specifying the default
 237 .Fl \&d\&0
 238 lines-up these comments with the code.
 239 See the section on comment indentation below.
 240 .It Fl \&di Ns Ar n
 241 Specifies the indentation, in character positions,
 242 of global variable names and all struct/union member names
 243 relative to the beginning of their type declaration.
 244 The default is
 245 .Fl di16 .
 246 .It Fl dj , ndj
 247 .Fl \&dj
 248 left justifies declarations.
 249 .Fl ndj
 250 indents declarations the same as code.
 251 The default is
 252 .Fl ndj .
 253 .It Fl \&ei , nei
 254 Enables (disables) special
 255 .Ic else-if
 256 processing.
 257 If it is enabled, an
 258 .Ic if
 259 following an
 260 .Ic else
 261 will have the same indentation as the preceding
 262 .Ic \&if
 263 statement.
 264 The default is
 265 .Fl ei .
 266 .It Fl fbs , nfbs
 267 Enables (disables) splitting the function declaration and opening brace
 268 across two lines.
 269 The default is
 270 .Fl fbs .
 271 .It Fl fc1 , nfc1
 272 Enables (disables) the formatting of comments that start in column 1.
 273 Often, comments whose leading `/' is in column 1 have been carefully
 274 hand formatted by the programmer.
 275 In such cases,
 276 .Fl nfc1
 277 should be used.
 278 The default is
 279 .Fl fc1 .
 280 .It Fl fcb , nfcb
 281 Enables (disables) the formatting of block comments (ones that begin
 282 with `/*\\n').
 283 Often, block comments have been not so carefully hand formatted by the
 284 programmer, but reformatting that would just change the line breaks is not
 285 wanted.
 286 In such cases,
 287 .Fl nfcb
 288 should be used.
 289 Block comments are then handled like box comments.
 290 The default is
 291 .Fl fcb .
 292 .It Fl i Ns Ar n
 293 The number of spaces for one indentation level.
 294 The default is 8.
 295 .It Fl \&ip , nip
 296 Enables (disables) the indentation of parameter declarations from the left
 297 margin.
 298 The default is
 299 .Fl \&ip .
 300 .It Fl l Ns Ar n
 301 Maximum length of an output line.
 302 The default is 78.
 303 .It Fl \&ldi Ns Ar n
 304 Specifies the indentation, in character positions,
 305 of local variable names
 306 relative to the beginning of their type declaration.
 307 The default is for local variable names to be indented
 308 by the same amount as global ones.
 309 .It Fl \&lp , nlp
 310 Lines-up code surrounded by parenthesis in continuation lines.
 311 If a line
 312 has a left paren which is not closed on that line, then continuation lines
 313 will be lined up to start at the character position just after the left
 314 paren.
 315 For example, here is how a piece of continued code looks with
 316 .Fl nlp
 317 in effect:
 318 .Bd -literal -offset indent
 319 p1 = first_procedure(second_procedure(p2, p3),
 320 \ \ third_procedure(p4, p5));
 321 .Ed
 322 .Pp
 323 With
 324 .Fl lp
 325 in effect (the default) the code looks somewhat clearer:
 326 .Bd -literal -offset indent
 327 p1\ =\ first_procedure(second_procedure(p2,\ p3),
 328 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,\ p5));
 329 .Ed
 330 .Pp
 331 Inserting two more newlines we get:
 332 .Bd -literal -offset indent
 333 p1\ =\ first_procedure(second_procedure(p2,
 334 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p3),
 335 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,
 336 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p5));
 337 .Ed
 338 .It Fl npro
 339 Causes the profile files,
 340 .Sq Pa ./.indent.pro
 341 and
 342 .Sq Pa ~/.indent.pro ,
 343 to be ignored.
 344 .It Fl pcs , npcs
 345 If true
 346 .Pq Fl pcs
 347 all procedure calls will have a space inserted between the name and the `('.
 348 The default is
 349 .Fl npcs .
 350 .It Fl psl , npsl
 351 If true
 352 .Pq Fl psl
 353 the names of procedures being defined are placed in
 354 column 1 \- their types, if any, will be left on the previous lines.
 355 The default is
 356 .Fl psl .
 357 .It Fl \&sc , nsc
 358 Enables (disables) the placement of asterisks (`*'s) at the left edge of all
 359 comments.
 360 The default is
 361 .Fl sc .
 362 .It Fl sob , nsob
 363 If
 364 .Fl sob
 365 is specified, indent will swallow optional blank lines.
 366 You can use this to get rid of blank lines after declarations.
 367 Default:
 368 .Fl nsob .
 369 .It Fl \&st
 370 Causes
 371 .Nm
 372 to take its input from stdin and put its output to stdout.
 373 .It Fl ta
 374 Automatically add all identifiers ending in "_t" to the list
 375 of type keywords.
 376 .It Fl T Ns Ar typename
 377 Adds
 378 .Ar typename
 379 to the list of type keywords.
 380 Names accumulate:
 381 .Fl T
 382 can be specified more than once.
 383 You need to specify all the typenames that
 384 appear in your program that are defined by
 385 .Ic typedef
 386 \- nothing will be
 387 harmed if you miss a few, but the program will not be formatted as nicely as
 388 it should.
 389 This sounds like a painful thing to have to do, but it is really
 390 a symptom of a problem in C:
 391 .Ic typedef
 392 causes a syntactic change in the
 393 language and
 394 .Nm
 395 cannot find all
 396 instances of
 397 .Ic typedef .
 398 .It Fl troff
 399 Causes
 400 .Nm
 401 to format the program for processing by
 402 .Xr troff 1 .
 403 It will produce a fancy
 404 listing in much the same spirit as
 405 .Xr vgrind 1 .
 406 If the output file is not specified, the default is standard output,
 407 rather than formatting in place.
 408 .It Fl ut , nut
 409 Enables (disables) the use of tab characters in the output.
 410 Tabs are assumed to be aligned on columns divisible by 8.
 411 The default is
 412 .Fl ut .
 413 .It Fl v , \&nv
 414 .Fl v
 415 turns on `verbose' mode;
 416 .Fl \&nv
 417 turns it off.
 418 When in verbose mode,
 419 .Nm
 420 reports when it splits one line of input into two or more lines of output,
 421 and gives some size statistics at completion.
 422 The default is
 423 .Fl \&nv .
 424 .El
 425 .Pp
 426 You may set up your own `profile' of defaults to
 427 .Nm
 428 by creating a file called
 429 .Pa .indent.pro
 430 in your login directory and/or the current directory and including
 431 whatever switches you like.
 432 A `.indent.pro' in the current directory takes
 433 precedence over the one in your login directory.
 434 If
 435 .Nm
 436 is run and a profile file exists, then it is read to set up the program's
 437 defaults.
 438 Switches on the command line, though, always override profile switches.
 439 The switches should be separated by spaces, tabs or newlines.
 440 .Ss Comments
 441 .Sq Em Box
 442 .Em comments .
 443 The
 444 .Nm
 445 utility
 446 assumes that any comment with a dash or star immediately after the start of
 447 comment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars.
 448 Each line of such a comment is left unchanged, except that its indentation
 449 may be adjusted to account for the change in indentation of the first line
 450 of the comment.
 451 .Pp
 452 .Em Straight text .
 453 All other comments are treated as straight text.
 454 The
 455 .Nm
 456 utility fits as many words (separated by blanks, tabs, or newlines) on a
 457 line as possible.
 458 Blank lines break paragraphs.
 459 .Ss Comment indentation
 460 If a comment is on a line with code it is started in the `comment column',
 461 which is set by the
 462 .Fl c Ns Ns Ar n
 463 command line parameter.
 464 Otherwise, the comment is started at
 465 .Ar n
 466 indentation levels less than where code is currently being placed, where
 467 .Ar n
 468 is specified by the
 469 .Fl d Ns Ns Ar n
 470 command line parameter.
 471 If the code on a line extends past the comment
 472 column, the comment starts further to the right, and the right margin may be
 473 automatically extended in extreme cases.
 474 .Ss Preprocessor lines
 475 In general,
 476 .Nm
 477 leaves preprocessor lines alone.
 478 The only reformatting that it will do is to straighten up trailing comments.
 479 It leaves embedded comments alone.
 480 Conditional compilation
 481 .Pq Ic #ifdef...#endif
 482 is recognized and
 483 .Nm
 484 attempts to correctly
 485 compensate for the syntactic peculiarities introduced.
 486 .Ss C syntax
 487 The
 488 .Nm
 489 utility understands a substantial amount about the syntax of C, but it
 490 has a `forgiving' parser.
 491 It attempts to cope with the usual sorts of incomplete and misformed syntax.
 492 In particular, the use of macros like:
 493 .Pp
 494 .Dl #define forever for(;;)
 495 .Pp
 496 is handled properly.
 497 .Sh ENVIRONMENT
 498 The
 499 .Nm
 500 utility uses the
 501 .Ev HOME
 502 environment variable.
 503 .Sh FILES
 504 .Bl -tag -width ".Pa /usr/share/misc/indent.pro" -compact
 505 .It Pa ./.indent.pro
 506 profile file
 507 .It Pa ~/.indent.pro
 508 profile file
 509 .It Pa /usr/share/misc/indent.pro
 510 example profile file
 511 .El
 512 .Sh HISTORY
 513 The
 514 .Nm
 515 command appeared in
 516 .Bx 4.2 .
 517 .Sh BUGS
 518 The
 519 .Nm
 520 utility has even more switches than
 521 .Xr ls 1 .
 522 .Pp
 523 A common mistake is to try to indent all the
 524 .Em C
 525 programs in a directory by typing:
 526 .Pp
 527 .Dl indent *.c
 528 .Pp
 529 This is probably a bug, not a feature.