https://github.com/gitpan/Text-CPP

Read-only release history for Text-CPP
https://github.com/gitpan/Text-CPP

Last synced: 18 days ago
JSON representation

Read-only release history for Text-CPP

• Host: GitHub
• URL: https://github.com/gitpan/Text-CPP
• Owner: gitpan
• License: gpl-2.0
• Created: 2014-10-22T09:37:03.000Z (about 10 years ago)
• Default Branch: master
• Last Pushed: 2014-10-22T09:37:35.000Z (about 10 years ago)
• Last Synced: 2024-07-31T22:58:43.870Z (3 months ago)
• Language: C
• Homepage: http://metacpan.org/release/Text-CPP
• Size: 371 KB
• Stars: 0
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README
  • License: COPYING

Awesome Lists containing this project

README

        
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:

            CLK_GNUC89 - GNU C89

            CLK_GNUC99 - GNU C99

            CLK_STDC89 - Standard C89

            CLK_STDC94 - Standard C94

            CLK_STDC99 - Standard C99

            CLK_GNUCXX - GNU C++

            CLK_CXX98 - Standard C++ 98

            CLK_ASM - Assembler

        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

    Dependency output

    Lots more tests

    Remaining callbacks

    Virtual file support

    Multiplicity

SUPPORT

    Mail the author at 

AUTHOR

            Shevek

            CPAN ID: SHEVEK

            [email protected]

            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).