1coan(1) User Commmands coan(1)
2
3
4
6 coan - C/C++ configuration analyser
7
9 coan COMMAND [OPTION...] [file...] [directory...]
10
11 Where no files or directories are specified, input will be read from
12 the standard input. The output of a command is written either to the
13 standard output or to new files, depending upon the command and the
14 options.
15
17 Coan is a tool for investigating configurations of C or C++ source
18 code. A configuration is a (possibly empty) list of assumptions about
19 the status of some preprocessor symbols when the source code is
20 compiled. It may be assumed that a symbol is defined for the
21 preprocessor, possibly with formal parameters and possibly with a
22 specified definition, or it may be assumed that a symbol is undefined.
23
24 It is important to understand that coan shall consider a symbol to be
25 undefined only if there is an assumption to that effect, or if you use
26 the --implicit option. By default, a symbol that is not mentioned in
27 any assumption is considered to be undetermined.
28
29 A configuration may be thought of as list of #define and/or #undef
30 directives that are applied to every file in the source code to observe
31 their effects. The source files might themselves contain #define or
32 #undef directives that are active under the given configuration and
33 which may influence its effects. To capture that influence, Coan
34 temporarily adds each active #define or #undef directive to the
35 configuration just for the duration of the source file in which it is
36 found.
37
38 Given a configuration and some source code, coan can answer a range of
39 questions about how the source code would appear to the C/C++
40 preprocessor if that configuration of preprocessor symbols had been
41 applied in advance.
42
43 The most useful of the questions that coan can answer is: What would
44 the source code look like if re-written with all of the simplifications
45 that follow from the given configuration? Coan can produce the
46 simplified re-write that answers this question. So, if the source code
47 contains redundant preprocessor complexities that depend on the status
48 of some preprocessor symbols, coan can be given a configuration that
49 specifies the status of those symbols, and it will output an new
50 version of the source code from which those redundant complexities have
51 been eliminated. Or, if the source code is obscured by preprocessor
52 logic that differentiates several variants by reference to preprocessor
53 symbols, coan can be given a configuration that specifies any of these
54 variants and will be able to generate a simpler version of the source
55 code that represents only the specifed variant.
56
57 Source code re-written by coan is not pre-processed code as produced by
58 the preprocessor. It still contains comments, macro-invocations, and
59 #-directives. It is still source code, but simplified.
60
61 Other questions that coan can answer include ones about the
62 preprocessor symbols that are invoked in the source code and their
63 properties under a given configuration. For example: What symbol
64 references would appear within active preprocessor directives under a
65 given configuration, and could thus influence the preprocessor under
66 that configuration? What are the macro-expansions of symbol references?
67 How are those macro-expansions derived? What integer values would
68 accrue to the symbol references that can be evaluated under a given
69 configuration?
70
71 Coan can also answer a range of questions about any category of
72 preprocessor directive that might appear in the source code, e.g. What
73 #include directives that import system header files would be active
74 under
75 a given configuration? When coan is invoked to identify the symbol
76 references or directives that satisfy certain criteria, it will output
77 a list of the references or directives of interest, and optionally
78 their locations in the source code.
79
81 help
82 Display a usage summary and exit.
83
84 version
85 Display version information and exit.
86
87 source [OPTION...] [file...] [directory...]
88 Read the input files and rewrite them in accordance with the
89 options.
90
91 spin [OPTION...] [file...] [directory...]
92 Like the source, with all output files organised beneath a
93 specified directory mirroring their original structure.
94
95 symbols [OPTION...] [file...] [directory...]
96 Select references of preprocessor symbols from the input files in
97 accordance with the options and report them on the standard output
98 in accordance with the options.
99
100 includes [OPTION...] [file...] [directory...]
101 Select #include directives from the input files in accordance with
102 the options and report them on the standard output in accordance
103 with the options.
104
105 defs [OPTION...] [file...] [directory...]
106 Select #define and #undef directives from the input files in
107 accordance with the options and report them on the standard output
108 in accordance with the options.
109
110 pragmas [OPTION...] [file...] [directory...]
111 Select #pragma directives from the input files in accordance with
112 the options and report them on the standard output in accordance
113 with the options.
114
115 errors [OPTION...] [file...] [directory...]
116 Select #error directives from the input files in accordance with
117 the options and report them on the standard output in accordance
118 with the options.
119
120 lines [OPTION...] [file...] [directory...]
121 Select #line directives from the input files in accordance with the
122 options and report them on the standard output in accordance with
123 the options.
124
125 directives [OPTION...] [file...] [directory...]
126 Select preprocessor directives from the input files in accordance
127 with the options and report them on the standard output in
128 accordance with the options.
129
131 GENERAL OPTIONS
132 These options may be given with any command.
133
134 -fargfile, --file argfile
135 Read (more) arguments from file argfile. Arguments may be written
136 free-form, separated by whitespace, in argfile. These arguments
137 will be parsed exactly as if they were listed on the commandline at
138 the position of -fargfile.
139
140 -Dsymbol[(param1[,param2...])]=definition, --define
141 symbol[(param1[,param2...])]=definition
142 Assume that the macro definition
143 symbol[(param1[,param2...])]=definition is in force for processing
144 the input file(s). If =definition is unspecified then string
145 defaults to the empty string.
146
147 -Usymbol, --undef symbol
148 Assume that the macro symbol is undefined for processing the input
149 file(s).
150
151 -m, --implicit
152 Assume that any symbol that is not --define-ed is implicitly
153 --undef-ed.
154
155 This option is not allowed to have the perverse effect that an
156 initial invocation, with arguments, of an unconfigured symbol, e.g.
157 sym(a,b), is expanded as 0(a,b) to provoke a syntax error. The
158 invocation is taken to imply that sym has a conforming but unknown
159 definition and is passed through unresolved. However, once sym has
160 been invoked either with arguments or without then subsequent
161 invocations are expected to be of the same form unless sym is
162 redefined or undefined in the meanwhile.
163
164 -R, --recurse
165 Recurse into directories to find input files. (With the source
166 command, --recurse implies --replace). With --recurse, the input
167 files may include directories: otherwise a directory provokes a
168 non-fatal error.
169
170 All files beneath a directory will be selected for input unless the
171 --filter option is given: otherwise all files will be selected that
172 match the --filter option.
173
174 When --recurse is in effect, coan builds a graph of all unique
175 input files once and for all as it parses the filenames that are
176 explicitly supplied and before it processes any of them. New files
177 that may later appear in input directories during execution will
178 not be processed, and files that have disappeared from input
179 directories when they are due to be processed will provoke fatal
180 errors.
181
182 -Fext1[,ext2...], --filter ext1[,ext2...]
183 Process only input files that have one of the file extensions
184 ext1,ext2... A file extension is the terminal segment of a
185 filename that immediately follows the final '.'.
186
187 -g[p|i|w|e|a], --gag [progress | info | warning | error | abend]
188 Suppress diagnostics no worse than [progress | info | warning |
189 error | abend].
190
191 -gs, --gag summary.
192 Suppress summary diagnostics at end of input.
193
194 -V, --verbose
195 Output all diagnostics,
196
197 If neither -V nor -garg is specified defaults are -gp -gi -gs.
198
199 -E, --evalconsts
200 Constants occurring as truth-functional operands in #if expressions
201 shall be evaluated and eliminated. By default constants as truth-
202 functional operands are treated as unknowns, i.e. like macros that
203 are not subject to any assumptions. Constants are always evaluated
204 and eliminated when they are arithmetic or bitwise operands.
205
206 The default behaviour preserves "work-in-progress" directives such
207 as #if 1 and #if 0 along with the code they control. With
208 --evalconsts these directives are evaluated.
209
210 -K, --keepgoing
211 If a parse error is encountered in an input file, continue
212 processing subsequent input files. An event of severity abend will
213 terminate processing regardless of --keepgoing.
214
215 --no-transients
216 By default an in-source #define SYM or #undef SYM directive is
217 transiently treated as a -DSYM or -USYM option within the source
218 file where it is found. This option suppresses the default
219 behaviour at your own risk.
220
221 -P, --pod
222 Apart from #-directives, input is to be treated as Plain Old Data.
223 C or C++ comments and quotations will not be parsed.
224
225 OPTIONS FOR THE source COMMAND
226 -r, --replace
227 Replace each input file with the corresponding output file. This
228 option must be specified to process multiple input files.
229
230 The option changes the default behaviour of the command when no
231 input files are specified. In that case, input is acquired from the
232 standard input. If --replace is not specified, then a single input
233 file is read from the standard input. If --replace is specified
234 then the names of the input files are read from the standard input.
235 Note that the --recurse option implies --replace.
236
237 If you wish to preserve the original files with the --replace
238 option, use the --backup option as well.
239
240 If the names of the input files are read from stdin, the filenames
241 are delimited by whitespace unless enclosed in double-quotes.
242
243 -bsuffix, --backup suffix
244 Backup each input file before replacing it, the backup file having
245 the same name as the input file with suffix appended to it.
246
247 -x[d|c|e], --conflict [delete | comment | error]
248 Select the action to be taken when a #define or #undef directive is
249 encountered in an input file that conflicts with one of the -D or
250 -U assumptions:
251
252 d, delete: Delete the conflicting directive.
253
254 c, comment: Replace the conflicting directive with a diagnostic
255 comment (default).
256
257 e, error: Replace the conflicting directive with a diagnostic
258 #error directive.
259
260 -k[d|b|c], --discard [drop | blank | comment]
261 Select the policy for discarding lines from output:
262
263 d, drop: Drop discarded lines.
264
265 b, blank: Blank discarded lines.
266
267 c, comment: Comment out discarded lines.
268
269 --line
270 Output #line directives in place of discarded lines to preserve the
271 line numbers of retained lines.
272
273 -c, --complement
274 Ouput the lines that ought to be dropped and vice versa.
275
276 OPTIONS FOR THE spin COMMAND
277 The --recurse and --replace options are implied for this command.
278
279 -x[d|c|e], --conflict [delete | comment | error]
280 Select the action to be taken when a #define or #undef directive is
281 encountered in an input file that conflicts with one of the -D or
282 -U assumptions:
283
284 d, delete: Delete the conflicting directive.
285
286 c, comment: Replace the conflicting directive with a diagnostic
287 comment (default).
288
289 e, error: Replace the conflicting directive with a diagnostic
290 #error directive.
291
292 -k[d|b|c], --discard [drop | blank | comment]
293 Select the policy for discarding lines from output:
294
295 d, drop: Drop discarded lines.
296
297 b, blank: Blank discarded lines.
298
299 c, comment: Comment out discarded lines.
300
301 --line
302 Output #line directives in place of discarded lines to preserve the
303 line numbers of retained lines.
304
305 -c, --complement
306 Ouput the lines that ought to be dropped and vice versa.
307
308 --dir dirname
309 Generate a spin under the directory dirname. The output files are
310 generated relative to dirname, mirroring their original structure.
311 dirname and subdirectories will be created as required. Pre-
312 existing output files will be overwritten. A fatal error is given
313 if dirname includes, or is included by or is identical with any
314 input directory.
315
316 -ppathame, --prefix pathname
317 In organising output files beneath the spin directory dir, dir will
318 equated with the path prefix pathname of any input file. This
319 enables any common prefix of all input files to be deleted from all
320 the outout files under dir if desired.
321
322 OPTIONS FOR THE symbols COMMAND
323 -i, --ifs
324 List symbol references that occur in #if, #if[n]def and #elif
325 directives.
326
327 -d, --defs
328 List symbol references that occur in #define directives.
329
330 -u, --undefs
331 List symbol references that occur in #undef directives.
332
333 --includes
334 List symbol references that occur in #include directives.
335
336 --lns
337 List symbol references that occur in #line directives.
338
339 If none of -i, -d, -u, --includes or --lns is given then they are all
340 defaults.
341
342 -o, --once-only
343 List only the first ocurrence of each distinct reference of a
344 symbol.
345
346 --once-per-file
347 List only the first ocurrence per input file of each distinct
348 reference of a symbol.
349
350 If neither --once-only nor --once-per-file is given then all of a
351 symbol's references are listed.
352
353 -A, --active
354 List only references from operative directives.
355
356 -I, --inactive
357 List only references from inoperative directives.
358
359 -L, --locate
360 Report the source file and line number of each listed reference.
361
362 -e, --expand
363 Report the macro expansion of each reported symbol reference, and
364 the integer to which it evaluates, if any. An expansion will be
365 reported for a reference of the symbol symbol if symbol is
366 configured by a -Doption or a -U option, or transiently configured
367 by a #define or #undef directive in the current file.
368
369 In the case -Dsymbol, the expansion of symbol is the empty string
370 (since that is the C preprocessor's default definition for defined
371 symbols).
372
373 In the case -Usymbol, the expansion of symbol is the numeral 0
374 (since 0 is the value assigned by the preprocessor to an undefined
375 symbol).
376
377 In the case -Dsymbol[(param1[,param2...])]=definition, the
378 expansion of the reference is the string that results by, first,
379 substituting the arguments of the references, if any, for the
380 corresponding formal parameters of the symbol in its definition and
381 then recursively replacing each symbol reference in the result with
382 its expansion.
383
384 If a symbol is not configured then its references are reported as
385 insoluble. Likewise if it is configured but a reference has a
386 circular expansion.
387
388 --explain
389 Report the successive steps of macro expansion for each reported
390 symbol reference. Implies --expand
391
392 --select name1[*][,name2[*]...]
393 Select by name the symbols to be reported. A symbol reference will
394 be reported only if its name matches one of the comma-separated
395 names or *-terminated names. A *-terminated name is interpreted as
396 a wildcard name prefix. If not specified then --select * is the
397 default.
398
399 OPTIONS FOR THE includes COMMAND
400 -s, --system
401 List system headers, e.g. <header.h>
402
403 -l, --local
404 List local headers, e.g. "header.h"
405
406 If neither -s or -L is given then both are defaults.
407
408 -o, --once-only
409 List only the first occurrence of each header.
410
411 --once-per-file
412 List only the first occurrence per input file of each header.
413
414 If neither --once-only nor --once-per-file is given then all
415 occurrences of a header are listed.
416
417 -A, --active
418 List only headers from operative directives.
419
420 -I, --inactive
421 List only headers from inoperative directives.
422
423 -L, --locate
424 Report the source file and line number of each listed occurrence
425
426 OPTIONS FOR THE defs COMMAND
427 -o, --once-only
428 List only the first occurrence of each distinct #define or #undef
429 directive.
430
431 --once-per-file
432 List only the first occurrence per input file of each distinct
433 #define or #undef directive.
434
435 For the purpose of determining whether two occurrences express the
436 same directive or not, coan reduces the text of each occurrence to
437 a canonical form, i.e. all comments are stripped out, all
438 whitespace sequences are collapsed to a single space and all tokens
439 are separated by a single space. This applies for all commands that
440 accept the --once-only or --once-per-file option.
441
442 If neither --once-only nor --once-per-file is given then all
443 occurrences of a distinct #define or #undef directive are listed.
444
445 -A, --active
446 List only operative #define and #undef directives.
447
448 -I, --inactive
449 List only inoperative #define and #undef directives.
450
451 -L, --locate
452 Report the source file and line number of each listed occurrence.
453
454 OPTIONS FOR THE pragmas COMMAND
455 -o, --once-only
456 List only the first occurrence of each distinct pragma.
457
458 --once-per-file
459 List only the first occurrence per input file of each distinct
460 pragma.
461
462 If neither --once-only nor --once-per-file is given then all
463 occurrences of a pragma are listed.
464
465 -A, --active
466 List only operative pragmas.
467
468 -I, --inactive
469 List only inoperative pragmas.
470
471 -L, --locate
472 Report the source file and line number of each listed occurrence.
473
474 OPTIONS FOR THE errors COMMAND
475 -o, --once-only
476 List only the first occurrence of each #error directive.
477
478 --once-per-file
479 List only the first occurrence per input file of each #error
480 directive.
481
482 If neither --once-only nor --once-per-file is given then all
483 occurrences of a distinct #error directive are listed.
484
485 -A, --active
486 List only operative #error directives.
487
488 -I, --inactive
489 List only inoperative #error directives.
490
491 -L, --locate
492 Report the source file and line number of each listed occurrence.
493
494 OPTIONS FOR THE directives COMMAND
495 -o, --once-only
496 List only the first occurrence of each distinct directive.
497
498 --once-per-file
499 List only the first occurrence per input file of each distinct
500 directive.
501
502 If neither --once-only nor --once-per-file is given then all
503 occurrences of a distinct directive are listed.
504
505 -A, --active
506 List only operative directives.
507
508 -I, --inactive
509 List only inoperative directives.
510
511 -L, --locate
512 Report the source file and line number of each listed occurrence.
513
515 Diagnostics written to stderr are classified by severity. Each
516 diagnostic includes a distinct hexadecimal code of the form 0xXXXXX
517 that encodes its severity. The 5
518 severities are:
519
520 progress: Progress messages (0xXXXXX & 0x00800 is true)
521
522 info: Noteworthy information (0xXXXXX & 0x01000 is true)
523
524 warning: Indicating problematic input (0xXXXXX & 0x02000 is true)
525
526 error: Indicating invalid input (0xXXXXX & 0x04000 is true)
527
528 abend: Indicating a fatal environment or internal error (0xXXXXX &
529 0x08000 is true)
530
531 If --gag summary is not in force, coan can write summary diagnostics at
532 the end of processing. A summary diagnostic has a hexadecimal code S
533 that encodes one of the severities and in addition S & 0x10000 is true.
534 Even if --gag summary is not in force, a summary will not be written if
535 its severity is suppressed by one of the specified or default --gag
536 options. Since all summaries have severity info or warning, and since
537 the --gag defaults are info, warning and summary, you should specify
538 --gag info to see only warning summaries, and to see all summaries you
539 should specify --verbose. The summaries include:
540
541 info: The number of input files that were reached and the number
542 that were not reached (due to abend).
543
544 info: The number of input files reached that were abandoned (due to
545 errors).
546
547 If there was no abend or error, then additional summaries are written
548 (unless suppressed) indicating each of the following outcomes that has
549 occurred:
550
551 info: Input lines were dropped through simplification.
552
553 info: Input lines were changed through simplification. If the
554 option --discard comment is in effect, causing discarded lines to
555 be commented out, then discarded lines are counted as changed, not
556 dropped.
557
558 warning: Input lines were changed to #error directives.
559
560 warning: #error directives were operative (either in the input
561 source or as a result of simplification).
562
563 Coan returns a system code SC of which the low order half of the low
564 order byte is always meaningful:
565
566 SC & 1: Informational diagnostics accrued.
567
568 SC & 2: Warnings diagnostics accrued.
569
570 SC & 4: Error diagnostics accrued. (Input files provoking errors
571 will be unchanged notwithstanding the --replace option.)
572
573 SC & 8: An abend occurred. Some input files may not have been
574 reached.
575
576 If no error or abend is indicated, then the high order half of the low
577 order byte is also meaningful:
578
579 SC & 16: Input lines were dropped through simplification.
580
581 SC & 32: Input lines were changed through simplification.
582
583 SC & 64: Input lines were changed to #error directives.
584
585 SC & 128: #error directives were operative.
586
587 The system code reflects diagnostics that were provoked even if they
588 were not actually output due to --gag options.
589
591 Trigraphs are not parsed.
592
593 Files that are #include-ed by input files are not parsed, hence any
594 #define or #undef directives they contain will not be factored into the
595 evaluation of the file.
596
597 Please report bugs to bugs dot coan at burroingroingjoing dot com
598
600 Mike Kinghan imk at burroingroingjoing dot com
601
602
603
604AUGUST 2014 burroingroingjoing.com coan(1)