.\" $Id: bcpp.1,v 1.2 2009/06/28 19:51:33 tom Exp $
.TH "C++ Beautifier"
.SH NAME
\fBbcpp\fP \- make C++ beautifier
.SH SYNOPSIS
.B bcpp
[\fI-bcl\fR]
[\fI-bnl\fR]
[\fI-cc\fR <num>]
[\fI-f\fR <num>]
 [\fI-fi\fR <input file name>]
[\fI-fnc\fR <custom config file>]
[\fI-fo\fR <output file name>]
[\fI-h\fR]
[\fI-i\fR <num>]
[\fI-lg\fR]
[\fI-nc\fR]
[\fI-qb\fR]
[\fI-s\fR]
[\fI-t\fR]
[\fI-tbcl\fR]
[\fI-tbnl\fR]
[<other options>]
[<input file name>] [<output file name>]
.SH GENERAL OPTIONS
.TP
\fB\-bcl\fR
Open braces on code line
.TP
\fB\-bnl\fR
Open braces on new line
.TP
\fB\-cc <num>\fR
Column to align comments with code
.TP
\fB\-f <num>\fR
Function line spacing
.TP
\fB\-fi <string>\fR
Input file name
.TP
\fB\-fnc <string>\fR
Load custom configuration file
.TP
\fB\-fo <string>\fR
Output file name
.TP
\fB\-h\fR, \fB\-?\fR
Display help message
.TP
\fB\-i <num>\fR
Indent space length
.TP
\fB\-lg\fR
Leave graphic chars
.TP
\fB\-nc\fR <num>\fR
Column to align comments with no code
.TP
\fB\-qb\fR <num>\fR
Define internal queue buffer size
.TP
\fB\-s\fR
Use spaces in indenting
.TP
\fB\-t\fR
Use tabs in indenting
.TP
\fB\-tbcl\fR
Top-level open braces on code line
.TP
\fB\-tbnl\fR
Top-level open braces on new line
.PP
.SH ENABLE/DISABLE OPTIONS
Options beginning with \-y or \-n enable/disable functions, respectively.
.TP
\fB\-ya\fR or \fB\-na\fR
Open braces on code line
.TP
\fB\-yb\fR or \fB\-nb\fR
Backup input file with .bac extension
.TP
\fB\-ybbi\fR or \fB\-nbbi\fR
Indent both braces of a block
.TP
\fB\-ybi\fR or \fB\-nbi\fR
Indent trailing brace of block
.TP
\fB\-ykcwc\fR or \fB\-nkcwc\fR
Keep comments with Code
.TP
\fB\-ylcnc\fR or \fB\-nlcnc\fR
Leave comments with NoCode
.TP
\fB\-yo\fR or \fB\-no\fR
Program output
.TP
\fB\-yq\fR or \fB\-nq\fR
Change non-ASCII chars in quotes to octal
.SH OVERVIEW
This program enables a user to reformat certain elements of a C,
or C++ source code. This helps if one person's code is a little
unreadable, or has been indented to a style that you dislike.
Using this program will hopefully help in re-styling the code so
that it closely meets your style. However, due to the many styles
of C(++) that can be coded, there are limits to how well this
program will handle the source code, and resulting re-formatted
source.
.PP
The following are a list of features implemented:
.RS 5
.TP 3
-
Reposition comments at certain locations.
.TP
-
Remove non-printable characters not contained within quotes.
.TP
-
Convert non-printable characters within quotes to octal/character notation.
.TP
-
Re-space line spacing between functions.
.TP
-
Trim trailing spaces from all lines, as well as leading
and trailing blank lines from the file.
.TP
-
Reposition opening braces to Kernighan/Ritchie style, or to Pascal style.
.TP
-
Use of tabs, or spaces in indenting.
.TP
-
Indention of single line code, according to certain C
condition statements, including embedded SQL
statements.
.RE
.SH Requirements
This program will run under Microsoft DOS V3.3 and Unix
platforms.
.PP
It uses approximately 50 - 70k (or more, dependant upon internal
queue size) of memory during execution.
.PP
The program code has been written in such a way as to be
compatible with existing C++ compilers, however the code is not
ANSI standard and may require modification for your environment.
The source code has been written with standard ANSI and Posix
functions so that least amount of rewriting should be needed if
recompiling on another computer platform.
.PP
The current sources have been compiled using Turbo C++ V3.0, for
MS-DOS, GNU G++ 2.7.2 under Sun SPARCstation running SunOS,
Solaris as well as SGI workstations running IRIX.
.SH OPERATION
Operation of the program is via the command line (CLI), and with
help from a configuration file you can define your format
requirements. Basically each command directive starts with a dash
"\-" followed my the command name. If another parameter is need
for the command, the parameter is added after the command, and
separated with a space (i.e. bcpp -fi input.cpp).
.PP
N.B: Do not enter bcpp.exe on its own to find its command help,
use bcpp -?, or bcpp -h. This is due to the input redirection
from the O/S. Keeping to Unix CLI convention, a string that is
read from the CLI and does not have a command directive is
considered a input file. If there are two such occurrences on the
command line, the precedence will be input file first, and output
file second (i.e., bcpp infile.cpp outfile.cpp -lg), a third such
occurrence will generate a error message.
.PP
If no output file is presented, its assumed output is via the
standard output. This automatically turns off program output.
Parameters entered on the command line will override parameters
that have been read from the configuration file.
.PP
Example:
.nf
     bcpp -fi input.cpp -f 2 -qb 5 -na -no -cc 60 > output.cpp
