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