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.07';
  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