@node complexity Invocation
@chapter Invoking complexity
@pindex complexity
@cindex Measure complexity of C source
@ignore
#  -*- buffer-read-only: t -*- vi: set ro:
#
# DO NOT EDIT THIS FILE   (invoke-complexity.texi)
#
# It has been AutoGen-ed
# From the definitions    ../src/opts.def
# and the template file   agtexi-cmd
@end ignore

Compute the complexity of source code not just with a
path-through-the-code count, but also amplifying line counts
by logic level nesting.

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:

@example
if (foo) @{
  if (bar) @{
    bumble; baz;
  @}
@}
@end example

will score 11.  This score is then scaled to approximate @code{pmccabe}
results by dividing by 20 and rounding.  This scores "1" at the end.
@code{pmccabe} scores higher on simple procedures and @code{complexity}
scores higher with more deeply nested logic.

The scoring can be tweaked by adjusting the @code{--nesting-penalty}
and @code{--scale}-ing factors.  The default values were calibrated
by comparing the average results of millions of lines of code with
the results of @code{pmccabe}.

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.


This chapter was generated by @strong{AutoGen},
using the @code{agtexi-cmd} template and the option descriptions for the @code{complexity} program.
This software is released under the GNU General Public License, version 3 or later.

@menu
* complexity usage::                  complexity help/usage (@option{--help})
* complexity threshold::              threshold option (-t)
* complexity horrid-threshold::       horrid-threshold option
* complexity nesting-penalty::        nesting-penalty option (-n)
* complexity demi-nesting-penalty::   demi-nesting-penalty option
* complexity scale::                  scale option (-s)
* complexity histogram::              histogram option (-h)
* complexity scores::                 scores option (-c)
* complexity ignore::                 ignore option (-I)
* complexity no-header::              no-header option (-H)
* complexity unifdef::                unifdef option (-u)
* complexity unif-exe::               unif-exe option
* complexity input::                  input option (-i)
* complexity trace::                  trace option
* complexity config::                 presetting/configuring complexity
* complexity exit status::            exit status
* complexity Bugs::                   Bugs
@end menu

@node complexity usage
@section complexity help/usage (@option{--help})
@cindex complexity help

This is the automatically generated usage text for complexity.

The text printed is the same whether selected with the @code{help} option
(@option{--help}) or the @code{more-help} option (@option{--more-help}).  @code{more-help} will print
the usage text by passing it through a pager program.
@code{more-help} is disabled on platforms without a working
@code{fork(2)} function.  The @code{PAGER} environment variable is
used to select the program, defaulting to @file{more}.  Both will exit
with a status code of 0.

