view release on metacpan or  search on metacpan

lib/Affix/Wrap.pod  view on Meta::CPAN

=pod

=encoding utf-8

=head1 NAME

Affix::Wrap - Frictionless C/C++ Binding Generator for Affix

=head1 SYNOPSIS

    use Affix::Wrap;

    my $wrapper = Affix::Wrap->new(
        project_files => ['/usr/include/sqlite3.h'],
        include_dirs  => ['/usr/include'],
        types         => {
            'sqlite3' => 'Pointer[Void]' # Custom override
        }
    );

    # Option 1: Instantly wrap and inject into the current namespace
    # You may call functions exported by the lib immediately
    $wrapper->wrap('libsqlite3.so', __PACKAGE__);

    # Option 2: Generate a standalone Perl module file to disk
    # This should get you started on a library wrapper you'll eventually put on CPAN
    $wrapper->generate('libsqlite3.so', 'My::SQLite', 'lib/My/SQLite.pm');

=head1 DESCRIPTION

C<Affix::Wrap> is a frictionless binding generator that bridges C/C++ header files and L<Affix>. It parses headers to
extract functions, structs, enums, typedefs, macros, and global variables, automatically converting this information
into L<Affix> definitions.

It is designed to facilitate two primary developer workflows:

=over

=item 1. B<Rapid Prototyping (Runtime Wrapping)>

Parse headers on the fly and inject bindings directly into your running Perl environment via C<wrap()>. This is perfect
for private tooling, experimental scripts, or whenever you want to avoid the boilerplate of a dedicated FFI module.

=item 2. B<Distribution (Static Generation)>

Generate standalone F<.pm> files for CPAN via C<generate()>. This produces a pure-Perl module that depends only on
L<Affix>, ensuring fast load times and zero development dependencies (like C<Clang> or C<Affix::Wrap> itself) for your
end users.

=back

=head2 Parsing Drivers

C<Affix::Wrap> employs a dual-driver strategy:

=over

=item * B<Clang Driver (Recommended)>

The primary driver. It leverages C<clang -Xclang -ast-dump=json> to perform compiler-grade analysis of your headers. It
is highly accurate and handles complex C++ templates, macros, and deep inclusion chains with ease.

=item * B<Regex Driver (Fallback)>