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