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