This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
BEGIN blocks in XS should work. (Given that CHECK, INIT and END all do)
[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
21 G_KEEPERR G_NODEBUG G_METHOD
5d2b1485 22 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
3e61d65a
JH
25);
26
d1f347d7
DM
27# from cop.h
28sub G_SCALAR() { 0 }
29sub G_ARRAY() { 1 }
30sub G_VOID() { 128 }
31sub G_DISCARD() { 2 }
32sub G_EVAL() { 4 }
33sub G_NOARGS() { 8 }
34sub G_KEEPERR() { 16 }
35sub G_NODEBUG() { 32 }
36sub G_METHOD() { 64 }
37
84ac5fd7
NC
38our $VERSION = '0.12';
39
40use vars '$WARNINGS_ON_BOOTSTRAP';
41if ($WARNINGS_ON_BOOTSTRAP) {
42 bootstrap XS::APItest $VERSION;
43} else {
44 local $^W;
45 # Need $W false by default, as some tests run under -w, and under -w we
46 # can get warnings about "Too late to run CHECK" block (and INIT block)
47 bootstrap XS::APItest $VERSION;
48}
3e61d65a
JH
49
501;
51__END__
52
53=head1 NAME
54
55XS::APItest - Test the perl C API
56
57=head1 SYNOPSIS
58
59 use XS::APItest;
60 print_double(4);
61
62=head1 ABSTRACT
63
64This module tests the perl C API. Currently tests that C<printf>
65works correctly.
66
67=head1 DESCRIPTION
68
69This module can be used to check that the perl C API is behaving
70correctly. This module provides test functions and an associated
71test script that verifies the output.
72
73This module is not meant to be installed.
74
75=head2 EXPORT
76
77Exports all the test functions:
78
79=over 4
80
81=item B<print_double>
82
83Test that a double-precision floating point number is formatted
84correctly by C<printf>.
85
86 print_double( $val );
87
88Output is sent to STDOUT.
89
90=item B<print_long_double>
91
92Test that a C<long double> is formatted correctly by
93C<printf>. Takes no arguments - the test value is hard-wired
94into the function (as "7").
95
96 print_long_double();
97
98Output is sent to STDOUT.
99
100=item B<have_long_double>
101
102Determine whether a C<long double> is supported by Perl. This should
103be used to determine whether to test C<print_long_double>.
104
105 print_long_double() if have_long_double;
106
107=item B<print_nv>
108
109Test that an C<NV> is formatted correctly by
110C<printf>.
111
112 print_nv( $val );
113
114Output is sent to STDOUT.
115
116=item B<print_iv>
117
118Test that an C<IV> is formatted correctly by
119C<printf>.
120
121 print_iv( $val );
122
123Output is sent to STDOUT.
124
125=item B<print_uv>
126
127Test that an C<UV> is formatted correctly by
128C<printf>.
129
130 print_uv( $val );
131
132Output is sent to STDOUT.
133
134=item B<print_int>
135
136Test that an C<int> is formatted correctly by
137C<printf>.
138
139 print_int( $val );
140
141Output is sent to STDOUT.
142
143=item B<print_long>
144
145Test that an C<long> is formatted correctly by
146C<printf>.
147
148 print_long( $val );
149
150Output is sent to STDOUT.
151
152=item B<print_float>
153
154Test that a single-precision floating point number is formatted
155correctly by C<printf>.
156
157 print_float( $val );
158
159Output is sent to STDOUT.
160
d1f347d7
DM
161=item B<call_sv>, B<call_pv>, B<call_method>
162
163These exercise the C calls of the same names. Everything after the flags
164arg is passed as the the args to the called function. They return whatever
165the C function itself pushed onto the stack, plus the return value from
166the function; for example
167
168 call_sv( sub { @_, 'c' }, G_ARRAY, 'a', 'b'); # returns 'a', 'b', 'c', 3
169 call_sv( sub { @_ }, G_SCALAR, 'a', 'b'); # returns 'b', 1
170
171=item B<eval_sv>
172
3c4b39be 173Evaluates the passed SV. Result handling is done the same as for
d1f347d7
DM
174C<call_sv()> etc.
175
176=item B<eval_pv>
177
3c4b39be 178Exercises the C function of the same name in scalar context. Returns the
d1f347d7
DM
179same SV that the C function returns.
180
181=item B<require_pv>
182
3c4b39be 183Exercises the C function of the same name. Returns nothing.
d1f347d7 184
3e61d65a
JH
185=back
186
187=head1 SEE ALSO
188
189L<XS::Typemap>, L<perlapi>.
190
191=head1 AUTHORS
192
193Tim Jenness, E<lt>t.jenness@jach.hawaii.eduE<gt>,
194Christian Soeller, E<lt>csoelle@mph.auckland.ac.nzE<gt>,
195Hugo van der Sanden E<lt>hv@crypt.compulink.co.ukE<gt>
196
197=head1 COPYRIGHT AND LICENSE
198
d1f347d7 199Copyright (C) 2002,2004 Tim Jenness, Christian Soeller, Hugo van der Sanden.
3e61d65a
JH
200All Rights Reserved.
201
202This library is free software; you can redistribute it and/or modify
203it under the same terms as Perl itself.
204
205=cut