pmccabe(1)

🦋 NAME 🦋

okay so bestie, meet pmccabe(1) — she calculates McCabe cyclomatic complexity, or counts non-commented lines, for your C and C++ programs. yes that's the whole vibe. 💖

---

✨ SYNOPSIS ✨

pmccabe [-bCdfFntTvVxX?] [file(s)]

---

🌸 DESCRIPTION 🌸

So pmccabe processes the files you name, or reads standard input if you name none. In default mode it crunches statistics including McCabe cyclomatic complexity for each function. The files are expected to be either C (ANSI or K&R) or C++. that's it, that's the assignment. 💅

• -? — prints an informative usage message. she's helpful like that.
• -v — prints column headers.
• -V — prints the pmccabe version number.

💀 De-commenting mode 💀

• -d — meant to help you count non-commented source lines via something like:

pmccabe -d *.c | grep -v '^[<blank><tab>]*$' | wc -l

Comments get removed, cpp directives get replaced by cpp, string literals get replaced by STRINGLITERAL, character constants get replaced by CHARLITERAL. The resulting source code is so much easier to parse. ngl this is literally the first step pmccabe does, so that its parser can stay simpler. iconic behavior tbh.

Only -X and -x work sensibly with -d. fr fr, don't fight it.

• -X — tells pmccabe to use a better approximation of the C preprocessor (courtesy of Matt Hargett) than the original one. WARNING! if you have archived results using the old algorithm, they may break because -X is now the default. 😭 she changed and you just have to accept it.
• -x — pmccabe uses the original rudimentary approximation of the C preprocessor (described below). WARNING! This is no longer the default algorithm as of version 2.8 and may be removed after version 2.8. so… cherish her while she's here. 🥺

🎀 Line-counting mode 🎀

• -n — counts non-commented source lines. The output format is identical to that of the anac program except that column headers and totals must be requested if desired. If you want column headers add -v. If you want totals add -t. If all you want is totals add -T. choose your own adventure bestie.

👑 Complexity mode (default) 👑

• -C — Custom output format — don't use it. that's it. that's the description. 💀
• -c — reports non-commented, non-blank lines per function (and file) instead of the raw number of lines. Note that pre-processor directives are NOT counted.
• -b — output format compatible with compiler error browsing tools which understand "classic" compiler errors. Numerical sorting on this format is possible using:

sort -n +1 -t%

• -t — prints column totals. Note the total number of lines is *NOT* the number of non-commented source lines — it's the same as would be reported by wc -l. do not be fooled. 🫶
• -T — prints column totals *ONLY*.
• -f — includes per-file totals along with the per-function totals.
• -F — prints per-file totals but NOT per-function totals.

🧚 Parsing 🧚

pmccabe ignores all cpp preprocessor directives — she's calculating the complexity of the appearance of the code rather than the complexity after the preprocessor mangles the code. This is especially important since simple things like getchar(3) expand into macros which increase complexity. the way that a tiny little function call becomes a whole complexity situation… 😭

🌈 Output Format 🌈

A line is written to standard output for each function found, of the form:

Modified McCabe Cyclomatic Complexity
|   Traditional McCabe Cyclomatic Complexity
|       |    # Statements in function
|       |        |   First line of function
|       |        |       |   # lines in function
|       |        |       |       |  filename(definition line number):function
|       |        |       |       |           |
5       6       11      34      27      gettoken.c(35): matchparen

Column 1 contains cyclomatic complexity calculated by adding 1 (for the function) to the occurrences of for, if, while, switch, &&, ||, and ?. Unlike "normal" McCabe cyclomatic complexity, each case in a switch statement is not counted as additional complexity. This treatment of switch statements and complexity may be more useful than the "normal" measure for judging maintenance effort and code difficulty.

Column 2 is the cyclomatic complexity calculated in the "usual" way with regard to switch statements. Specifically it is calculated as in column 1 but counting each case rather than the switch, and may be more useful than column 1 for judging testing effort.

Column 3 contains a statement count. It is calculated by adding each occurrence of for, if, while, switch, ?, and semicolon within the function. One possible surprise is that for statements have a minimum statement count of 3. This is realistic since for(A; B; C){...} is really shorthand for A; while (B) { ... C;}. The number of statements within a file is the sum of the number of statements for each function implemented within that file, plus one for each of those functions (because functions are statements too), plus one for each other file-scoped statement (usually declarations). math is mathing. ✨

Column 4 contains the first line number in the function. This is not necessarily the same line on which the function name appears. sneaky.

Column 5 is the number of lines of the function, from the number in column 4 through the line containing the closing curly brace.

The final column contains the file name, line number on which the function name occurs, and the name of the function.

---

🚀 APPLICATIONS 🚀

The obvious application of pmccabe is illustrated by the following, which gives a list of the "top ten" most complex functions:

pmccabe *.c | sort -nr | head -10

Many files contain more than one C function, and sometimes it would be useful to extract each function separately. matchparen() (see example output above) can be extracted from gettoken.c by extracting 27 lines starting with line 34. This can form the basis of tools which operate on functions instead of files (e.g., use as a front-end for diff(1)). lowkey a whole ecosystem. 🔥

---

🩺 DIAGNOSTICS 🩺

pmccabe returns a nonzero exit status if files could not be opened and upon encountering some parsing errors.

Error messages go to standard error, usually explaining that the parser is confused about something, and they mimic classic C compiler error messages. she's confused and she's telling you in the most vintage way possible. 🙈

---

⚠️ WARNINGS ⚠️

pmccabe is confused by unmatched curly braces or parentheses, which sometimes occur with hasty use of cpp directives. In these cases a diagnostic is printed and the complexity results for the files named may be unreliable. Most times the "#ifdef" directives may be modified such that the curly braces match. Note that if pmccabe is confused by a cpp directive, most pretty printers will be too. In some cases, preprocessing with unifdef(1) may be appropriate.

Statement counting could arguably be improved by: counting occurrences of the comma operator, multiple assignments, assignments within conditional tests, and logical conjunction. However since there is no crisp statement definition from the language or from people I've queried, statement counting will probably not be improved. If you have a crisp definition I'll be happy to consider it. bestie the author is literally asking for your notes. 📝

Templates cause pmccabe's scanner to exit. 💀

It's a shame that ctags output isn't provided. we mourn. 😭

---

💜 AUTHOR 💜

Paul Bame

---

👀 SEE ALSO 👀

codechanges(1), decomment(1), vifn(1), sort(1), diff(1), wc(1), grep(1), unifdef(1), head(1), anac(1)

https://gitlab.com/pmccabe/pmccabe

---

okay that's the whole page bestie 🫶 this was pmccabe(1), dated 17Jan2021, and you can find the real one living her best life as pmccabe(1) in the General Commands Manual. go forth and measure some complexity, no cap. 💅✨