NAME
    MarpaX::Languages::C::AST - Translate a C source to an AST

VERSION
    version 0.16

SYNOPSIS
        use strict;
        use warnings FATAL => 'all';
        use MarpaX::Languages::C::AST;
        use Log::Log4perl qw/:easy/;
        use Log::Any::Adapter;
        use Log::Any qw/$log/;
        use Data::Dumper;
        #
        # Init log
        #
        our $defaultLog4perlConf = '
        log4perl.rootLogger              = WARN, Screen
        log4perl.appender.Screen         = Log::Log4perl::Appender::Screen
        log4perl.appender.Screen.stderr  = 0
        log4perl.appender.Screen.layout  = PatternLayout
        log4perl.appender.Screen.layout.ConversionPattern = %d %-5p %6P %m{chomp}%n
        ';
        Log::Log4perl::init(\$defaultLog4perlConf);
        Log::Any::Adapter->set('Log4perl');
        #
        # Parse C
        #
        my $cSourceCode = '
        typedef struct s1_ {int i1;} x1, y1;
        struct x1 {x1 i2;};
        x1 x;
        ';
        my $cAstObject = MarpaX::Languages::C::AST->new();
        $log->infof('%s', $cAstObject->parse(\$cSourceCode));

DESCRIPTION
    This module translates C source into an AST tree. To assist further
    process of the AST tree, the nodes of the AST are blessed according to
    the C grammar you have selected. (The default is 'ISO-ANSI-C-2011'.) If
    you want to enable logging, be aware that this module is a Log::Any
    thingy.

    This module implements the full syntax, as well as those specification
    constraints which are syntactic in nature: Associativity of nested
    if-then-else statements is according to the C standards, as is the
    treatment of names as typedefs, enums, or variable identifiers.

    The C standards contain many constraints that are non-syntactic.
    MarpaX::Languages::C::AST does not implement these, leaving them for AST
    post-process. One example of a non-syntactic constraint is the
    requirement that labeled statements within a function be unique. Another
    is the requirement that declarations include at most one storage class
    specifier.

SUBROUTINES/METHODS
  new($class, %options)
    Instantiate a new object. Takes as parameter an optional hash of options
    that can be:

    grammarName
        Name of a grammar. Default is 'ISO-ANSI-C-2011'.

    logInfo
        Reference to an array of lexemes for which a log of level INFO will
        be issued.

    lexemeCallback
        Array reference containing a CODE ref and optional arguments. This
        callback will be trigerred like this: &$CODE(@arguments,
        $lexemeHashp), where $lexemeHashp is a reference to a hash
        describing current lexeme:

        name
            Name of the lexeme. You have to refer to the grammar used to get
            its definition, although this is usually self-explanatory.

        start
            G1 (Marpa term) start location.

        length
            Length of the lexeme

        line
            Line number in the source being parsed.

        column
            Column number in the source being parsed.

        value
            String containing lexeme value.

  parse($self, $sourcep)
    Do the parsing. Takes as parameter the reference to a C source code.
    Returns $self, so that chaining with value method will be natural, i.e.
    parse()->value().

  value($self, $optionalArrayOfValuesb)
    Return the blessed value. Takes as optional parameter a flag saying if
    the return value should be an array of all values or not. If this flag
    is false, the module will croak if there more than one parse tree value.
    If this flag is true, a reference to an array of values will be
    returned, even if there is a single parse tree value.

SEE ALSO
    Log::Any, Marpa::R2

SUPPORT
  Bugs / Feature Requests
    Please report any bugs or feature requests through the issue tracker at
    <https://rt.cpan.org/Public/Dist/Display.html?Name=MarpaX-Languages-C-AS
    T>. You will be notified automatically of any progress on your issue.

  Source Code
    This is open source software. The code repository is available for
    public review and contribution under the terms of the license.

    <https://github.com/jddurand/marpax-languages-c-ast>

      git clone git://github.com/jddurand/marpax-languages-c-ast.git

AUTHOR
    Jean-Damien Durand <jeandamiendurand@free.fr>

CONTRIBUTORS
    *   Jeffrey Kegler <jkegl@cpan.org>

    *   jddurand <jeandamiendurand@free.fr>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by Jean-Damien Durand.

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