Separate POD file and ExtUtils::ParseXS::Utilities
authorSteffen Mueller <smueller@cpan.org>
Sun, 6 Feb 2011 10:19:58 +0000 (11:19 +0100)
committerSteffen Mueller <smueller@cpan.org>
Tue, 12 Jul 2011 18:53:49 +0000 (20:53 +0200)
Create separate file to hold POD and introduce
ExtUtils::ParseXS::Utilities to hold non-object-oriented functions
refactored out of ExtUtils::ParseXS; first instance:
standard_typemap_locations().

MANIFEST
dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pm
dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pod [new file with mode: 0644]
dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm [new file with mode: 0644]

index a468639..0faadee 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -2973,6 +2973,8 @@ dist/ExtUtils-Manifest/lib/ExtUtils/MANIFEST.SKIP         The default MANIFEST.SKIP
 dist/ExtUtils-Manifest/t/Manifest.t                            See if ExtUtils::Manifest works
 dist/ExtUtils-ParseXS/Changes                  ExtUtils::ParseXS change log
 dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pm  converts Perl XS code into C code
+dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pod ExtUtils::ParseXS documentation
+dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm        ExtUtils::ParseXS guts
 dist/ExtUtils-ParseXS/lib/ExtUtils/xsubpp      External subroutine preprocessor
 dist/ExtUtils-ParseXS/t/001-basic.t            See if ExtUtils::ParseXS works
 dist/ExtUtils-ParseXS/t/002-more.t             Extended ExtUtils::ParseXS testing
index 12f8a09..076ee1e 100644 (file)
@@ -7,6 +7,9 @@ use Exporter;
 use File::Basename;
 use File::Spec;
 use Symbol;
+use ExtUtils::ParseXS::Utilities qw(
+  standard_typemap_locations
+);
 
 our (@ISA, @EXPORT_OK, $VERSION);
 @ISA = qw(Exporter);
@@ -139,7 +142,7 @@ sub process_file {
     die "Can't find $typemap in $pwd\n" unless -r $typemap;
   }
 
