.de1 NOP
.  it 1 an-trap
.  if \\n[.$] \,\\$*\/
..
.ie t \
.ds B-Font [CB]
.ds I-Font [CI]
.ds R-Font [CR]
.el \
.ds B-Font B
.ds I-Font I
.ds R-Font R
.TH complexity 1 "19 Sep 2022" "GNU Complexity (1.13)" "User Commands"
.\"
.\" DO NOT EDIT THIS FILE (in-mem file)
.\"
.\" It has been AutoGen-ed
.\" From the definitions ../src/opts.def
.\" and the template file agman-cmd
.SH NAME
\f\*[B-Font]complexity\fP
\- Measure complexity of C source
.SH SYNOPSIS
\f\*[B-Font]complexity\fP
.\" Mixture of short (flag) options and long options
[\f\*[B-Font]\-flags\f[]]
[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]]
[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]]
[ <file-name> ... ]
.sp \n(Ppu
.ne 2

The operands that this program operates on may be specified either
on the command line or read from standard input, one per line.
In that input, leading and trailing white space is stripped,
blank lines are ignored.
Standard input may not be a terminal.
.sp \n(Ppu
.ne 2

Compute the complexity of source code not just with a
path-through-the-code count, but also amplifying line counts
by logic level nesting.
.sp \n(Ppu
.ne 2

Compute the complexity of code by counting lines of non-comment source
and multiplying by a nested logic weight factor.  By default, 1.9.
.SH DESCRIPTION
The weight of each statement is the number of lines the statement
uses.  This value is multiplied by the nested logic weighting
(1.9 by default) for each layer of logic.  For example, this snippet:
.sp
.br
.in +4
.nf
if (foo) {
  if (bar) {
    bumble; baz;
  }
}
.in -4
.fi
.sp
will score 11.  This score is then scaled to approximate \fBpmccabe\fP
results by dividing by 20 and rounding.  This scores "1" at the end.
\fBpmccabe\fP scores higher on simple procedures and \fBcomplexity\fP
scores higher with more deeply nested logic.
.sp
The scoring can be tweaked by adjusting the \fB\-\-nesting\-penalty\fP
and \fB\-\-scale\fP\-ing factors.  The default values were calibrated
by comparing the average results of millions of lines of code with
the results of \fBpmccabe\fP.
.sp
For the purposes of this program, a procedure is identified by a name
followed by a parenthesized expression and then an opening curly brace.
It ends with a closing curly brace in column 1.
.sp \n(Ppu
.ne 2

This program will perform its function for every file named on the command
line or every file named in a list read from stdin.  The arguments or input
names must be pre\-existing files.  The input list may contain comments,
which are blank lines or lines beginning with a '#' character.
.SH "OPTIONS"
.TP
.NOP \f\*[B-Font]\-t\f[] \f\*[I-Font]minimum\f[], \f\*[B-Font]\-\-threshold\f[]=\f\*[I-Font]minimum\f[]
Reporting threshold.
This option takes an integer number as its argument.
The default
\f\*[I-Font]minimum\f[]
for this option is:
.ti +4
 30
.sp
Ignore any procedures with a complexity measure below this threshold.
By default, a complexity score of under 30 is not printed.
However, if a histogram and statistics are to be printed, but
not individual procedure scores, then the default is set to zero.
Procedures below this limit are not counted in the statistics.
.TP
.NOP \f\*[B-Font]\-\-horrid\-threshold\f[]=\f\*[I-Font]minimum\f[]
zero exit threshold.
This option takes an integer number as its argument.
The default
\f\*[I-Font]minimum\f[]
for this option is:
.ti +4
 100
.sp
If any procedures score higher than this threshold, then the
program will exit non-zero.  (\fB4/COMPLEX_EXIT_HORRID_FUNCTION\fP,
if no other problems are encountered.)  By default, this program exits
zero unless one function exceeds the horrid score of 100.
.TP
.NOP \f\*[B-Font]\-n\f[] \f\*[I-Font]factor\f[], \f\*[B-Font]\-\-nesting\-penalty\f[]=\f\*[I-Font]factor\f[]
score multiplier for nested code.
.sp
Linguistic constructs weigh more heavily the more deeply nested they
are.  By default, each layer penalizes by a factor of 1.9.  The option
argument is a floating point number.  The penalty may be 1, but not less.
.TP
.NOP \f\*[B-Font]\-\-demi\-nesting\-penalty\f[]=\f\*[I-Font]factor\f[]
score multiplier for nested expressions.
.sp
By default, this value is halfway between 1.0 and the nesting penalty
(specifically, the square root of the nesting penalty).
It refers to a parenthesized sub-expression. e.g.
.nf
    ((a > b) && (c > d))
.fi
contains two parenthesized sub-expressions.  This would count 3.5 points.
On the other hand, this:
.nf
    (a > b && c > d)
.fi
contains two relation operators and a logical operator at the same level.
These nested counts will be multiplied together and yield
\fB2.5 * 2.5\fP, or \fB6.25\fP.  Don't do that.  It gets even worse
if you have logical ands and ors at the same level.
.TP
.NOP \f\*[B-Font]\-s\f[] \f\*[I-Font]factor\f[], \f\*[B-Font]\-\-scale\f[]=\f\*[I-Font]factor\f[]
complexity scaling factor.
This option takes an integer number as its argument.
.sp
By default, the scaling is 20 which divides the raw score by 20.
This was normalized to roughly correspond to the \fBpmccabe\fP scores:
.sp
.sp
.IR "0-9"
Easily maintained code.
.sp
.IR "10-19"
Maintained with little trouble.
.sp
.IR "20-29"
Maintained with some effort.
.sp
.IR "30-39"
Difficult to maintain code.
.sp
.IR "40-49"
Hard to maintain code.
.sp
.IR "50-99"
Unmaintainable code.
.sp
.IR "100-199"
Crazy making difficult code.
.sp
.IR "200+"
I only wish I were kidding.
.nf
    Score | ln-ct | nc-lns| file-name(line): proc-name
     4707    3815    2838   lib/vasnprintf.c(1747): VASNPRINTF
.fi
.br
.TP
.NOP \f\*[B-Font]\-h\f[], \f\*[B-Font]\-\-histogram\f[], \f\*[B-Font]\-\-no\-histogram\f[]
Display histogram of complexity numbers.
The \fIno\-histogram\fP form will disable the option.
This option may not be preset with environment variables
or in initialization (rc) files.
.sp
Instead of printing out each function's score, a summary is printed
at the end showing how many functions had particular ranges of scores.
Unless \fB--scores\fP is specifically called out, the scores will not
print with this option specified.  The minimum scoring threshold will
also be reduced to zero (0), unless \fB--threshold\fP is specified.
.TP
.NOP \f\*[B-Font]\-c\f[], \f\*[B-Font]\-\-scores\f[], \f\*[B-Font]\-\-no\-scores\f[]
Display the score for each procedure.
The \fIno\-scores\fP form will disable the option.
This option may not be preset with environment variables
or in initialization (rc) files.
.sp
If you specify \fB--histogram\fP, individual scores will not be
displayed, unless this option is specified.
.TP
.NOP \f\*[B-Font]\-I\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-ignore\f[]=\f\*[I-Font]string\f[]
procedure name to be ignored.
This option may appear an unlimited number of times.
.sp
Some code has macros defined that confuse the lexical analysis.
This will cause them to be ignored.  Other ways to cause functions
to be ignored are:
.sp 1
Use K&R syntax for a procedure header.
.sp 1
Use a preprocessing macro to assemble the procedure header.
.sp 1
Simplify your code.
.br
Generally speaking, anything you do that alters normal C syntax will
confuse the lexical analysis.  If a procedure is not seen, then it
will not get counted.  If code within a procedure is incomprehensible,
you will likely get inappropriate results.
.TP
.NOP \f\*[B-Font]\-H\f[], \f\*[B-Font]\-\-no\-header\f[]
do not print scoring header.
This option may not be preset with environment variables
or in initialization (rc) files.
.sp
If a script is going to process the scoring output, parsing is easier
without a header.  The histogram output will always have a header.
.TP
.NOP \f\*[B-Font]\-u\f[] \f\*[I-Font]unifdef\-opt\f[], \f\*[B-Font]\-\-unifdef\f[]=\f\*[I-Font]unifdef\-opt\f[]
Run the source(s) through unifdef(1BSD).
This option may appear an unlimited number of times.
.sp
Strip out sections of code surrounded by \fB#if/#endif\fP directives.
The option argument is passed as an argument to the \fIunifdef(1BSD)\fP
program.  For example:
.nf
    \fIcomplexity\fP \-u-Dsymbol
.fi
would cause \fBsymbol\fP to be defined and remove sections of code
preceded by \fB#ifndef symbol\fP directives.
.sp
Please see the \fIunifdef\fP documentation for more information.
.TP
.NOP \f\*[B-Font]\-\-unif\-exe\f[]=\f\*[I-Font]prog\f[]
Specify the unifdef program.
.sp
Alternate program to use for unifdef-ing the input.
.TP
.NOP \f\*[B-Font]\-i\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-input\f[]=\f\*[I-Font]file\-name\f[]
file of file list.
.sp
Instead of either a command line list of input files or reading
them from standard input, read the list of files from this file.
.TP
.NOP \f\*[B-Font]\-\-trace\f[]=\f\*[I-Font]file\-name\f[]
trace output file.
.sp
Print intermediate scores to a trace file.
.TP
.NOP \f\*[B-Font]\-\&?\f[], \f\*[B-Font]\-\-help\f[]
Display usage information and exit.
.TP
.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[]
Pass the extended usage information through a pager.
.TP
.NOP \f\*[B-Font]\->\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]]
Save the option state to \fIcfgfile\fP.  The default is the \fIlast\fP
configuration file listed in the \fBOPTION PRESETS\fP section, below.
The command will exit after updating the config file.
.TP
.NOP \f\*[B-Font]\-<\f[] \f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-load-opts\f[]=\f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-no-load-opts\f[]
Load options from \fIcfgfile\fP.
The \fIno-load-opts\fP form will disable the loading
of earlier config/rc/ini files.  \fI\-\-no-load-opts\fP is handled early,
out of order.
.TP
.NOP \f\*[B-Font]\-v\f[] [{\f\*[I-Font]v|c|n\f[] \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}]}]
Output version of program and exit.  The default mode is `v', a simple
version.  The `c' mode will print copyright information and `n' will
print the full copyright notice.
.PP
.SH "OPTION PRESETS"
Any option that is not marked as \fInot presettable\fP may be preset
by loading values from configuration ("RC" or ".INI") file(s) and values from
environment variables named:
.nf
  \fBCOMPLEXITY_<option-name>\fP or \fBCOMPLEXITY\fP
