NAME

Clownfish::Binding::Perl - Perl bindings for a Clownfish::Hierarchy.

DESCRIPTION

Clownfish::Binding::Perl presents an interface for auto-generating XS and Perl code to bind C code for a Clownfish class hierarchy to Perl.

In theory this module could be much more flexible and its API could be more elegant. There are many ways which you could walk the parsed parcels, classes, methods, etc. in a Clownfish::Hierarchy and generate binding code. However, our needs are very limited, so we are content with a "one size fits one" solution.

In particular, this module assumes that the XS bindings for all classes in the hierarchy should be assembled into a single shared object which belongs to the primary, "boot" class. There's no reason why it could not write one .xs file per class, or one per parcel, instead.

The files written by this class are derived from the name of the boot class. If it is "Crustacean", the following files will be generated.

# Generated by write_bindings()
$lib_dir/Crustacean.xs
$lib_dir/Crustacean/Autobinding.pm

# Generated by write_boot()
$hierarchy_dest_dir/crust_boot.h
$hierarchy_dest_dir/crust_boot.c

METHODS

new

my $perl_binding = Clownfish::Binding::Perl->new(
    boot_class => 'Crustacean',                    # required
    parcel     => 'Crustacean',                    # required
    hierarchy  => $hierarchy,                      # required
    lib_dir    => 'lib',                           # required
    header     => "/* Autogenerated file */\n",    # required
    footer     => $copyfoot,                       # required
);

• boot_class - The name of the main class, which will own the shared object.

• parcel - The Clownfish::Parcel to which the boot_class belongs.

• hierarchy - A Clownfish::Hierarchy.

• lib_dir - location of the Perl lib directory to which files will be written.

• header - Text which will be prepended to generated C/XS files -- typically, an "autogenerated file" warning.

• footer - Text to be appended to the end of generated C/XS files -- typically copyright information.

write_bindings

$perl_binding->write_bindings;

Generate the XS bindings (including "Autobind.pm) for all classes in the hierarchy.

prepare_pod

my $filepaths_and_pod = $perl_binding->prepare_pod;
while ( my ( $filepath, $pod ) = each %$filepaths_and_pod ) {
    add_to_cleanup($filepath);
    spew_file( $filepath, $pod );
}

Auto-generate POD for all classes bindings which were spec'd with make_pod directives. See whether a .pod file exists and is up to date.

Return a hash representing POD files that need to be modified; the keys are filepaths, and the values are the POD file content.

The caller must take responsibility for actually writing out the POD files, after adding the filepaths to cleanup records and so on.

write_boot

$perl_binding->write_boot;

Write out "boot" files to the Hierarchy's dest_dir which contain code for bootstrapping Clownfish classes.

COPYRIGHT AND LICENSE

Copyright 2008-2011 Marvin Humphrey

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