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