NAME

cscan - C source scan (C::Scan alternative)

VERSION

version 0.47

AUTHOR

Jean-Damien Durand <jeandamiendurand@free.fr>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

NAME

cscan - C source scsan

SYNOPSIS

 cscan [options] [file]

 Startup Options:
   --help                Brief help message.
   --cpprun <argument>   Preprocessor run command.
   --cppflags <argument> Preprocessor flags.
   --filter <argument>   File to look at after preprocessing.
   --get <argument,...>  Dump the result of getting <argument>.
   --xml                 Print out an XML view of all declarations and definitions.
   --out <argument>      Redirect any output to this filename.
   --err <argument>      Redirect any error to this filename.
   --in <argument>       Load a full XML view of all declarations and definitions from this filename.
   --xpath <argument>    Dump the result of an xpath query on declarations and definitions.
   --loglevel <level>    A level that has to be meaningful for Log::Log4perl, typically DEBUG, INFO, WARN, ERROR, FATAL or TRACE.
   --logstderr           Logs to stderr or not.
   --enumType            Type for enumerators.

 Aliased options:
   --debug              Alias to --loglevel DEBUG
   --info               Alias to --loglevel INFO
   --warn               Alias to --loglevel WARN
   --error              Alias to --loglevel ERROR
   --fatal              Alias to --loglevel FATAL
   --trace              Alias to --loglevel TRACE

 Advanced options:
   --lazy               Instruct the parser to try all alternatives on typedef/enum/identifier
   --typedef <typedef>  Comma separated list of known typedefs
   --enum <enums>       Comma separated list of known enums

OPTIONS

--help

This help

--cpprun <argument>

cpp run command. Default is the value when perl was compiled, i.e.:

$CPPRUN (if you read this message, do not worry: this is replaced by correct value at run-time)

This option can be repeated.

--cppflags <argument>

cpp flags. Default is the value when perl was compiled, i.e.:

$CPPFLAGS (if you read this message, do not worry: this is replaced by correct value at run-time)

--filter <argument>

File to look at after proprocessing. Defaults to basename of file argument.

cscan is using the preprocessor. Every #include statement in your original source code is telling the preprocessor to look at another file, this is marked down by a line like:

 #line ... "information on the file processed"

in the generated output. The --filter argument is used to select which processed files is/are of interest. If $filter is starting with a slash "/" it is assumed to be a full regular expression (including modifier flags). The regexp can be used to handle the case of multiple input files.

In case the file you parse already contains preprocessing information, for example a generated C source code from a source file xxx.w, then you migh want to say: --filter xxx.w, or --filter '/xxx\\.w$/'

--get <argument,...>

Dump the result of getting <argument> using perl module Data::Dumper, except for the astToString. A comma "," is the separator for multiple arguments.

<argument> is exactly one of the C::Scan like methods when such one exist, i.e.:

ast: The AST (Abstract Syntax Tree) in stringified XML format.
decls: All declarations.
defines_args: Macros with arguments.
defines_no_args: Macros without arguments.
fdecls: Declarations of functions.
includes: Included files.
inlines: Definitions of functions.
macros: List of macros
parsed_fdecls: List of parsed functions declarations.
strings: List of strings.
typedef_hash: List of hash which contains known typedefs as keys.
typedef_structs: Hash which known typedefs as keys.
typedef_texts: List of known expansions of typedef.
typedefs_maybe: List of typedefed names.
vdecl_hash: Hash of parsed extern variable declarations.
vdecls: List of extern variable declarations.
topDeclarations: List of all top-level declarations.
cdecl: List of all top-level declarations in human-readable format, i.e. a-la cdecl.

--xml

Print out an XML view of all declarations and definitions.

The XML will have this structure:

 <C>
   <decls>...</decls>
   <decls>...</decls>
   ...
   <defs>...</defs>
   <defs>...</defs>
 </C>

There is one <decl/> element per declaration, one <defs/> element per function definition. Both can have the following attributes:

