NAME

    Const::Introspect::C - Find and evaluate C/C++ constants for use in
    Perl

VERSION

    version 0.01

SYNOPSIS

     use Const::Introspect::C;
     
     my $c = Const::Introspect::C->new(
       headers => ['foo.h'],
     );
     
     foreach my $const ($c->get_macro_constants)
     {
       # const isa Const::Introspect::C::Constant
       say "name  = ", $const->name;
       # type is one of: int, long, pointer, string,
       #                 float, double or "other"
       say "type  = ", $const->type;
       say "value = ", $const->value;
     }

DESCRIPTION

    Note: This is an early release, expect some interface changes in the
    near future.

    This module provides an interface for finding C/C++ constant style
    macros, and can compute their types and values. It can also be used to
    compute the values of enumerated type constants, although this module
    doesn't have a way of finding the names (For that try something like
    Clang::CastXML).

PROPERTIES

 headers

    List of C/C++ header files.

 lang

    The programming language. Should be one of c or c++. The default is c.

 cc

    The C compiler. The default is the C compiler used by Perl itself,
    automatically split on the appropriate whitespace. This should be a
    array reference, so ['clang'] and not 'clang'. This allows for cc with
    spaces in it.

 ppflags

    The C pre-processor flags. This may change in the future, or on some
    platforms, but as of this writing this is -dM -E -x c for C and -dM -E
    -x c++ for C++. This must be an array reference.

 cflags

    C compiler flags. This is what Perl uses by default. This must be an
    array reference.

 extra_cflags

    Extra Compiler flags. This is an empty array by default. This allows
    the caller to provide additional library specific flags, like -I.

 source

    C source file. This is an instance of Path::Tiny and it is created
    on-the-fly. You shouldn't need to specify this explicitly.

 filter

    Filter regular expression that all macro names must match. This is
    ^[^_] by default, which means all macros starting with an underscore
    are skipped.

 diag

    List of diagnostic failures.

METHODS

 get_macro_constants

     my @const = $c->get_macro_constants;

    This generates the source file, runs the pre-processor, parses the
    macros as well as possible and returns the result as a list of
    Const::Introspect::C::Constant instances.

 get_single

     my $const = $c->get_single($name);

    Get a single constant by the name of $name. Returns an instance of
    Const::Introspect::C. This is most useful for getting the integer
    values for named enumerated values.

 compute_expression_type

     my $type = $c->compute_expression_type($expression);

    This attempts to compute the type of the C $expression. It should
    return one of int, long, string, float, double, or other. If the type
    cannot be determined then other will be returned, and often indicates a
    code macro that doesn't have a corresponding constant.

 compute_expression_value

     my $value = $c->compute_expression_value($type, $expression);

    This method attempts to compute the value of the given C $expression of
    the given $type. $type should be one of int, long, string, float, or
    double.

    If you do not know the expression type, you can try to compute the type
    using compute_expression_type above.

CAVEATS

    This modules requires the C pre-processor for macro constants, and for
    many constants requires a compiler to compute the type and value. The
    techniques used by this module work with clang and gcc, but they
    probably don't work with other compilers. Patches welcome to support
    other compilers.

    This module can tell you the value of pointer constants, but there is
    not much utility to the value of non NULL values.

AUTHOR

    Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2020 by Graham Ollis.

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

