NAME

P5NCI::Library - an OO library to the Native Calling Interface for Perl 5

SYNOPSIS

        use P5NCI::Library;

        # load a shared library
        my $lib = P5NCI::Library->new( library => 'nci_test' );

        # fetch a reference to a function in a shared libarry
        my $double_double = $lib->load_function( 'double_double', 'dd' );
        my $two_point_oh  = $double_double->( 1.0 );

        # load a shared library and associate it with a namespace
        my $lib = P5NCI::Library->new( library => 'nci_test', package => 'NCI' );

        # install a function from the shared library into the namespace
        $lib->install_function( 'double_int', 'ii' );
        my $two = NCI::double_int( 1 );

        # or call it from that namespace
        package NCI;

        my $six = double_int( 3 );

DESCRIPTION

P5NCI::Library provides an object-oriented way of loading shared libraries and their functions, including installing them in specified namespaces. This makes it easy to call C functions from Perl without writing any messy glue code yourself -- or having to compile any XS!

METHODS

new( library = $library_name, [ package => $package_name ] )>

Loads the library named in $library_name if possible and returns a new P5NCI::Library object.

This will throw an exception if you fail to provide a library name or if it cannot find a library of the given name. Note that $library_name should ideally be the cross-platform library name. For example, use nci_test instead of libnci_test.so on Unix, nci_test.dll on Windows, or libnci_test.dylib on Mac OS X.

The optional package parameter sets the name of the package to which the library object can install loaded functions directly. You don't have to do this. If you don't specify a package name, it will default to main.

package()

Returns the name of the package into which the object can install shared library functions.

load_function( $function_name, $signature )

Attempts to load the function named $function_name with the signature $signature from the shared library this object represents. Signatures are simple strings representing the types of the arguments the function takes in their simplest forms. For example, a function that takes two ints and returns an int would have a signature of iii. A function that takes two ints and returns nothing (or void) has a signature of vii. The current working signature items are:

i, an integer

f, a float

d, a double

s, a short

t, a string

v, void (nothing)

Note: The signature list will definitely expand and may change in the future.

This function returns a Perl subroutine reference to the library function. Call it as you would any other subroutine reference. Note that it will throw an exeption if you pass the wrong number of values. It will probably segfault or do horrible things if you pass the wrong type of values. That's what happens when you play with C.

This function itself will throw an exception if you fail to provide both a function name and its signature. It will also throw an exception if it does not understand the signature. That might not be an error -- it doesn't understand a lot of valid signatures yet.

install_function( $function_name, $function_signature )

Loads the function with the given name and signature from the library the object represents and installs it into the namespace associated with the object. This will throw the same exceptions as does load_function under the same circumstances.

It also returns the same subroutine reference.

AUTHOR

chromatic, <chromatic at wgz dot org>

BUGS

No known bugs. Several known limitations.

COPYRIGHT

Copyright (c) 2004, 2006 - 2007, chromatic. All rights reserved.

This module is free software; you can use, redistribute, and modify it under the same terms as Perl 5.8.x.