BCPP(1)

📦 version 0.0.20250914, in ubuntu stonking

💖 BCPP(1) — General Commands Manual 💖

okay bestie, sit down, we're doing the bcpp page and it's a long one, but we're gonna eat. 🍓

✨ NAME ✨

bcpp — make C++ beautifier 💅

(also answers to cb++, she's got range)

🦋 SYNOPSIS 🦋

bcpp [options] [files]
cb++ [files]

🌸 DESCRIPTION 🌸

so basically this program lets you reformat certain elements of a C or C++ source code. it's giving "your friend handed you a file that looks like a raccoon walked across the keyboard" energy 🦝 — maybe one person's code is a little unreadable, or it's been indented in a style you simply cannot with. running this will hopefully help you re-style the code so it closely matches your vibe. HOWEVER — and this is important, no cap — because there are SO many ways to write C(++) out there, there are limits to how well this program will handle the source code and the resulting re-formatted source. it's not magic, it's just very committed. ✨

here's the list of features it actually implements:

  • Reposition comments at certain locations. 💬
  • Remove non-printable characters not contained within quotes.
  • Convert non-printable characters within quotes to octal/character notation.
  • Re-space line spacing between functions.
  • Trim trailing spaces from all lines, as well as leading and trailing blank lines from the file.
  • Reposition opening braces to Kernighan/Ritchie style, or to Pascal style. 🎀
  • Use of tabs, or spaces in indenting.
  • Indention of single line code, according to certain C condition statements, including embedded SQL statements.

🔥 Operation 🔥

so you drive this thing from the command line (CLI), and with a little help from a configuration file you can define exactly what your format requirements are. basically every command directive starts with a dash - followed by the command name. if the command needs another parameter, you just add it after the command separated by a space (i.e., bcpp -fi input.cpp).

N.B: do NOT just run bcpp.exe on its own to find its command help, bestie, use bcpp -? or bcpp -h instead. this is due to the input redirection from the O/S. 🙈

keeping to Unix CLI convention, any string read from the CLI that does not have a command directive is considered an input file. if there are two such occurrences on the command line, the precedence is: input file first, output file second (i.e., bcpp infile.cpp outfile.cpp -lg). a third such occurrence will generate an error message. don't push your luck. 💀

if no output file is presented, the 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. (CLI stays winning, periodt. 👑)

Example:

bcpp -fi input.cpp -f 2 -qb 5 -na -no -cc 60 > output.cpp

🫶 Synopsis 🫶

-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"

a configuration file can be used to specify most of the non-changing elements in the reformatting of code. the config file is made up of some fairly lengthy words that explain the output style of the code. BUT — setting these parameters is actually super easy, they basically come in two types: Boolean or Integer. using your favorite text editor, you can change the following inside the configuration file…

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. 🌈

🎀 Data Types 🎀

  • Integer Type Ranges : 0 - 5000
  • Boolean Type Ranges : On, Yes, or Off, No

💜 Parameters 💜

Function_Spacing : Integer

this one specifies how many lines separate two functions. 📏

e.g.,

function_spacing      = 2

CLI

-f 2

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)

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

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

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

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. and listen — unrecognized (i.e., nonstandard) preprocessor lines are always put into the first column. no exceptions, she's strict. 💅

Indent_Exec_Sql: Boolean

if true, bcpp looks for embedded SQL statements (e.g., EXEC SQL), and formats them specially. 🗄️

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.

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)

NonAscii_Quotes_To_Octal : Boolean

use this option to change non-ASCII (non-printable) chars to octal notation if they lie within quotes. heads up: 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)

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 the NonAscii_Quotes_To_Octal parameter is set to True. 🖼️

E.G.

leave_graphic_chars      = yes

CLI

-lg

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're using the Leave_Graphic_Chars parameter, because 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)

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)

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)

Queue_Buffer : Integer

specifies what the internal memory requirements 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

; : Not Applicable

placing a semicolon in front of text makes everything after the semicolon a comment. 💬

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)

🌟 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)

🦄 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

⭐ 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

💫 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

💖 DIAGNOSTICS 💖

Okay bestie, listen up — if you mess up a command or a parameter inside the configuration file, the second the executable reads it, it's gonna hit you with an error message. And it's not just vague vibes, no — it tells you the line number. So helpful. So iconic. 💅

🔍 Configuration File Processing

Here's the tea on every error message you might bump into while it's reading parameters out of the configuration file:

  • Syntax Error After Key Word : — this pops off when the character/word after a parameter was simply incorrect, or when it was expecting another keyword (think stuff like =, Yes, No, On, Off).
  • Range Error : — this one shows up when integer parameters have an invalid numeric setting, like… a number that is not within 0 - 5000.
  • Expected Numeric Data : — this is what you get when alpha-numeric data is sitting where numeric data should be, for integer type parameters.
  • Cannot Decipher : — the parameter on that line is just not valid, i.e. it's not recognizable. 😭
If any errors have occurred after reading the configuration file, you get a [y/n] continuation prompt. You can either fix the configuration error(s) before processing, or just keep going with the current set parameters. No pressure, bestie, it's literally your call. 🫶

📂 Input File Processing

  • Memory Allocation Failed : — the program couldn't allocate memory to process your data. Heads up: this error will stop processing of data. Dead stop, no cap.
  • Error In Line Construction
  • Expected Some Sort Of Code ! Data Type = ? : — this one gets generated inside the line construction process. Basically the decoded line from the input file might be too indecipherable for this program to handle. So go find that line in your input file and see if you can alter it so processing can keep going. 🌸

💀 BUGS 💀

This section is where we spill on the places in the code where bcpp will fail to reconstruct the output code into the style you wanted — even though it might still compile. Awkward. 🙈

  • All code that's fed through this program should be in a compilable state. That means there should be closing braces that cancel out opening braces. Bcpp does no syntax checking at all upon the code — it just reformats it according to open braces, closing braces, and a handful of key words for single line indentation.
  • There's also a limitation on how far the movement of open braces can be processed. This is due to the current design of the program (though it can be fixed easily by extending the internal queue buffer size), plus memory requirements and processing speed. Dynamic memory allocation is used extensively throughout the program, and it may exceed current limits if certain conditions arise.

So the example shows that moving the brace from the new line up to the code line above it will not take place, because it'd 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;
}
  • There's a constraint that a single line of code should only have one type of comment. If both C and C++ comments exist on the same line, then the line construction phase of the program gets confused and generates an 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, periodt. Remedy this by removing one type of comment, combining them, or placing one of them on a new line. 🎀

👑 AUTHORS 👑

Written By Steven De Toni December 1995 Updated by Thomas Dickey 1997-2024

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)

If all else fails, send snail mail to:

17 Garden Heights Ave,
Melville,
Hamilton,
New Zealand

Thomas Dickey can be reached at

dickey@invisible-island.net

Special thanks goes out to Glyn Webster for proof reading my manual, and testing my program. 🫶

Thanks to Justin Slootsky for his input, and changes for this version. ✨

That's the whole page, bestie — C++ Beautifier, dated 2024-01-11, filed under BCPP(1). Go forth and beautify. 💖🌈

📦 where this page comes from