view release on metacpan or  search on metacpan

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

=over

=item * C<affix_type>: Returns a complete Perl string to bind this function (e.g., C<affix $lib, name =E<gt> ...>).

=item * C<affix( $lib, $pkg )>: Installs the function into C<$pkg>.

=back

=head2 Affix::Wrap::Struct

A C struct or union definition.

=over

=item * C<tag>: Either 'struct' or 'union'.

=item * C<affix_type>: Returns signature string C<Struct[ ... ]> or C<Union[ ... ]>.

=back

=head2 Affix::Wrap::Typedef

A name alias for another type.

=over

=item * C<underlying>: The type object being aliased.

=item * C<affix_type>: Returns string C<typedef Name =E<gt> UnderlyingType>.

=back

B<Note:> In C, C<typedef struct { ... } Name;> results in a C<Typedef> object where B<underlying> is the C<Struct>
object.

=head2 Affix::Wrap::Enum

An enumeration.

=over

=item * C<affix_type>: Returns signature string C<Enum[ Name =E<gt> Val, ... ]>. String values/expressions in enums are quoted automatically to prevent eval errors.

=back

=head2 Affix::Wrap::Variable

A global C<extern> variable.

=over

=item * C<affix_type>: Returns string C<pin my $var, $lib, name =E<gt> Type>.

=item * C<affix( $lib, $pkg )>: Installs the variable accessor into C<$pkg>.

=back

=head2 Affix::Wrap::Macro

A preprocessor C<#define>. Only simple value macros are captured.

=over

=item * C<affix_type>: Returns string C<use constant Name =E<gt> Value>. Expressions (e.g., C<A + B>) are quoted as strings, while literals are preserved.

=item * C<affix( undef, $pkg )>: Installs the constant into C<$pkg>.

=back

=head1 Tutorials

=head2 Runtime Library Wrappers

If you want to use a C library immediately without creating a separate Perl module file, use the C<wrap> method.

    use Affix;
    use Affix::Wrap;

    my $lib = load_library('demo');

    # This parses demo.h and installs subroutines, constants,
    # and types directly into the calling package.
    Affix::Wrap->new( project_files => ['demo.h'] )->wrap($lib);

    # Now you can use them:
    my $obj = Demo_CreateStruct();

=head3 Manual Control

If you need to filter which functions are bound or rename them, you can iterate over the AST manually instead of
calling C<wrap>:

    my $binder = Affix::Wrap->new( project_files => ['demo.h'] );
    for my $node ( $binder->parse ) {
        next if $node->name =~ m[^Internal_]; # Skip internal functions
        # Manually bind
        if ( $node->can('affix') ) {
            $node->affix($lib);
        }
    }

=head2 Generating Affix Modules for CPAN

To create a distributable module (e.g., C<My::Lib.pm>) without requiring your users to have C<Clang> or C<Affix::Wrap>
installed at runtime, use the C<generate> method:

    use Affix::Wrap;

    my $binder = Affix::Wrap->new( project_files => ['mylib.h'] );

    # Creates 'lib/My/Lib.pm' which depends only on 'Affix'
    $binder->generate( 'mylib', 'My::Lib', 'lib/My/Lib.pm' );

If you need custom behaviors (like filtering functions or adding custom POD), you can iterate over the AST manually as
described in L<parse()>.

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>