rt: Return type of a function.
nm: Identifier
ft: Full text used to get this information.
mod: Array modifiers if any (for example: char x[2] will make mod to be: '[2]').
ty: Type of a declarator. In case of a function, the type will contain only eventual stars '*'.
extern: "1" value means this is an 'extern' declaration.
typedef: "1" value means this is an 'typedef' declaration.
init: Declarator initialization, if any. For example, with char *x = "value" init will be the string "value".
func: "1" means this is an function declaration.
struct: "1" means this is a struct declaration.
union: "1" means this is a union declaration.
structOrUnion: "1" means this is a struct or union declaration. If true, it is guaranteed that one of 'struct' or 'union' attributes is true.
type: "1" means this is a type declaration. If true, it is guaranteed that one of 'typedef' or 'structOrUnion' attribute is true, and that the 'var' attribute (see below) is false.
var: "1" means this is a variable declaration. If true, it is guaranteed that the 'type' attribute is false.
file: Filename where this parsed statement occurs. The filename is derived from the preprocessor output, with no modification.
line: Line number within filename where is beginning the attribute 'ft'.

The only possible child element is:

args: Array reference of arguments parsed declarations, which can have same attributes as listed below, and other args children.

--in <argument>

Load a full XML view of all declarations and definitions from this filename.

Doing so will prevent any preprocessor call and analysis: cscan will assume this XML has a correct format. Such option exist because analysing preprocessing output takes time, and often, once the analysis is done, it is easier to reload the result to do xpath queries. For instance, first you create the XML:

 cscan --out /tmp/file.xml --xml /tmp/file.c

then you do xpath queries on the reloaded output:

 cscan --in /tmp/file.xml --xpath "//*[contains(@nm,'x')]"
 cscan --in /tmp/file.xml --xpath "//*[contains(@nm,'Y')]"

When you use the --in option, the --get option becomes a noop.

--xpath <argument>

Dump the result of an XPath (version 1) query on the XML structure described above. Found nodes are converted to hashes for readibility and printed out. For example, to find all nodes having an identifier named "x":

 cscan --xpath "//*[contains(@nm,'x')]" /tmp/file.c

To find all declared strings:

 cscan --xpath "//*[starts-with(@init,'\"')]" /tmp/file.c

To find all function definitions that have at least one argument of type "double":

 cscan --xpath "//*[@func=\"1\"]/args[@var=\"1\" and @ty=\"double\"]/.." /tmp/file.c

--out <argument>

Redirect any output to this filename.

--err <argument>

Redirect any error to this filename.

--loglevel level

A level that has to be meaningful for Log::Log4perl, typically DEBUG, INFO, WARN, ERROR, FATAL or TRACE. Default is WARN.

Note that tracing Marpa library itself is possible, but only using environment variable MARPA_TRACE /and/ saying --loglevel TRACE.

In case of trouble, typical debugging phases are: --loglevel INFO then: --loglevel DEBUG then: --loglevel TRACE

--debug

Shortcut for --loglevel DEBUG

--info

Shortcut for --loglevel INFO

--warn

Shortcut for --loglevel WARN

--error

Shortcut for --loglevel ERROR

--fatal

Shortcut for --loglevel FATAL

--trace

Shortcut for --loglevel TRACE

--logstderr

Log to stderr or not. Default is a false value.

--enumType

Type for enumerators. Default is 'int'.

--lazy

Instruct the parser to try all alternatives on typedef/enum/identifier. Default is a false value.

--typedef typedefs

Comma separated list of known typedefs. Can be repeated. Default is an empty list.

--enum enums

Comma separated list of known enums. Can be repeated. Default is an empty list.

EXAMPLES

 cscan --get strings                                                                         /tmp/file.c
 cscan --get strings,macros --cppflags "-I/tmp/dir1            -DMYDEFINE"                   /tmp/file.c
 cscan --get strings,macros --cppflags  -I/tmp/dir1 --cppflags -DMYDEFINE                    /tmp/file.c
 cscan --get strings        --cppflags  -I/tmp/dir1 --cppflags -DMYDEFINE --filter '/\.H$/i' /tmp/file.c

The parsing result for the following source code, in filename test.c:

 int func1(int x1, double *x2, float *( f1)(int x11, double x12));
 int func1(int x1, double *x2, float *( f1)(int x11, double x12)) {
   char *string = "&";
   return 0;
 }

will be converted to xml using:

 cscan --xml test.c

