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