.fi
.PP
Synopsis
.PP
        -fi input.cpp   Input file = input.cpp
        -f 2            Function spacing = 2
        -qb 2           Internal Queue Buffer = 5
        -na             Remove non-ascii chars
        -no             Suppress program output
        -cc 60          Comments that appear on same line as
                        code will be placed in column 60.
        > output.cpp    Output of program is redirected to
                        "output.cpp"
.PP
A configuration file can be used to specify most of the non-
changing elements in reformatting of code. The configuration file
consists of some fairly lengthy words that are used to explain
the output style of the code. However setting these parameters is
very easy, they basically consist of two types, Boolean, or
Integer types. Using your favorite text editor, you can change
the following within the configuration file ...
.PP
The following parameters will be contained within the
configuration file (default is bcpp.cfg). The program will
attempt to read the default configuration file at the program
source (i.e. which path bcpp was run). Using the -fnc option you
can define a custom configuration file name, and path from the
CLI.
.PP
Integer Type Ranges : 0 - 5000
Boolean Type Ranges : On, Yes, or Off, No
.RS 5
.TP 5
Function_Spacing : Integer
This parameter specifies how many lines separate two functions.

e.g.,
     function_spacing      = 2

CLI
     -f 2
.TP
Use_Tabs: Boolean
Specifies whether to use tabs in indenting code.

e.g.,
     use_tabs              = no

CLI
     -t   (Turn tabs on, default uses spaces)
     -s   (Use tabs for indenting)
.TP
Indent_Spacing : Integer
Specifies how many spaces to indent. This parameter also sets the
width of tabs. Bcpp considers the width of a tab to be the same
as the width of an indent.

E.G.
     indent_spacing        = 4

CLI
     -i 4
.TP
Comments_With_Code : Integer
Defines the column in which comments that appear after code on a
line will be placed.

e.g.,
     comments_with_code    = 50

CLI
     -cc 50
.TP
Comments_With_Nocode : Integer
Defines the column in which comments that appear in a line will
be placed.

e.g.,
     comments_with_nocode  = 0

CLI
     -nc 0
.TP
Indent_Preprocessor: Boolean
If true, bcpp will indent preprocessor lines to the indention of
the C(++) code. If false, preprocessor lines will be in the first
column. Unrecognized (i.e., nonstandard) preprocessor lines are
always put into the first column.
.TP
Indent_Exec_Sql: Boolean
If true, bcpp looks for embedded SQL statements (e.g., EXEC SQL),
and formats them specially.
.TP
Keep_Comments_With_Code : Boolean
This option overrides the "Comments_With_Code" option.
Setting this option On will make comments which do not fit as inline
comments append to the code anyway.
.TP
Leave_Comments_NoCode : Boolean
This option overrides the "Comments_With_Nocode" option. Setting
this option On will indent comments that do not occur on the same
line as code to the same indention as code.

