=head1 NAME ExtUtils::ParseXS - converts Perl XS code into C code =head1 SYNOPSIS use ExtUtils::ParseXS; my $pxs = ExtUtils::ParseXS->new; $pxs->process_file( filename => 'foo.xs' ); $pxs->process_file( filename => 'foo.xs', output => 'bar.c', 'C++' => 1, typemap => 'path/to/typemap', hiertype => 1, except => 1, versioncheck => 1, linenumbers => 1, optimize => 1, prototypes => 1, ); # Legacy non-OO interface using a singleton: use ExtUtils::ParseXS qw(process_file); process_file( filename => 'foo.xs' ); =head1 DESCRIPTION C<ExtUtils::ParseXS> will compile XS code into C code by embedding the constructs necessary to let C functions manipulate Perl values and creates the glue necessary to let Perl access those functions. The compiler uses typemaps to determine how to map C function parameters and variables to Perl values. The compiler will search for typemap files called I<typemap>. It will use the following search path to find default typemaps, with the rightmost typemap taking precedence. ../../../typemap:../../typemap:../typemap:typemap =head1 EXPORT None by default. C<process_file()> and/or C<report_error_count()> may be exported upon request. Using the functional interface is discouraged. =head1 METHODS =over 4 =item $pxs->new() Returns a new, empty XS parser/compiler object. =item $pxs->process_file() This method processes an XS file and sends output to a C file. The method may be called as a function (this is the legacy interface) and will then use a singleton as invocant. Named parameters control how the processing is done. The following parameters are accepted: =over 4 =item B<C++> Adds C<extern "C"> to the C code. Default is false. =item B<hiertype> Retains C<::> in type names so that C++ hierarchical types can be mapped. Default is false. =item B<except> Adds exception handling stubs to the C code. Default is false. =item B<typemap> Indicates that a user-supplied typemap should take precedence over the default typemaps. A single typemap may be specified as a string, or multiple typemaps can be specified in an array reference, with the last typemap having the highest precedence. =item B<prototypes> Generates prototype code for all xsubs. Default is false. =item B<versioncheck> Makes sure at run time that the object file (derived from the C<.xs> file) and the C<.pm> files have the same version number. Default is true. =item B<linenumbers> Adds C<#line> directives to the C output so error messages will look like they came from the original XS file. Default is true. =item B<optimize> Enables certain optimizations. The only optimization that is currently affected is the use of I<target>s by the output C code (see L<perlguts>). Not optimizing may significantly slow down the generated code, but this is the way B<xsubpp> of 5.005 and earlier operated. Default is to optimize. =item B<inout> Enable recognition of C<IN>, C<OUT_LIST> and C<INOUT_LIST> declarations. Default is true. =item B<argtypes> Enable recognition of ANSI-like descriptions of function signature. Default is true. =item B<s> I<Maintainer note:> I have no clue what this does. Strips function prefixes? =back =item $pxs->report_error_count() This method returns the number of [a certain kind of] errors encountered during processing of the XS file. The method may be called as a function (this is the legacy interface) and will then use a singleton as invocant. =back =head1 AUTHOR Based on xsubpp code, written by Larry Wall. Maintained by: =over 4 =item * Ken Williams, <ken@mathforum.org> =item * David Golden, <dagolden@cpan.org> =item * James Keenan, <jkeenan@cpan.org> =item * Steffen Mueller, <smueller@cpan.org> =back =head1 COPYRIGHT Copyright 2002-2014 by Ken Williams, David Golden and other contributors. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Based on the C<ExtUtils::xsubpp> code by Larry Wall and the Perl 5 Porters, which was released under the same license terms. =head1 SEE ALSO L<perl>, ExtUtils::xsubpp, ExtUtils::MakeMaker, L<perlxs>, L<perlxstut>. =cut