This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
New XS::APItest's for sv_peek based on my DDumper work
[perl5.git] / ext / XS / APItest / APItest.pm
CommitLineData
3e61d65a
JH
1package XS::APItest;
2
3use 5.008;
4use strict;
5use warnings;
6use Carp;
7
8use base qw/ DynaLoader Exporter /;
9
10# Items to export into callers namespace by default. Note: do not export
11# names by default without a very good reason. Use EXPORT_OK instead.
12# Do not simply export all your public functions/methods/constants.
13
14# Export everything since these functions are only used by a test script
deec275f 15our @EXPORT = qw( print_double print_int print_long
9d911683 16 print_float print_long_double have_long_double print_flush
d4b90eee
SH
17 mpushp mpushn mpushi mpushu
18 mxpushp mxpushn mxpushi mxpushu
d1f347d7
DM
19 call_sv call_pv call_method eval_sv eval_pv require_pv
20 G_SCALAR G_ARRAY G_VOID G_DISCARD G_EVAL G_NOARGS
b8d2d791 21 G_KEEPERR G_NODEBUG G_METHOD G_WANT
7a646707 22 apitest_exception mycroak strtab
85ce96a1 23 my_cxt_getint my_cxt_getsv my_cxt_setint my_cxt_setsv
34482cd6 24 sv_setsv_cow_hashkey_core sv_setsv_cow_hashkey_notcore
218787bd 25 rmagical_cast rmagical_flags
f9c17636 26 DPeek
3e61d65a
JH
27);
28
f9c17636 29our $VERSION = '0.15';
84ac5fd7
NC
30
31use vars '$WARNINGS_ON_BOOTSTRAP';
0932863f
NC
32use vars map "\$${_}_called_PP", qw(BEGIN UNITCHECK CHECK INIT END);
33
9568a123
NC
34BEGIN {
35 # This is arguably a hack, but it disposes of the UNITCHECK block without
36 # needing to preprocess the source code
37 if ($] < 5.009) {
38 eval 'sub UNITCHECK (&) {}; 1' or die $@;
39 }
40}
41
0932863f
NC
42# Do these here to verify that XS code and Perl code get called at the same
43# times
44BEGIN {
45 $BEGIN_called_PP++;
46}
47UNITCHECK {
48 $UNITCHECK_called_PP++;
9568a123 49};
0932863f
NC
50{
51 # Need $W false by default, as some tests run under -w, and under -w we
52 # can get warnings about "Too late to run CHECK" block (and INIT block)
53 no warnings 'void';
54 CHECK {
55 $CHECK_called_PP++;
56 }
57 INIT {
58 $INIT_called_PP++;
59 }
60}
61END {
62 $END_called_PP++;
63}
64
84ac5fd7
NC
65if ($WARNINGS_ON_BOOTSTRAP) {
66 bootstrap XS::APItest $VERSION;
67} else {
0932863f 68 # More CHECK and INIT blocks that could warn:
84ac5fd7 69 local $^W;
84ac5fd7
NC
70 bootstrap XS::APItest $VERSION;
71}
3e61d65a
JH
72
731;
74__END__
75
76=head1 NAME
77
78XS::APItest - Test the perl C API
79
80=head1 SYNOPSIS
81
82 use XS::APItest;
83 print_double(4);
84
85=head1 ABSTRACT
86
87This module tests the perl C API. Currently tests that C<printf>
88works correctly.
89
90=head1 DESCRIPTION
91
92This module can be used to check that the perl C API is behaving
93correctly. This module provides test functions and an associated
94test script that verifies the output.
95
96This module is not meant to be installed.
97
98=head2 EXPORT
99
100Exports all the test functions:
101
102=over 4
103
104=item B<print_double>
105
106Test that a double-precision floating point number is formatted
107correctly by C<printf>.
108
109 print_double( $val );
110
111Output is sent to STDOUT.
112
113=item B<print_long_double>
114
115Test that a C<long double> is formatted correctly by
116C<printf>. Takes no arguments - the test value is hard-wired
117into the function (as "7").
118
119 print_long_double();
120
121Output is sent to STDOUT.
122
123=item B<have_long_double>
124
125Determine whether a C<long double> is supported by Perl. This should
126be used to determine whether to test C<print_long_double>.
127
128 print_long_double() if have_long_double;
129
130=item B<print_nv>
131
132Test that an C<NV> is formatted correctly by
133C<printf>.
134
135 print_nv( $val );
136
137Output is sent to STDOUT.
138
139=item B<print_iv>
140
141Test that an C<IV> is formatted correctly by
142C<printf>.
143
144 print_iv( $val );
145
146Output is sent to STDOUT.
147
148=item B<print_uv>
149
150Test that an C<UV> is formatted correctly by
151C<printf>.
152
153 print_uv( $val );
154
155Output is sent to STDOUT.
156
157=item B<print_int>
158
159Test that an C<int> is formatted correctly by
160C<printf>.
161
162 print_int( $val );
163
164Output is sent to STDOUT.
165
166=item B<print_long>
167
168Test that an C<long> is formatted correctly by
169C<printf>.
170
171 print_long( $val );
172
173Output is sent to STDOUT.
174
175=item B<print_float>
176
177Test that a single-precision floating point number is formatted
178correctly by C<printf>.
179
180 print_float( $val );
181
182Output is sent to STDOUT.
183
d1f347d7
DM
184=item B<call_sv>, B<call_pv>, B<call_method>
185
186These exercise the C calls of the same names. Everything after the flags
187arg is passed as the the args to the called function. They return whatever
188the C function itself pushed onto the stack, plus the return value from
189the function; for example
190
191 call_sv( sub { @_, 'c' }, G_ARRAY, 'a', 'b'); # returns 'a', 'b', 'c', 3
192 call_sv( sub { @_ }, G_SCALAR, 'a', 'b'); # returns 'b', 1
193
194=item B<eval_sv>
195
3c4b39be 196Evaluates the passed SV. Result handling is done the same as for
d1f347d7
DM
197C<call_sv()> etc.
198
199=item B<eval_pv>
200
3c4b39be 201Exercises the C function of the same name in scalar context. Returns the
d1f347d7
DM
202same SV that the C function returns.
203
204=item B<require_pv>
205
3c4b39be 206Exercises the C function of the same name. Returns nothing.
d1f347d7 207
3e61d65a
JH
208=back
209
210=head1 SEE ALSO
211
212L<XS::Typemap>, L<perlapi>.
213
214=head1 AUTHORS
215
216Tim Jenness, E<lt>t.jenness@jach.hawaii.eduE<gt>,
217Christian Soeller, E<lt>csoelle@mph.auckland.ac.nzE<gt>,
218Hugo van der Sanden E<lt>hv@crypt.compulink.co.ukE<gt>
219
220=head1 COPYRIGHT AND LICENSE
221
d1f347d7 222Copyright (C) 2002,2004 Tim Jenness, Christian Soeller, Hugo van der Sanden.
3e61d65a
JH
223All Rights Reserved.
224
225This library is free software; you can redistribute it and/or modify
226it under the same terms as Perl itself.
227
228=cut