1coan(1)                         User Commmands                         coan(1)
2
3
4

NAME

6       coan - C/C++ configuration analyser
7

SYNOPSIS

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

DESCRIPTION

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

COMMANDS

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

OPTIONS

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

DIAGNOSTICS

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

BUGS

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

AUTHOR

600       Mike Kinghan imk at burroingroingjoing dot com
601
602
603
604AUGUST 2014                 burroingroingjoing.com                     coan(1)
Impressum