.fi
.ad
The environmental presets take precedence (are processed later than)
the configuration files.
The \fIhomerc\fP files are "\fI$@/complex.conf\fP", "\fI$HOME\fP", "\fI$PROJECT_ROOT/complex.conf\fP", and "\fI.\fP".
If any of these are directories, then the file \fI.complexityrc\fP
is searched for within those directories.
.SH "ENVIRONMENT"
See \fBOPTION PRESETS\fP for configuration environment variables.
.SH "FILES"
See \fBOPTION PRESETS\fP for configuration files.
.SH "EXIT STATUS"
One of the following exit values will be returned:
.TP
.NOP 0 " (EXIT_SUCCESS)"
Successful program execution.
.TP
.NOP 1 " (EXIT_FAILURE)"
The operation failed or the command syntax was not valid.
.TP
.NOP 3 " (EXIT_NOMEM)"
insufficient memory to run program
.TP
.NOP 4 " (EXIT_HORRID_FUNCTION)"
One or more functions scored over 100
.TP
.NOP 5 " (EXIT_NO_DATA)"
No qualifying procedures were found.
.TP
.NOP 6 " (EXIT_ASSERT)"
Assertion failed
.TP
.NOP 32 " (EXIT_BAD_FILE)"
one or more input files were unreadable or empty.
.TP
.NOP 66 " (EX_NOINPUT)"
A specified configuration file could not be loaded.
.TP
.NOP 70 " (EX_SOFTWARE)"
libopts had an internal operational error.  Please report
it to autogen-users@lists.sourceforge.net.  Thank you.
.PP
.SH "AUTHORS"
Bruce Korb
.SH "COPYRIGHT"
Copyright (C) 2011-2020 Bruce Korb all rights reserved.
This program is released under the terms of the GNU General Public License, version 3 or later.
.SH BUGS
This program does not recognize K&R procedure headers.
.sp
Some procedures still get missed.  Usually, these are procedures
that use the C pre\-processor to extend the C language in some way.
.sp
Initialized variable definitions within procedures have the initializing
elements counted in the complexity calculation.
.sp \n(Ppu
.ne 2

Please send bug reports to: bkorb@gnu.org
.SH "NOTES"
This manual page was \fIAutoGen\fP-erated from the \fBcomplexity\fP
option definitions.