e.g.,
     leave_comments_nocode = on

CLI
     -nlcnc (Turn off Leave_Comments_NoCode)
     -ylcnc (Turn on Leave_Comments_NoCode)

.TP
NonAscii_Quotes_To_Octal : Boolean
Use this option to change non-ASCII (non-printable) chars to
octal notation if they lie within quotes. This parameter does not
take effect unless either the Ascii_Chars_Only or
Leave_Graphic_Chars parameters have been set.

e.g.,
     NonAscii_Quotes_to_Octal = no

CLI
     -nq  (Turn off non-ascii chars in quotes to octal)
     -yq  (Turn on non-ascii chars in quotes to octal)
.TP
Leave_Graphic_Chars : Boolean
Setting this parameter to yes will strip non-printable characters
from the source file, but leave any characters that are IBM
graphics alone. Any non-printable characters that lie within
quotes will be transformed into octal/character notation, if
NonAscii_Quotes_To_Octal parameter is set to True.

E.G.
     leave_graphic_chars      = yes

CLI
     -lg

.TP
Ascii_Chars_Only : Boolean
Setting this parameter to yes will strip any non-printable,
non-ASCII characters from the input file. Any non-printable
characters that lie within quotes will be transformed into
octal/character notation if NonAscii_Quotes_To_Octal is set to
True. Comment out this parameter if you are using
Leave_Graphic_Chars parameter, as this parameter will override it.

e.g.,
     ascii_chars_only         = yes

CLI
     -na  (Do not remove non-ASCII characters)
     -ya  (Yes remove non-ASCII characters)

.TP
Place_Brace_On_New_Line : Boolean
When set to 'on' bcpp will place opening braces on new lines
("Pascal" style C coding), when set to 'off' bcpp will use "K&R"
style C coding.

Pascal style C coding:
     if (condition)
     {
         statements;
     }

K&R style C coding:
     if (condition) {
         statements;
     }

e.g.,
     place_brace_on_new_line  = on

CLI
     -bnl (on )
     -bcl (off)


.TP
Program_Output : Boolean
This parameter will stop output from the program corrupting
output that may exit from the program via the standard output.
If this parameter is set to off/no then no output is generated
from the program, unless an error is encountered. The standard
error is used to display any errors encountered while processing.

E.G
     program_output          = off

CLI
     -no (default is generate output if possible, this will
          force output off)
     -yo (turn on program output if possible)
.TP
Queue_Buffer : Integer
Specifies what the internal memory requires will be in size of
the line processing buffer. This is used for open brace
relocation in Kernighan/Ritchie style. Extending this buffer to
large amounts of memory will slow processing on small machines.

e.g.,
     Queue_Buffer            = 2

CLI
     -qb 2
.TP
; : Not Applicable
Placing a semicolon in front of text makes everything after the
semicolon a comment.
.TP
Backup_File : Boolean
This option will backup the input file to a file with the
extension ".bac" and overwrite the input file with the
reformatted version.

e.g.,
     backup_file             = yes

CLI
     -yb  (yes, backup input file if possible)
     -nb  (no, do not backup input file)
.RE
.SH Loading Configuration File : CLI only
Bcpp implements a configuration setting to allow custom file
selection from a specific path/file defined by a user.

e.g.,
     bcpp input.cpp -yb (read bcpp.cfg configuration file
                         before processing CLI options)

     bcpp -fnc /bin/bcpp.cfg (load configuration file at
                              said location)

CLI
     -fnc (use user defined)
.TP
Input File Name : CLI only
This option directs bcpp to read data at a given path, and file
name.

E.G
     bcpp -fi input.cpp > output.cpp

CLI
     -fi
.TP
Output File Name : CLI only
This defines the output file name that data is to be written to.

e.g.,
     Has to be like this, (in DOS, at least):

     bcpp  -fo output.cpp < input.cpp

ClI
     -fo
.TP
Online Help : CLI only
Some online help which is brief but to the point exists within
the program. The help lists all of the CLI commands available
within the program.

E.G bcpp -h

CLI bcpp -?
    bcpp -h
