This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Eliminate PL_* accessor functions under ithreads.
[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
01146bad 26 DPeek utf16_to_utf8 utf16_to_utf8_reversed my_exit
d97c33b5 27 sv_count
3e61d65a
JH
28);
29
829afbf7 30our $VERSION = '0.21';
84ac5fd7
NC
31
32use vars '$WARNINGS_ON_BOOTSTRAP';
0932863f
NC
33use vars map "\$${_}_called_PP", qw(BEGIN UNITCHECK CHECK INIT END);
34
9568a123
NC
35BEGIN {
36 # This is arguably a hack, but it disposes of the UNITCHECK block without
37 # needing to preprocess the source code
38 if ($] < 5.009) {
39 eval 'sub UNITCHECK (&) {}; 1' or die $@;
40 }
41}
42
0932863f
NC
43# Do these here to verify that XS code and Perl code get called at the same
44# times
45BEGIN {
46 $BEGIN_called_PP++;
47}
48UNITCHECK {
49 $UNITCHECK_called_PP++;
9568a123 50};
0932863f
NC
51{
52 # Need $W false by default, as some tests run under -w, and under -w we
53 # can get warnings about "Too late to run CHECK" block (and INIT block)
54 no warnings 'void';
55 CHECK {
56 $CHECK_called_PP++;
57 }
58 INIT {
59 $INIT_called_PP++;
60 }
61}
62END {
63 $END_called_PP++;
64}
65
84ac5fd7
NC
66if ($WARNINGS_ON_BOOTSTRAP) {
67 bootstrap XS::APItest $VERSION;
68} else {
0932863f 69 # More CHECK and INIT blocks that could warn:
84ac5fd7 70 local $^W;
84ac5fd7
NC
71 bootstrap XS::APItest $VERSION;
72}
3e61d65a
JH
73
741;
75__END__
76
77=head1 NAME
78
79XS::APItest - Test the perl C API
80
81=head1 SYNOPSIS
82
83 use XS::APItest;
84 print_double(4);
85
86=head1 ABSTRACT
87
d97c33b5
DM
88This module tests the perl C API. Also exposes various bit of the perl
89internals for the use of core test scripts.
3e61d65a
JH
90
91=head1 DESCRIPTION
92
93This module can be used to check that the perl C API is behaving
94correctly. This module provides test functions and an associated
95test script that verifies the output.
96
97This module is not meant to be installed.
98
99=head2 EXPORT
100
101Exports all the test functions:
102
103=over 4
104
105=item B<print_double>
106
107Test that a double-precision floating point number is formatted
108correctly by C<printf>.
109
110 print_double( $val );
111
112Output is sent to STDOUT.
113
114=item B<print_long_double>
115
116Test that a C<long double> is formatted correctly by
117C<printf>. Takes no arguments - the test value is hard-wired
118into the function (as "7").
119
120 print_long_double();
121
122Output is sent to STDOUT.
123
124=item B<have_long_double>
125
126Determine whether a C<long double> is supported by Perl. This should
127be used to determine whether to test C<print_long_double>.
128
129 print_long_double() if have_long_double;
130
131=item B<print_nv>
132
133Test that an C<NV> is formatted correctly by
134C<printf>.
135
136 print_nv( $val );
137
138Output is sent to STDOUT.
139
140=item B<print_iv>
141
142Test that an C<IV> is formatted correctly by
143C<printf>.
144
145 print_iv( $val );
146
147Output is sent to STDOUT.
148
149=item B<print_uv>
150
151Test that an C<UV> is formatted correctly by
152C<printf>.
153
154 print_uv( $val );
155
156Output is sent to STDOUT.
157
158=item B<print_int>
159
160Test that an C<int> is formatted correctly by
161C<printf>.
162
163 print_int( $val );
164
165Output is sent to STDOUT.
166
167=item B<print_long>
168
169Test that an C<long> is formatted correctly by
170C<printf>.
171
172 print_long( $val );
173
174Output is sent to STDOUT.
175
176=item B<print_float>
177
178Test that a single-precision floating point number is formatted
179correctly by C<printf>.
180
181 print_float( $val );
182
183Output is sent to STDOUT.
184
d1f347d7
DM
185=item B<call_sv>, B<call_pv>, B<call_method>
186
187These exercise the C calls of the same names. Everything after the flags
188arg is passed as the the args to the called function. They return whatever
189the C function itself pushed onto the stack, plus the return value from
190the function; for example
191
192 call_sv( sub { @_, 'c' }, G_ARRAY, 'a', 'b'); # returns 'a', 'b', 'c', 3
193 call_sv( sub { @_ }, G_SCALAR, 'a', 'b'); # returns 'b', 1
194
195=item B<eval_sv>
196
3c4b39be 197Evaluates the passed SV. Result handling is done the same as for
d1f347d7
DM
198C<call_sv()> etc.
199
200=item B<eval_pv>
201
3c4b39be 202Exercises the C function of the same name in scalar context. Returns the
d1f347d7
DM
203same SV that the C function returns.
204
205=item B<require_pv>
206
3c4b39be 207Exercises the C function of the same name. Returns nothing.
d1f347d7 208
3e61d65a
JH
209=back
210
211=head1 SEE ALSO
212
213L<XS::Typemap>, L<perlapi>.
214
215=head1 AUTHORS
216
217Tim Jenness, E<lt>t.jenness@jach.hawaii.eduE<gt>,
218Christian Soeller, E<lt>csoelle@mph.auckland.ac.nzE<gt>,
219Hugo van der Sanden E<lt>hv@crypt.compulink.co.ukE<gt>
220
221=head1 COPYRIGHT AND LICENSE
222
d1f347d7 223Copyright (C) 2002,2004 Tim Jenness, Christian Soeller, Hugo van der Sanden.
3e61d65a
JH
224All Rights Reserved.
225
226This library is free software; you can redistribute it and/or modify
227it under the same terms as Perl itself.
228
229=cut