DESCRIPTION

This module scans a C source and exposes methods compatible with C::Scan module.

SUBROUTINES

new($class, %options)

Instantiate a new object. Parameters are in a hash that can contain the following keys:

filename

File name to parse.

content

Content to parse.

filename_filter

Filter on filename from pre-processor output.

asDOM

Say that all C::Scan-like methods should return an xml document.

enumType

Type for enumerators. Default is 'int'.

xpathDirectories

A reference to an array giving xpath directories that will have precedence over the shared directory installed with this module.

xsltDirectories

A reference to an array giving xslt directories that will have precedence over the shared directory installed with this module.

cpprun

Preprocessor command, default is $ENV{MARPAX_LANGUAGES_C_SCAN_CPPRUN}, or $Config{cpprun}. It is assume that cpprun is already correctly quoted for your system shell.

cppflags

Preprocessor flags, default is $ENV{MARPAX_LANGUAGES_C_SCAN_CPPFLAGS}, $Config{cppflags}. It is assume that cppflags is already correctly quoted for your system shell.

nocpp

Disable preprocessor command. It is then up to the user to make that filename, or content, are suitable for the grammar. Eventually setting other MarpaX::Languages::C::AST->new() other options, like lazy mode and/or a list of typedef. Default is a false value.

Any other option is passed as-is to MarpaX::Languages::C::AST->new() and will have precedence.

Please refer to the Config perl documentation for the meaning of $Config{cpprun} or $Config{cppflags}.

This module will execute "$cpprun $cppflags $filename", using a temporary filename if $content was given. Thus a working precompiler is required.

$filename and $content are mutually exclusive. If $content is used a temporary file will be created using File::Temp (which may fail under taint mode -;).

The $filename_filter value limits the output to file names equal to $filename_filter (if this is a SCALAR) or matching $filename_filter (if this is a Regexp): since we use the precompiler, any #include statements is "polluting" the original source, i.e. much more files that just $filename (or $content) are used. Default value is $filename or the generated temporary filename when using $content mode.

The methods defines_args() and defines_no_args() are not subject to the filename_filter parameter: they always apply on the content or filename given /before/ the preprocessing. They are based on heuristic parsing, so their result should not be blindly trusted. A typical example of false positive is a macro inside string or a comment.

This module will croak on any error.

METHODS

ast($self)

AST of the preprocessed output. This is an XML::LibXML document.

astToString($self)

Stringified AST of the preprocessed output. This is an XML::LibXML document passed through its toString(1) in DOM mode, a Data::Dumper output if non-DOM mode.

get($self, $attribute)

C::Scan like method, that is a proxy to $self->$attribute. All methods described after can be used as attribute, for example: $self->get('strings'), or $self->get('includes').

includes($self)

Returns a reference to a list of included files, sorted alphabetically. This is available JUST because preprocessors give the file that has been preprocessed in their output using a #line directive, and there is a special procedure in MarpaX::Languages::C::AST for that, on top of the ISO C grammar.

defines_args($self)

Returns a reference to hash of macros with arguments. The values are references to an array of length 2, the first element is a reference to the list of arguments, the second one being the expansion.

defines_no_args($self)

Returns a reference to hash of macros without arguments.

strings($self)

Returns a reference to a list of strings after preprocessing, regardless of scope level.

macros($self)

Returns a reference to a list of macros before preprocessing.

fdecls($self)

C::Scan compatible reference to a list of parsed declarations of functions.

inlines($self)

C::Scan compatible reference to a list of definitions of functions.

parsed_fdecls($self)

C::Scan NOT-FULLY compatible reference to list of parsed declarations of functions: the type of arguments consist only of type specifiers as per the grammar. For instance pointers are not in argument types: strictly speaking pointers are part of a declarator.

typedef_hash($self)

Reference to a hash which contains known typedefs as keys. Values of the hash are array references of length 2, with what should be put before/after the type for a standalone typedef declaration (but without the typedef substring). Note that it is the minimal full text of the C source that is used to obtain the before/after strings, so this /can/ contain definition of other variables.

typedef_texts($self)

Returns a reference to a list which contains known expansions of typedefs. This is just the first indice from "value" part of typedef_hash.

typedefs_maybe($self)

Returns a reference to a list of typedefed names. This is just the "key" part of typedef_hash. The name "maybe" is kept for compatibility with C::Scan.

vdecls($self)

Returns a reference to a list of extern variable declarations.

vdecl_hash($self)

Reference to a hash of parsed extern variable declarations, containing the variable names as keys. Values of the hash are array references of length 2, with what should be put before/after the name for a standalone extern variable declaration (but without the extern substring). Note that it is the minimal full text of the C source that is used to obtain the before/after strings, so this /can/ contain definition of other variables.

typedef_structs($self)

Hopefully C::Scan compatible reference to a hash which contains known typedefs as keys. The values of the hash may not be compatible with C::Scan output. In our case these are array references of length 2, with at index 0 the full text used to parsed this typedef (maybe inclusing more than needed, but always what is necessary), and at index 1 an empty string.

topDeclarations($self)

All top-level declarations. This is a XML::LibXML::Document containing a list of declaration children. Available only when asDOM option is a true value.

cdecl($self)

Cdecl-like string of top-level declarations. Available only when asDOM option is atrue value. Returns a reference to an array.

c2cifce($self, $lang, %params)

Applies the transformation $lang, with parameters %params, and returns an array composed of the XML::LibXSLT instance and the transformed new XML::LibXML::Document.

NOTES

The default return type for functions without type specifier is fixed to 'int', as per the C standard.