Debian Codegraph @

src/opts.def

raw
1
2 /* -*- Mode: conf -*-
3 *
4 * This file is part of Complexity.
5 * Complexity Copyright (c) 2011-2020 by Bruce Korb - all rights reserved
6 *
7 * Complexity is free software: you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the
9 * Free Software Foundation, either version 3 of the License, or
10 * (at your option) any later version.
11 *
12 * Complexity is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
15 * See the GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License along
18 * with this program. If not, see <http://www.gnu.org/licenses/>.
19 */
20
21 AutoGen Definitions options;
22
23 argument = "[ <file-name> ... ]";
24 prog-name = complexity;
25 prog-title = "Measure complexity of C source";
26 package = 'GNU Complexity';
27
28 explain = <<- _EOF_
29 Compute the complexity of source code not just with a
30 path-through-the-code count, but also amplifying line counts
31 by logic level nesting.
32 _EOF_;
33
34 copyright = {
35 date = "2011-2020";
36 owner = "Bruce Korb";
37 eaddr = "[email protected]";
38 type = gpl;
39 };
40
41 version = `
42 ver_file=${top_srcdir:-..}/.tarball-version
43 cat ${ver_file} || exit 1`;
44
45 long-opts;
46 die-code; no-return;
47 gnu-usage;
48 environrc;
49 rcfile = '.complexityrc';
50 homerc = '$@/complex.conf', '$HOME', '$PROJECT_ROOT/complex.conf', '.';
51
52 explain = <<- _EOExplanation_
53 Compute the complexity of code by counting lines of non-comment source
54 and multiplying by a nested logic weight factor. By default, 1.9.
55 _EOExplanation_;
56
57 export = <<- _EOExport_
58 #define DEFAULT_PENALTY 1.9
59 #define DEFAULT_SCALE 19
60
61 typedef double score_t;
62 extern score_t penalty;
63
64 #include "complexity.h"
65 extern FILE * trace_fp;
66 extern int score_ct;
67 extern char const assert_fail_fmt[];
68
69 #define CX_ASSERT(_e) \
70 \ if (!(_e)) \
71 \ die(COMPLEXITY_EXIT_ASSERT, assert_fail_fmt, \
72 \ __FILE__, __LINE__, #_e);
73 _EOExport_;
74
75 include = <<- _EOInclude_
76 score_t penalty = DEFAULT_PENALTY;
77 FILE * trace_fp = NULL;
78 int score_ct = 0;
79 char const assert_fail_fmt[] =
80 \ "COMPLEX ASSERTION FAILURE in %s line %u: %s\n";
81 _EOInclude_;
82
83 main = {
84 main-type = for-each;
85 handler-proc = complex_eval;
86 handler-type = name;
87 main-init = ' initialize(argc, argv);';
88 main-fini = <<- _EOFini_
89 if (score_ct == 0) {
90 printf("No procedures were scored\n");
91 exit(res | COMPLEXITY_EXIT_NO_DATA);
92 }
93 do_summary(res);
94 _EOFini_;
95 };
96
97 flag = {
98 name = threshold;
99 value = t;
100 arg-type = number;
101 arg-default = 30;
102 arg-name = minimum;
103 settable;
104 descrip = "Reporting threshold";
105
106 doc = <<- _EODoc_
107 Ignore any procedures with a complexity measure below this threshold.
108 By default, a complexity score of under 30 is not printed.
109 However, if a histogram and statistics are to be printed, but
110 not individual procedure scores, then the default is set to zero.
111 Procedures below this limit are not counted in the statistics.
112 _EODoc_;
113 };
114
115 flag = {
116 name = horrid-threshold;
117 arg-type = number;
118 arg-default = 100;
119 arg-name = minimum;
120 settable;
121 descrip = "zero exit threshold";
122
123 doc = <<- _EODoc_
124 If any procedures score higher than this threshold, then the
125 program will exit non-zero. (@code{4/COMPLEX_EXIT_HORRID_FUNCTION},
126 if no other problems are encountered.) By default, this program exits
127 zero unless one function exceeds the horrid score of 100.
128 _EODoc_;
129 };
130
131 flag = {
132 name = nesting-penalty;
133 value = n;
134 arg-type = string;
135 arg-name = factor;
136 descrip = "score multiplier for nested code";
137
138 doc = <<- _EODoc_
139 Linguistic constructs weigh more heavily the more deeply nested they
140 are. By default, each layer penalizes by a factor of 1.9. The option
141 argument is a floating point number. The penalty may be 1, but not less.
142 _EODoc_;
143 };
144
145 flag = {
146 name = demi-nesting-penalty;
147 arg-type = string;
148 arg-name = factor;
149 descrip = "score multiplier for nested expressions";
150
151 doc = <<- _EODoc_
152 By default, this value is halfway between 1.0 and the nesting penalty
153 (specifically, the square root of the nesting penalty).
154 It refers to a parenthesized sub-expression. e.g.
155 @example
156 ((a > b) && (c > d))
157 @end example
158 contains two parenthesized sub-expressions. This would count 3.5 points.
159 On the other hand, this:
160 @example
161 (a > b && c > d)
162 @end example
163 contains two relation operators and a logical operator at the same level.
164 These nested counts will be multiplied together and yield
165 @code{2.5 * 2.5}, or @code{6.25}. Don't do that. It gets even worse
166 if you have logical ands and ors at the same level.
167 _EODoc_; //'
168 };
169
170 flag = {
171 name = scale;
172 value = s;
173 arg-type = number;
174 arg-name = factor;
175 descrip = "complexity scaling factor";
176
177 doc = <<- _EODoc_
178 By default, the scaling is 20 which divides the raw score by 20.
179 This was normalized to roughly correspond to the @code{pmccabe} scores:
180
181 @table @samp
182 @item 0-9
183 Easily maintained code.
184 @item 10-19
185 Maintained with little trouble.
186 @item 20-29
187 Maintained with some effort.
188 @item 30-39
189 Difficult to maintain code.
190 @item 40-49
191 Hard to maintain code.
192 @item 50-99
193 Unmaintainable code.
194 @item 100-199
195 Crazy making difficult code.
196 @item 200+
197 I only wish I were kidding.
198 @example
199 Score | ln-ct | nc-lns| file-name(line): proc-name
200 4707 3815 2838 lib/vasnprintf.c(1747): VASNPRINTF
201 @end example
202 @end table
203 _EODoc_;
204 };
205
206 flag = {
207 name = histogram;
208 value = h;
209 descrip = "Display histogram of complexity numbers";
210 no-preset;
211 disable = no;
212
213 doc = <<- _EODoc_
214 Instead of printing out each function's score, a summary is printed
215 at the end showing how many functions had particular ranges of scores.
216 Unless @code{--scores} is specifically called out, the scores will not
217 print with this option specified. The minimum scoring threshold will
218 also be reduced to zero (0), unless @code{--threshold} is specified.
219 _EODoc_; //'
220 };
221
222 flag = {
223 name = scores;
224 value = c;
225 descrip = "Display the score for each procedure";
226 disable = no;
227 no-preset;
228 settable;
229
230 doc = <<- _EODoc_
231 If you specify @code{--histogram}, individual scores will not be
232 displayed, unless this option is specified.
233 _EODoc_;
234 };
235
236 flag = {
237 name = ignore;
238 value = I;
239 descrip = "procedure name to be ignored";
240 arg-type = string;
241 max = NOLIMIT;
242 stack-arg;
243
244 doc = <<- _EODoc_
245 Some code has macros defined that confuse the lexical analysis.
246 This will cause them to be ignored. Other ways to cause functions
247 to be ignored are:
248 @enumerate
249 @item
250 Use K&R syntax for a procedure header.
251 @item
252 Use a preprocessing macro to assemble the procedure header.
253 @item
254 Simplify your code.
255 @end enumerate
256 Generally speaking, anything you do that alters normal C syntax will
257 confuse the lexical analysis. If a procedure is not seen, then it
258 will not get counted. If code within a procedure is incomprehensible,
259 you will likely get inappropriate results.
260 _EODoc_;
261 };
262
263 flag = {
264 name = no-header;
265 value = H;
266 descrip = "do not print scoring header";
267 no-preset;
268
269 doc = <<- _EODoc_
270 If a script is going to process the scoring output, parsing is easier
271 without a header. The histogram output will always have a header.
272 _EODoc_;
273 };
274
275 flag = {
276 name = unifdef;
277 value = u;
278 descrip = "Run the source(s) through unifdef(1BSD)";
279 arg-type = string;
280 arg-name = unifdef-opt;
281 max = NOLIMIT;
282 stack-arg;
283
284 doc = <<- _EODoc_
285 Strip out sections of code surrounded by @code{#if/#endif} directives.
286 The option argument is passed as an argument to the @file{unifdef(1BSD)}
287 program. For example:
288 @example
289 @i{complexity} -u-Dsymbol
290 @end example
291 @noindent
292 would cause @code{symbol} to be defined and remove sections of code
293 preceded by @code{#ifndef symbol} directives.
294
295 Please see the @file{unifdef} documentation for more information.
296 _EODoc_;
297 };
298
299 flag = {
300 name = unif-exe;
301 descrip = "Specify the unifdef program";
302 arg-type = string;
303 arg-name = prog;
304
305 doc = <<- _EODoc_
306 Alternate program to use for unifdef-ing the input.
307 _EODoc_;
308 };
309
310 flag = {
311 name = input;
312 value = i;
313 descrip = "file of file list";
314 arg-type = string;
315 arg-name = file-name;
316 flag-code = <<- _EOCode_
317 FILE * fp = freopen(pOptDesc->optArg.argString, "r", stdin);
318 if (fp != stdin) {
319 fprintf(stderr, "fs error %d (%s) reopening %s as stdin\n",
320 errno, strerror(errno), pOptDesc->optArg.argString);
321 exit(COMPLEXITY_EXIT_BAD_FILE);
322 }
323 _EOCode_;
324
325 doc = <<- _EODoc_
326 Instead of either a command line list of input files or reading
327 them from standard input, read the list of files from this file.
328 _EODoc_;
329 };
330
331 flag = {
332 name = trace;
333 descrip = "trace output file";
334 arg-type = string;
335 arg-name = file-name;
336 flag-code = <<- _EOCode_
337 trace_fp = fopen(pOptDesc->optArg.argString, "w");
338 if (trace_fp == NULL) {
339 fprintf(stderr, "fs error %d (%s) opening %s for tracing\n",
340 errno, strerror(errno), pOptDesc->optArg.argString);
341 exit(COMPLEXITY_EXIT_BAD_FILE);
342 }
343 _EOCode_;
344
345 doc = <<- _EODoc_
346 Print intermediate scores to a trace file.
347 _EODoc_;
348 };
349
350 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
351 * Exit codes. The first few are warnings and "or"-ed into the
352 * final exit code.
353 */
354 exit-name[3] = nomem;
355 exit-desc[3] = 'insufficient memory to run program';
356 nomem-fail-code = nomem;
357
358 exit-name[4] = horrid-function;
359 exit-desc[4] = 'One or more functions scored over 100';
360
361 exit-name[5] = no-data;
362 exit-desc[5] = 'No qualifying procedures were found.';
363
364 exit-name[6] = assert;
365 exit-desc[6] = 'Assertion failed';
366
367 exit-name[32] = bad-file;
368 exit-desc[32] = 'one or more input files were unreadable or empty.';
369 file-fail-code = bad-file;
370
371 exit-status-desc = <<- _EODesc_
372 The "horrid-function" exit code is a warning only.
373 That code is used if the score for any function score exceeds
374 the arbitrary value of 100.
375 _EODesc_;
376
377 option-doc-format = texi;
378
379 detail = <<- _EOF_
380 @code{complexity} ignores all cpp preprocessor directives -
381 calculating the complexity of the appearance of the code,
382 rather than the complexity after the preprocessor manipulates the
383 code. @code{getchar(3)}, for example, will expand into quite
384 complicated code.
385 _EOF_;
386
387 doc-section = {
388 ds-type = DESCRIPTION;
389 ds-format = texi;
390 ds-text = <<- _END_MAN_DESCRIP
391 The weight of each statement is the number of lines the statement
392 uses. This value is multiplied by the nested logic weighting
393 (1.9 by default) for each layer of logic. For example, this snippet:
394
395 @example
396 if (foo) @{
397 if (bar) @{
398 bumble; baz;
399 @}
400 @}
401 @end example
402
403 will score 11. This score is then scaled to approximate @code{pmccabe}
404 results by dividing by 20 and rounding. This scores "1" at the end.
405 @code{pmccabe} scores higher on simple procedures and @code{complexity}
406 scores higher with more deeply nested logic.
407
408 The scoring can be tweaked by adjusting the @code{--nesting-penalty}
409 and @code{--scale}-ing factors. The default values were calibrated
410 by comparing the average results of millions of lines of code with
411 the results of @code{pmccabe}.
412
413 For the purposes of this program, a procedure is identified by a name
414 followed by a parenthesized expression and then an opening curly brace.
415 It ends with a closing curly brace in column 1.
416 _END_MAN_DESCRIP;
417 };
418
419 doc-section = {
420 ds-type = BUGS;
421 ds-format = texi;
422 ds-text = <<- _END_MAN_DESCRIP
423 This program does not recognize K&R procedure headers.
424
425 Some procedures still get missed. Usually, these are procedures
426 that use the C pre-processor to extend the C language in some way.
427
428 Initialized variable definitions within procedures have the initializing
429 elements counted in the complexity calculation.
430 _END_MAN_DESCRIP;
431 };