@exampleindent 0
@example
complexity (GNU Complexity) - Measure complexity of C source
Usage:  complexity [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... \
                [ <file-name> ... ]

   -t, --threshold=num        Reporting threshold
       --horrid-threshold=num zero exit threshold
   -n, --nesting-penalty=str  score multiplier for nested code
       --demi-nesting-penalty=str score multiplier for nested expressions
   -s, --scale=num            complexity scaling factor
   -h, --histogram            Display histogram of complexity numbers
                                - disabled as '--no-histogram'
                                - may not be preset
   -c, --scores               Display the score for each procedure
                                - disabled as '--no-scores'
                                - may not be preset
   -I, --ignore=str           procedure name to be ignored
                                - may appear multiple times
   -H, --no-header            do not print scoring header
                                - may not be preset
   -u, --unifdef=str          Run the source(s) through unifdef(1BSD)
                                - may appear multiple times
       --unif-exe=str         Specify the unifdef program
   -i, --input=str            file of file list
       --trace=str            trace output file
   -v, --version[=arg]        output version information and exit
   -?, --help                 display extended usage information and exit
   -!,  --- help           display extended usage information and exit
   ->, --save-opts[=arg]      save the option state to a config file
   -<, --load-opts=str        load options from a config file
                                - disabled as '--no-load-opts'
                                - may appear multiple times

Options are specified by doubled hyphens and their name or by a single
hyphen and the flag character.
Compute the complexity of source code not just with a path-through-the-code
count, but also amplifying line counts by logic level nesting.

If no arguments are provided, input arguments are read from stdin,
one per line; blank and '#'-prefixed lines are comments.
'stdin' may not be a terminal (tty).

The following option preset mechanisms are supported:
 - reading file $@@/complex.conf
 - reading file $HOME/.complexityrc
 - reading file $PROJECT_ROOT/complex.conf
 - reading file ./.complexityrc
 - examining environment variables named COMPLEXITY_*
'complexity' ignores all cpp preprocessor directives - calculating the
complexity of the appearance of the code, rather than the complexity after
the preprocessor manipulates the code.  'getchar(3)', for example, will
expand into quite complicated code.

Please send bug reports to:  <bkorb@@gnu.org>
@end example
@exampleindent 4

@node complexity threshold
@section threshold option (-t)
@cindex complexity-threshold

This is the ``reporting threshold'' option.
This option takes a number argument @file{minimum}.
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.
@node complexity horrid-threshold
@section horrid-threshold option
@cindex complexity-horrid-threshold

This is the ``zero exit threshold'' option.
This option takes a number argument @file{minimum}.
If any procedures score higher than this threshold, then the
program will exit non-zero.  (@code{4/COMPLEX_EXIT_HORRID_FUNCTION},
if no other problems are encountered.)  By default, this program exits
zero unless one function exceeds the horrid score of 100.
@node complexity nesting-penalty
@section nesting-penalty option (-n)
@cindex complexity-nesting-penalty

This is the ``score multiplier for nested code'' option.
This option takes a string argument @file{factor}.
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.
@node complexity demi-nesting-penalty
@section demi-nesting-penalty option
@cindex complexity-demi-nesting-penalty

This is the ``score multiplier for nested expressions'' option.
This option takes a string argument @file{factor}.
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.
@example
((a > b) && (c > d))
@end example
contains two parenthesized sub-expressions.  This would count 3.5 points.
On the other hand, this:
@example
(a > b && c > d)
@end example
contains two relation operators and a logical operator at the same level.
These nested counts will be multiplied together and yield
@code{2.5 * 2.5}, or @code{6.25}.  Don't do that.  It gets even worse
if you have logical ands and ors at the same level.
@node complexity scale
@section scale option (-s)
@cindex complexity-scale

This is the ``complexity scaling factor'' option.
This option takes a number argument @file{factor}.
By default, the scaling is 20 which divides the raw score by 20.
This was normalized to roughly correspond to the @code{pmccabe} scores:

@table @samp
@item 0-9
Easily maintained code.
@item 10-19
Maintained with little trouble.
@item 20-29
Maintained with some effort.
@item 30-39
Difficult to maintain code.
@item 40-49
Hard to maintain code.
@item 50-99
Unmaintainable code.
@item 100-199
Crazy making difficult code.
@item 200+
I only wish I were kidding.
@example
Score | ln-ct | nc-lns| file-name(line): proc-name
 4707    3815    2838   lib/vasnprintf.c(1747): VASNPRINTF
@end example
@end table
@node complexity histogram
@section histogram option (-h)
@cindex complexity-histogram

This is the ``display histogram of complexity numbers'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
can be disabled with --no-histogram.
@item
may not be preset with environment variables or configuration (rc/ini) files.
@end itemize

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 @code{--scores} 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 @code{--threshold} is specified.
@node complexity scores
@section scores option (-c)
@cindex complexity-scores

This is the ``display the score for each procedure'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
can be disabled with --no-scores.
@item
may not be preset with environment variables or configuration (rc/ini) files.
@end itemize

If you specify @code{--histogram}, individual scores will not be
displayed, unless this option is specified.
@node complexity ignore
@section ignore option (-I)
@cindex complexity-ignore

This is the ``procedure name to be ignored'' option.
This option takes a string argument.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@end itemize

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:
@enumerate
@item
Use K&R syntax for a procedure header.
@item
Use a preprocessing macro to assemble the procedure header.
@item
Simplify your code.
@end enumerate
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.
@node complexity no-header
@section no-header option (-H)
@cindex complexity-no-header

This is the ``do not print scoring header'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may not be preset with environment variables or configuration (rc/ini) files.
@end itemize

If a script is going to process the scoring output, parsing is easier
without a header.  The histogram output will always have a header.
@node complexity unifdef
@section unifdef option (-u)
@cindex complexity-unifdef

This is the ``run the source(s) through unifdef(1bsd)'' option.
This option takes a string argument @file{unifdef-opt}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@end itemize

Strip out sections of code surrounded by @code{#if/#endif} directives.
The option argument is passed as an argument to the @file{unifdef(1BSD)}
program.  For example:
@example
@i{complexity} -u-Dsymbol
@end example
@noindent
would cause @code{symbol} to be defined and remove sections of code
preceded by @code{#ifndef symbol} directives.

Please see the @file{unifdef} documentation for more information.
@node complexity unif-exe
@section unif-exe option
@cindex complexity-unif-exe

This is the ``specify the unifdef program'' option.
This option takes a string argument @file{prog}.
Alternate program to use for unifdef-ing the input.
@node complexity input
@section input option (-i)
@cindex complexity-input

This is the ``file of file list'' option.
This option takes a string argument @file{file-name}.
Instead of either a command line list of input files or reading
them from standard input, read the list of files from this file.
@node complexity trace
@section trace option
@cindex complexity-trace

This is the ``trace output file'' option.
This option takes a string argument @file{file-name}.
Print intermediate scores to a trace file.


@node complexity config
@section presetting/configuring complexity

Any option that is not marked as @i{not presettable} may be preset by
loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{COMPLEXITY} and @code{COMPLEXITY_<OPTION_NAME>}.  @code{<OPTION_NAME>} must be one of
the options listed above in upper case and segmented with underscores.
The @code{COMPLEXITY} variable will be tokenized and parsed like
the command line.  The remaining variables are tested for existence and their
values are treated like option arguments.


@noindent
@code{libopts} will search in 4 places for configuration files:
@itemize @bullet
@item
$(pkgdatadir)/complex.conf
@item
$HOME
@item
$PROJECT_ROOT/complex.conf
@item
$PWD
@end itemize
The value for @code{$(pkgdatadir)} is recorded at package configure time
and replaced by @file{libopts} when @file{complexity} runs.
The environment variables @code{HOME}, @code{PROJECT_ROOT}, and @code{PWD}
are expanded and replaced when @file{complexity} runs.
For any of these that are plain files, they are simply processed.
For any that are directories, then a file named @file{.complexityrc} is searched for
within that directory and processed.

Configuration files may be in a wide variety of formats.
The basic format is an option name followed by a value (argument) on the
same line.  Values may be separated from the option name with a colon,
equal sign or simply white space.  Values may be continued across multiple
lines by escaping the newline with a backslash.

Multiple programs may also share the same initialization file.
Common options are collected at the top, followed by program specific
segments.  The segments are separated by lines like:
@example
[COMPLEXITY]
@end example
@noindent
or by
@example
<?program complexity>
@end example
@noindent
Do not mix these styles within one configuration file.

Compound values and carefully constructed string values may also be
specified using XML syntax:
@example
<option-name>
   <sub-opt>...&lt;...&gt;...</sub-opt>
</option-name>
@end example
@noindent
yielding an @code{option-name.sub-opt} string value of
@example
"...<...>..."
@end example
@code{AutoOpts} does not track suboptions.  You simply note that it is a
hierarchicly valued option.  @code{AutoOpts} does provide a means for searching
the associated name/value pair list (see: optionFindValue).

The command line options relating to configuration and/or usage help are:

@subheading version (-v)

Print the program version to standard out, optionally with licensing
information, then exit 0.  The optional argument specifies how much licensing
detail to provide.  The default is to print the license name with the version.  The licensing information may be selected with an option argument.
Only the first letter of the argument is examined:

@table @samp
@item version
Only print the version.
@item copyright
Name the copyright usage licensing terms.  This is the default.
@item verbose
Print the full copyright usage licensing terms.
@end table

@node complexity exit status
@section complexity exit status

One of the following exit values will be returned:
@table @samp
@item 0 (EXIT_SUCCESS)
Successful program execution.
@item 1 (EXIT_FAILURE)
The operation failed or the command syntax was not valid.
@item 3 (EXIT_NOMEM)
insufficient memory to run program
@item 4 (EXIT_HORRID_FUNCTION)
One or more functions scored over 100
@item 5 (EXIT_NO_DATA)
No qualifying procedures were found.
@item 6 (EXIT_ASSERT)
Assertion failed
@item 32 (EXIT_BAD_FILE)
one or more input files were unreadable or empty.
@item 66 (EX_NOINPUT)
A specified configuration file could not be loaded.
@item 70 (EX_SOFTWARE)
libopts had an internal operational error.  Please report
it to autogen-users@@lists.sourceforge.net.  Thank you.
@end table
@node complexity Bugs
@section complexity Bugs
This program does not recognize K&R procedure headers.

Some procedures still get missed.  Usually, these are procedures
that use the C pre-processor to extend the C language in some way.

Initialized variable definitions within procedures have the initializing
elements counted in the complexity calculation.