.SH Configuration File Error Messages
If you enter a command/parameter incorrectly within the
configuration file, upon the executable program reading it, the
program will generate a error message along with its line number.
The following is an explanation of error messages that may occur
while reading parameters within the configuration file.
.RS 5
.TP 3
Syntax Error After Key Word :
Error occurs because the character/word after a
parameter was incorrect, or expected another keyword
(e.g =, Yes, No, On, Off)
.TP
Range Error :
Error occurs when integer parameters have a invalid
numeric setting (i.e., A number is not within 0 -
5000).
.TP
Expected Numeric Data :
This error occurs when alpha-numeric data is in place
of numeric data for integer type parameters.
.TP
Cannot Decipher :
The parameter at said line is not valid (i.e., not
recognizable).
.RE
.PP
If any errors have occurred after reading the configuration file;
the user is prompted with a [y/n] continuation prompt to either
fix the configuration error(s) before processing, or continue
with current set parameters.
.SH Run Time Errors During Input File Processing
.RS 5
.TP 3
Memory Allocation Failed :
The program was unable to allocate memory to process
data. This error will stop processing of data.
.TP
Error In Line Construction
.TP
Expected Some Sort Of Code ! Data Type = ? :
This error is generated within the line construction
process. The decoded line from the input file may be too
indecipherable for this program. Find the line in the input
file,  and see if it can be altered so that processing can
continue.
.RE
.SH C(++) Beautifier Limitations
This section highlights certain areas within code where bcpp will
fail to reconstruct the output code to the desired style
(although it may still be able to compile).
.RS 5
.TP 3
-
All code that is fed through this program should be in
a compilable state. This means that there should be
closing braces that cancel out opening braces. Bcpp
does no syntax checking at all upon the code, but
reformats it according to open, closing braces, and a
handful of key words for single line indentation.
.TP
-
There is also a limitation on how far the movement of
open braces can be processed. This is due to the
current design of the program (this can fixed easily by
extending the internal queue buffer size), memory
requirements, processing speed. Dynamic memory
allocation is used extensively throughout the program,
and may exceed current limits if certain conditions
arise.

The example shows that the movements of the brace from
the new line to the above code line will not take place
as it would be out of scope for the program if the
internal queue buffer is limited to 2 lines in size.

     Example of brace movement scope:

     if (a == b)
     // Brace will not be re-positioned
     {
          b = c;
     }

     if (a == b)    // Brace will be re-positioned
     {
          b = c;
     }

     End Result

     if (a == b)
     // Brace will not be re-positioned
     {
          b = c;
     }

     if (a == b){   // Brace will be re-positioned
          b = c;
     }
.TP
-
There is a constraint that a single line of code should
only have one type of comment. If there are both C, and
C++ existing on the same line then the line
construction phase of the program will become confused,
and generate a error message. The following line will
produce a Line Construction Error message.

Example of multiple comments.

     /* C Comment */ a = b; // C++ Comment

The above line will generate an error. Remedy this by
removing one type of comment, combine them, or place
one on a new line.
.RE
.SH AUTHORS
Written By Steven De Toni December 1995
.br
Updated by Thomas Dickey January 1997-2002
.PP
You can contact Steven De Toni via various online networks:

          Internet Address
               tge@midland.co.nz
               steve@alpha.ocbbs.gen.nz

          Net Mail Via Fido-Net (Dog Net)
               Steven De Toni,
               "The Great Escape",
               Hamilton,
               New Zealand

          Demi-Monde New Zealand National Mail Net Work
               (see Dog Net)
.PP
If all else fails, send snail mail to:
.PP
          17 Garden Heights Ave,
          Melville,
          Hamilton,
          New Zealand
.PP
Thomas Dickey can be reached at

          dickey@invisible-island.net
.PP
Special thanks goes out to Glyn Webster for proof reading my
manual, and testing my program.
.PP
Thanks to Justin Slootsky for his input, and changes for this
version.
.PP
All \fBgrammatical\fR errors within this document are there for your
enjoyment. ;-)
.SH DISCLAIMER
The authors give no guarantees that this program will function to
the specifications given via the configuration, or the program's
reconstructed output of source code that have been processed. Any
damage that might arise from the use of this program (be it
software, or hardware) is the problem of user, and not the
authors. Using this software binds you to this disclaimer.=