-  push @tm, standard_typemap_locations();
+  push @tm, standard_typemap_locations( \@INC );
 
   foreach my $typemap (@tm) {
     next unless -f $typemap;
@@ -1087,24 +1090,6 @@ EOF
 
 sub errors { $errors }
 
-sub standard_typemap_locations {
-  # Add all the default typemap locations to the search path
-  my @tm = qw(typemap);
-
-  my $updir = File::Spec->updir;
-  foreach my $dir (File::Spec->catdir(($updir) x 1), File::Spec->catdir(($updir) x 2),
-           File::Spec->catdir(($updir) x 3), File::Spec->catdir(($updir) x 4)) {
-
-    unshift @tm, File::Spec->catfile($dir, 'typemap');
-    unshift @tm, File::Spec->catfile($dir, lib => ExtUtils => 'typemap');
-  }
-  foreach my $dir (@INC) {
-    my $file = File::Spec->catfile($dir, ExtUtils => 'typemap');
-    unshift @tm, $file if -e $file;
-  }
-  return @tm;
-}
-
 sub TrimWhitespace {
   $_[0] =~ s/^\s+|\s+$//go;
 }
@@ -2057,155 +2042,3 @@ sub end_marker {
 1;
 __END__
 
-=head1 NAME
-
-ExtUtils::ParseXS - converts Perl XS code into C code
-
-=head1 SYNOPSIS
-
-  use ExtUtils::ParseXS qw(process_file);
-
-  process_file( filename => 'foo.xs' );
-
-  process_file( filename => 'foo.xs',
-                output => 'bar.c',
-                'C++' => 1,
-                typemap => 'path/to/typemap',
-                hiertype => 1,
-                except => 1,
-                prototypes => 1,
-                versioncheck => 1,
-                linenumbers => 1,
-                optimize => 1,
-                prototypes => 1,
-              );
-=head1 DESCRIPTION
-
-C<ExtUtils::ParseXS> will compile XS code into C code by embedding the constructs
-necessary to let C functions manipulate Perl values and creates the glue
-necessary to let Perl access those functions.  The compiler uses typemaps to
-determine how to map C function parameters and variables to Perl values.
-
-The compiler will search for typemap files called I<typemap>.  It will use
-the following search path to find default typemaps, with the rightmost
-typemap taking precedence.
-
-    ../../../typemap:../../typemap:../typemap:typemap
-
-=head1 EXPORT
-
-None by default.  C<process_file()> may be exported upon request.
-
-
-=head1 FUNCTIONS
-
-=over 4
-
-=item process_xs()
-
-This function processes an XS file and sends output to a C file.
-Named parameters control how the processing is done.  The following
-parameters are accepted:
-
-=over 4
-
-=item B<C++>
-
-Adds C<extern "C"> to the C code.  Default is false.
-
-=item B<hiertype>
-
-Retains C<::> in type names so that C++ hierachical types can be
-mapped.  Default is false.
-
-=item B<except>
-
-Adds exception handling stubs to the C code.  Default is false.
-
-=item B<typemap>
-
-Indicates that a user-supplied typemap should take precedence over the
-default typemaps.  A single typemap may be specified as a string, or
-multiple typemaps can be specified in an array reference, with the
-last typemap having the highest precedence.
-
-=item B<prototypes>
-
-Generates prototype code for all xsubs.  Default is false.
-
-=item B<versioncheck>
-
-Makes sure at run time that the object file (derived from the C<.xs>
-file) and the C<.pm> files have the same version number.  Default is
-true.
-
-=item B<linenumbers>
-
-Adds C<#line> directives to the C output so error messages will look
-like they came from the original XS file.  Default is true.
-
-=item B<optimize>
-
-Enables certain optimizations.  The only optimization that is currently
-affected is the use of I<target>s by the output C code (see L<perlguts>).
-Not optimizing may significantly slow down the generated code, but this is the way
-B<xsubpp> of 5.005 and earlier operated.  Default is to optimize.
-
-=item B<inout>
-
-Enable recognition of C<IN>, C<OUT_LIST> and C<INOUT_LIST>
-declarations.  Default is true.
-
-=item B<argtypes>
-
-Enable recognition of ANSI-like descriptions of function signature.
-Default is true.
-
-=item B<s>
-
-I have no clue what this does.  Strips function prefixes?
-
-=back
-
-=item errors()
-
-This function returns the number of [a certain kind of] errors
-encountered during processing of the XS file.
-
-=back
-
-=head1 AUTHOR
-
-Based on xsubpp code, written by Larry Wall.
-
-Maintained by:
-
-=over 4
-
-=item *
-
-Ken Williams, <ken@mathforum.org>
-
-=item *
-
-David Golden, <dagolden@cpan.org>
-
-=back
-
-=head1 COPYRIGHT
-
-Copyright 2002-2009 by Ken Williams, David Golden and other contributors.  All
-rights reserved.
-
-This library is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-Based on the ExtUtils::xsubpp code by Larry Wall and the Perl 5
-Porters, which was released under the same license terms.
-
-=head1 SEE ALSO
-
-L<perl>, ExtUtils::xsubpp, ExtUtils::MakeMaker, L<perlxs>, L<perlxstut>.
-
-=cut
-
diff --git a/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pod b/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pod
new file mode 100644 (file)
index 0000000..dd98103
--- /dev/null
@@ -0,0 +1,197 @@
+=head1 NAME
+
+ExtUtils::ParseXS - converts Perl XS code into C code
+
+=head1 SYNOPSIS
+
+  use ExtUtils::ParseXS qw(process_file);
+
+  process_file( filename => 'foo.xs' );
+
+  process_file( filename => 'foo.xs',
+                output => 'bar.c',
+                'C++' => 1,
+                typemap => 'path/to/typemap',
+                hiertype => 1,
+                except => 1,
+                prototypes => 1,
+                versioncheck => 1,
+                linenumbers => 1,
+                optimize => 1,
+                prototypes => 1,
+              );
+
+=head1 DESCRIPTION
+
+C<ExtUtils::ParseXS> will compile XS code into C code by embedding the constructs
+necessary to let C functions manipulate Perl values and creates the glue
+necessary to let Perl access those functions.  The compiler uses typemaps to
+determine how to map C function parameters and variables to Perl values.
+
+The compiler will search for typemap files called I<typemap>.  It will use
+the following search path to find default typemaps, with the rightmost
+typemap taking precedence.
+
+    ../../../typemap:../../typemap:../typemap:typemap
+
+=head1 EXPORT
+
+None by default.  C<process_file()> may be exported upon request.
+
+=head1 FUNCTIONS
+
+=over 4
+
+=item process_xs()
+
+This function processes an XS file and sends output to a C file.
+Named parameters control how the processing is done.  The following
+parameters are accepted:
+
+=over 4
+
+=item B<C++>
+
+Adds C<extern "C"> to the C code.  Default is false.
+
+=item B<hiertype>
+
+Retains C<::> in type names so that C++ hierachical types can be
+mapped.  Default is false.
+
+=item B<except>
+
+Adds exception handling stubs to the C code.  Default is false.
+
+=item B<typemap>
+
+Indicates that a user-supplied typemap should take precedence over the
+default typemaps.  A single typemap may be specified as a string, or
+multiple typemaps can be specified in an array reference, with the
+last typemap having the highest precedence.
+
+=item B<prototypes>
+
+Generates prototype code for all xsubs.  Default is false.
+
+=item B<versioncheck>
+
+Makes sure at run time that the object file (derived from the C<.xs>
+file) and the C<.pm> files have the same version number.  Default is
+true.
+
+=item B<linenumbers>
+
+Adds C<#line> directives to the C output so error messages will look
+like they came from the original XS file.  Default is true.
+
+=item B<optimize>
+
+Enables certain optimizations.  The only optimization that is currently
+affected is the use of I<target>s by the output C code (see L<perlguts>).
+Not optimizing may significantly slow down the generated code, but this is the way
+B<xsubpp> of 5.005 and earlier operated.  Default is to optimize.
+
+=item B<inout>
+
+Enable recognition of C<IN>, C<OUT_LIST> and C<INOUT_LIST>
+declarations.  Default is true.
+
+=item B<argtypes>
+
+Enable recognition of ANSI-like descriptions of function signature.
+Default is true.
+
+=item B<s>
+
+I have no clue what this does.  Strips function prefixes?
+
+=back
+
+=item errors()
+
+This function returns the number of [a certain kind of] errors
+encountered during processing of the XS file.
+
+=back
+
+=head1 INTERNAL SUBROUTINES
+
+The following functions are not considered to be part of the public interface.
+They are documented here for the benefit of future maintainers of this module.
+
+=head2 C<standard_typemap_locations()>
+
+=over 4
+
+=item * Purpose
+
+Provide a list of directories in which to search for F<typemap> files.  The
+directories appear in this list in lowest-to-highest priority.  The lowest
+priority directories are directories named F<ExtUtils> which are
+subdirectories of directories found in C<@INC> -- provided a file named
+F<typemap> actually exists in such a directory.  The highest priority
+directory is the current directory.  The second highest priority directory is
+the parent of the current directory.  The third highest priority directory is
+a directory called F<lib/ExtUtils> underneath the parent directory. And so
+forth for three more upward levels.  This results in a list like this:
+
+  '/usr/local/lib/perl5/5.10.1/ExtUtils/typemap',
+  '../../../../lib/ExtUtils/typemap',
+  '../../../../typemap',
+  '../../../lib/ExtUtils/typemap',
+  '../../../typemap',
+  '../../lib/ExtUtils/typemap',
+  '../../typemap',
+  '../lib/ExtUtils/typemap',
+  '../typemap',
+  'typemap'
+
+=item * Arguments
+
+  my @stl = standard_typemap_locations( \@INC );
+
+Reference to C<@INC>.
+
+=item * Return Value
+
+Array holding list of directories to be searched for F<typemap> files.
+
+=back
+
+=head1 AUTHOR
+
+Based on xsubpp code, written by Larry Wall.
+
+Maintained by:
+
+=over 4
+
+=item *
+
+Ken Williams, <ken@mathforum.org>
+
+=item *
+
+David Golden, <dagolden@cpan.org>
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2002-2009 by Ken Williams, David Golden and other contributors.  All
+rights reserved.
+
+This library is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+Based on the ExtUtils::xsubpp code by Larry Wall and the Perl 5
+Porters, which was released under the same license terms.
+
+=head1 SEE ALSO
+
+L<perl>, ExtUtils::xsubpp, ExtUtils::MakeMaker, L<perlxs>, L<perlxstut>.
+
+=cut
+
+
diff --git a/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm b/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm
new file mode 100644 (file)
index 0000000..ff00a7a
--- /dev/null
@@ -0,0 +1,30 @@
+package ExtUtils::ParseXS::Utilities;
+use strict;
+use warnings;
+use Exporter;
+our (@ISA, @EXPORT_OK);
+@ISA = qw(Exporter);
+@EXPORT_OK = qw(
+  standard_typemap_locations
+);
+
+sub standard_typemap_locations {
+  my $include_ref = shift;
+  # Add all the default typemap locations to the search path
+  my @tm = qw(typemap);
+
+  my $updir = File::Spec->updir;
+  foreach my $dir (File::Spec->catdir(($updir) x 1), File::Spec->catdir(($updir) x 2),
+           File::Spec->catdir(($updir) x 3), File::Spec->catdir(($updir) x 4)) {
+
+    unshift @tm, File::Spec->catfile($dir, 'typemap');
+    unshift @tm, File::Spec->catfile($dir, lib => ExtUtils => 'typemap');
+  }
+  foreach my $dir (@{ $include_ref}) {
+    my $file = File::Spec->catfile($dir, ExtUtils => 'typemap');
+    unshift @tm, $file if -e $file;
+  }
+  return @tm;
+}
+
+1;