NAME
Text::CPP - A full C Preprocessor in XS
SYNOPSIS
use Text::CPP;
my $reader = new Text::CPP(
Language => CLK_GNUC99,
Options => {
...
},
Builtins => {
foo => 'this',
bar => 'that',
...
},
Callbacks => {
...
},
);
$reader->read("file.c");
while (my $token = $reader->token) {
print "Token: $token\n";
}
$reader->data->{MyKey} = $MyData;DESCRIPTION
A fast C preprocessor in XS. This does not require an external C preprocessor, and will not fork() or exec() any external process.
USAGE
The following methods have been implemented, allowing the use of this module as a pure C preprocessor, or as a lexer for a C, C++ or Assembler-like language.
- new Text::CPP(...)
-
Takes a hash or hashref with the following possible keys:
- Language
-
Defines the source language to preprocess and/or tokenise. It may be any of:
- Options
-
A hashref of options for the preprocessor. Valid entries are given with alternative forms (from GNU cpp) in brackets.
- Define (-D): array of strings or hash
-
Strings should be of the form NAME=VALUE.
- Undef (-U): array of strings
- DiscardComments (-C): boolean
- DiscardCommentsInMacroExp (-CC): boolean
- PrintIncludeNames (-H): boolean
- NoLineCommands (-P): boolean
- WarnComments (-Wcomment -Wcomments): boolean
- WarnDeprecated (-Wdeprecated): boolean
- WarningsAreErrors (-Werror): boolean
- WarnImport (-Wimport): boolean
- WarnMultichar (-Wmultichar): boolean
- WarnSystemHeaders (-Wsystem-headers): boolean
-
Ignore errors in system header files.
- WarnTraditional (-Wtraditional): boolean
- WarnTrigraphs (-Wtrigraphs): boolean
- WarnUnusedMacros (-Wunused-macros): boolean
- Pedantic (-pedantic): boolean
- PedanticErrors (-pedantic-errors): boolean
-
Implies, and overrides, Pedantic.
- Remap (-remap): boolean
-
Deal with some brokennesses of MSDOS. Untested.
- Trigraphs (-trigraphs): boolean
- Traditional (-traditional): boolean
- NoWarnings (-w): boolean
- IncludePrefix (-iprefix): string
- SystemRoot (-isysroot): string
- Include (-include): array of strings
-
Include the specified files before reading the main file to be processed.
- IncludeMacros (-imacros): array of strings
-
Include the specified files before reading the main file to be processed. Output from preprocessing these files is discarded. Files specified by IncludeMacros are processed before files specified by Include.
- IncludePath (-I): array of strings
-
This include path is searched first.
- SystemIncludePath (-isystem): array of strings
-
Specify the standard system include path, searched second.
- AfterIncludePath (-idirafter): array of strings
-
This include path is searched after the system include path.
- Builtins
-
A hashref of predefined macros. The values must be strings or integers. Macros in this hash will be defined before preprocessing starts. These correspond to true "builtin" macros. You should probably prefer to use the 'Define' option.
- Callbacks
-
The preprocessor makes callbacks when certain events occur.
- LineChange
-
Called when the line in the source file changes. Arguments are (XXX see BUGS)
- Ident
- Define
- Undef
- $text = $reader->token
- ($text, $type, $flags) = $reader->token
-
Return the next available preprocessed token. Some tokens are not stringifiable. These include tokens of type CPP_MACRO_ARG, CPP_PADDING and CPP_EOF. Text::CPP returns a dummy string in the 'text' field for these tokens. Tokens of type CPP_EOF should never actually be returned. Instead, an empty list is returned in list context, or undef in scalar context.
- @tokens = $reader->tokens
-
Preprocess and return a list of tokens. This is approximately equivalent to:
push(@tokens, $_) while ($_ = $reader->token); - $reader->type($type)
-
Return a human readable name for a token type, as returned by $reader->token.
- $reader->data
-
Returns a hashref in which user data may be stored by subclasses. This hashref is created with a new Text::CPP object, and is ignored for all functional purposes. The user may do with it as he wishes.
- $reader->errors
-
In scalar context, returns the fatal error count. In list context, returns a list of warnings and errors encountered by the preprocessor. Thus scalar(@errors) >= $errors, since @errors will also contain the warnings.
BUGS
Fewer than in the last release, and hopefully not very many.
This documentation is probably incomplete. There are many important functions in the source which are not yet documented.
It is not possible to instantiate multiple Text::CPP objects, since the underlying library uses many global variables.
C99 may not implement variadic macros correctly according to the ISO standard. I must check this. If anyone knows, please tell me.
The -M option is not yet handled.
Callbacks are not yet fully implemented.
CAVEATS
Memory for hash tables, token names, etc is only freed when the reader is destroyed.
Assertions are a deprecated feature, and thus the -A flag is not supported.
It does not seem necessary to support the following flags:
- -x
- -iwithprefix
- -iwithprefixbefore
- -fpreprocessed
-
The following options may be requested, but seem boring, so are not currently supported.
- -std
- -ansi
- -foperator-names
- -fshow-column
- -ftabstop
TODO
SUPPORT
Mail the author at <cpan@anarres.org>
AUTHOR
Shevek
CPAN ID: SHEVEK
cpan@anarres.org
http://www.anarres.org/projects/COPYRIGHT
Copyright (c) 2002 Shevek. All rights reserved.
This program is free software; but parts of it have been borrowed from, or based on, parts of the GNU C Compiler version 3.3.2. You may therefore redistribute and/or modify this code under the terms of the GNU GENERAL PUBLIC LICENSE. I am unable to release this code under the usual Perl license because that license includes the Artistic License, and I cannot rerelease GPL code under the Artistic License. Sorry.
The full text of the license can be found in the COPYING file included with this module.
SEE ALSO
perl(1).
4 POD Errors
The following errors were encountered while parsing the POD:
- Around line 359:
'=item' outside of any '=over'
- Around line 380:
You forgot a '=back' before '=head1'
- Around line 382:
'=item' outside of any '=over'
- Around line 392:
You forgot a '=back' before '=head1'