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