view release on metacpan or  search on metacpan

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

The shared library to link the functions against.

=item C<$target_package>

Optional. The namespace to inject symbols and types into. Defaults to the caller package.

=back

=head2 generate( $lib, $pkg, $output_file )

    $binder->generate( 'mylib', 'My::Lib', 'lib/My/Lib.pm' );

Parses the headers and writes a fully functioning, standalone Perl .pm module to disk. This is highly recommended for
production modules to avoid the overhead of parsing headers at runtime.

=head2 parse( [$entry_point] )

    my @nodes = $binder->parse;

Parses the project files and returns a list of Node objects (see B<Data Model> below). Use this if you want to inspect
the C header structure or generate code strings for a static Perl module.

The nodes are sorted by file name and line number to ensure deterministic output order.

=over

=item C<$entry_point>

Optional. The specific file to start parsing from. Defaults to the first file in C<project_files>.

=back

=head1 Data Model

The C<parse()> method returns a list of objects inheriting from C<Affix::Wrap::Entity>.

All nodes provide at least two key methods:

=over

=item * C<affix_type>: Returns a B<string> of Perl code representing the type or declaration (e.g., C<"Int">, C<"typedef Foo => Int">). Used for code generation.

=item * C<affix( $lib, $pkg )>: Performs the actual binding at runtime. Installs symbols into C<$pkg> using C<$lib>.

=back

=head2 Affix::Wrap::Type

Represents a generic C type (e.g., C<int>, C<void>, C<size_t>).

=head2 Affix::Wrap::Type::Pointer

Represents C<T*> types. Wraps another type object.

=head2 Affix::Wrap::Type::Array

Represents C<T[N]> fixed-size arrays. Wraps a type object and a count.

=head2 Affix::Wrap::Type::CodeRef

Represents function pointers (callbacks), e.g., C<void (*)(int)>.

=over

=item * C<ret>: Return type object.

=item * C<params>: ArrayRef of argument type objects.

=item * C<affix_type>: Returns string C<Callback[[Args] =E<gt> Ret]>.

=back

=head2 Affix::Wrap::Argument

Function arguments. Stringifies to "Type Name".

=head2 Affix::Wrap::Member

Struct/Union members.

=over

=item * C<definition>: If the member defines a nested struct/union inline, this holds that definition object.

=item * C<affix_type>: Returns the signature of the type OR the nested definition.

=back

=head2 Affix::Wrap::Function

A C function declaration.

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