giving:

 <C>
   <decls file="test.c" ft="int func1(int x1, double *x2, float *( f1)(int x11, double x12))" func="1" line="1" nm="func1" rt="int" var="1">
     <args file="test.c" ft="int x1" line="1" nm="x1" ty="int" var="1" />
     <args file="test.c" ft="double *x2" line="1" nm="x2" ty="double *" var="1" />
     <args file="test.c" ft="float *( f1)(int x11, double x12)" func="1" line="1" nm="f1" rt="float *" var="1">
       <args file="test.c" ft="int x11" line="1" nm="x11" ty="int" var="1" />
       <args file="test.c" ft="double x12" line="1" nm="x12" ty="double" var="1" />
     </args>
   </decls>
   <defs file="test.c" ft="int func1(int x1, double *x2, float *( f1)(int x11, double x12)) {
  char *string = &quot;&amp;&quot;;
  return 0;
}" func="1" line="2" nm="func1" rt="int">
     <args file="test.c" ft="int x1" line="2" nm="x1" ty="int" var="1" />
     <args file="test.c" ft="double *x2" line="2" nm="x2" ty="double *" var="1" />
     <args file="test.c" ft="float *( f1)(int x11, double x12)" func="1" line="2" nm="f1" rt="float *" var="1">
       <args file="test.c" ft="int x11" line="2" nm="x11" ty="int" var="1" />
       <args file="test.c" ft="double x12" line="2" nm="x12" ty="double" var="1" />
     </args>
   </defs>
 </C>

while the following source code:

 struct s1_ {
   int x;
   enum {E1, E2} e;
   struct {
     long y;
     double z;
     char *s[1024][32];
   } innerStructure;
 };

will give the following XML:

 <C>
   <decls enum="1" nm="ANON0" ty="ANON0" type="1">
     <args file="test.c" ft="E1" line="3" nm="E1" ty="int" var="1" />
   </decls>
   <decls nm="s1_" struct="1" structOrUnion="1" ty="struct s1_" type="1">
     <args file="test.c" ft="int x" line="2" nm="x" ty="int" var="1" />
     <args file="test.c" ft="enum {E1, E2} e" line="3" nm="e" ty="ANON0" var="1" />
     <args nm="ANON1" struct="1" structOrUnion="1" ty="struct ANON1" type="1">
       <args file="test.c" ft="long y" line="5" nm="y" ty="long" var="1" />
       <args file="test.c" ft="double z" line="6" nm="z" ty="double" var="1" />
       <args file="test.c" ft="char *s[1024][32]" line="7" mod="[1024][32]" nm="s" ty="char *" var="1" />
     </args>
     <args file="test.c" ft="struct {
     long y;
     double z;
     char *s[1024][32];
   } innerStructure" line="4" nm="innerStructure" ty="struct ANON1" var="1" />
   </decls>
   <decls file="test.c" ft="struct s1_ {
   int x;
   enum {E1, E2} e;
   struct {
     long y;
     double z;
     char *s[1024][32];
   } innerStructure;
 };" line="1" nm="ANON2" ty="struct s1_" var="1" />
 </C>

In the later example you see that anonymous types can be in an arg element. They do not have the attribute "var". Anonymous types are of two categeries: structOrUnion (divided again in struct or union), and enum. Per definition, enum types are always global, wherever and whenever they appear, i.e. they will always be a direct child of <decls/>. On contrary, structOrUnion types always stay in the scope of their declaration.

NOTES

Any unknown option on the command line is passed through to --cppflags. I.e.:

 cscan --get strings,macros --cppflags  -I/tmp/dir1 --cppflags -DMYDEFINE /tmp/file.c

and

 cscan --get strings,macros -I/tmp/dir1 -DMYDEFINE /tmp/file.c

are equivalent. A restriction is that the filename must be the last argument.

NOTES

If last argument is absent or equal to '-' and if there is no '--in' option value, then STDIN is assumed.
cdecl is an alias to cscan --get cdecl. Therefore when cdecl --help is invoked, this will mention cscan instead of cdecl.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

AUTHOR

COPYRIGHT AND LICENSE

NAME

SYNOPSIS

OPTIONS

EXAMPLES

NOTES

NOTES

SEE ALSO

Module Install Instructions