1=head1 NAME
2
3ExtUtils::ParseXS - converts Perl XS code into C code
4
5=head1 SYNOPSIS
6
7  use ExtUtils::ParseXS;
8
9  my $pxs = ExtUtils::ParseXS->new;
10  $pxs->process_file( filename => 'foo.xs' );
11
12  $pxs->process_file( filename => 'foo.xs',
13                      output => 'bar.c',
14                      'C++' => 1,
15                      typemap => 'path/to/typemap',
16                      hiertype => 1,
17                      except => 1,
18                      versioncheck => 1,
19                      linenumbers => 1,
20                      optimize => 1,
21                      prototypes => 1,
22                    );
23
24  # Legacy non-OO interface using a singleton:
25  use ExtUtils::ParseXS qw(process_file);
26  process_file( filename => 'foo.xs' );
27
28=head1 DESCRIPTION
29
30C<ExtUtils::ParseXS> will compile XS code into C code by embedding the constructs
31necessary to let C functions manipulate Perl values and creates the glue
32necessary to let Perl access those functions.  The compiler uses typemaps to
33determine how to map C function parameters and variables to Perl values.
34
35The compiler will search for typemap files called I<typemap>.  It will use
36the following search path to find default typemaps, with the rightmost
37typemap taking precedence.
38
39    ../../../typemap:../../typemap:../typemap:typemap
40
41=head1 EXPORT
42
43None by default.  C<process_file()> and/or C<report_error_count()>
44may be exported upon request. Using the functional interface is
45discouraged.
46
47=head1 METHODS
48
49=over 4
50
51=item $pxs->new()
52
53Returns a new, empty XS parser/compiler object.
54
55=item $pxs->process_file()
56
57This method processes an XS file and sends output to a C file.
58The method may be called as a function (this is the legacy
59interface) and will then use a singleton as invocant.
60
61Named parameters control how the processing is done.
62The following parameters are accepted:
63
64=over 4
65
66=item B<C++>
67
68Adds C<extern "C"> to the C code.  Default is false.
69
70=item B<hiertype>
71
72Retains C<::> in type names so that C++ hierarchical types can be
73mapped.  Default is false.
74
75=item B<except>
76
77Adds exception handling stubs to the C code.  Default is false.
78
79=item B<typemap>
80
81Indicates that a user-supplied typemap should take precedence over the
82default typemaps.  A single typemap may be specified as a string, or
83multiple typemaps can be specified in an array reference, with the
84last typemap having the highest precedence.
85
86=item B<prototypes>
87
88Generates prototype code for all xsubs.  Default is false.
89
90=item B<versioncheck>
91
92Makes sure at run time that the object file (derived from the C<.xs>
93file) and the C<.pm> files have the same version number.  Default is
94true.
95
96=item B<linenumbers>
97
98Adds C<#line> directives to the C output so error messages will look
99like they came from the original XS file.  Default is true.
100
101=item B<optimize>
102
103Enables certain optimizations.  The only optimization that is currently
104affected is the use of I<target>s by the output C code (see L<perlguts>).
105Not optimizing may significantly slow down the generated code, but this is the way
106B<xsubpp> of 5.005 and earlier operated.  Default is to optimize.
107
108=item B<inout>
109
110Enable recognition of C<IN>, C<OUT_LIST> and C<INOUT_LIST>
111declarations.  Default is true.
112
113=item B<argtypes>
114
115Enable recognition of ANSI-like descriptions of function signature.
116Default is true.
117
118=item B<s>
119
120I<Maintainer note:> I have no clue what this does.  Strips function prefixes?
121
122=back
123
124=item $pxs->report_error_count()
125
126This method returns the number of [a certain kind of] errors
127encountered during processing of the XS file.
128
129The method may be called as a function (this is the legacy
130interface) and will then use a singleton as invocant.
131
132=back
133
134=head1 AUTHOR
135
136Based on xsubpp code, written by Larry Wall.
137
138Maintained by:
139
140=over 4
141
142=item *
143
144Ken Williams, <ken@mathforum.org>
145
146=item *
147
148David Golden, <dagolden@cpan.org>
149
150=item *
151
152James Keenan, <jkeenan@cpan.org>
153
154=item *
155
156Steffen Mueller, <smueller@cpan.org>
157
158=back
159
160=head1 COPYRIGHT
161
162Copyright 2002-2014 by Ken Williams, David Golden and other contributors.  All
163rights reserved.
164
165This library is free software; you can redistribute it and/or
166modify it under the same terms as Perl itself.
167
168Based on the C<ExtUtils::xsubpp> code by Larry Wall and the Perl 5
169Porters, which was released under the same license terms.
170
171=head1 SEE ALSO
172
173L<perl>, ExtUtils::xsubpp, ExtUtils::MakeMaker, L<perlxs>, L<perlxstut>.
174
175=cut
176
177
178