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