Move POD for internal sub from ParseXS.pod to Utilities.pm

Create file to test standard_typemap_locations().
Update MANIFEST.

diff --git a/MANIFEST b/MANIFEST
index 0faadee..9864df6 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -2979,6 +2979,7 @@ 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
 dist/ExtUtils-ParseXS/t/003-usage.t            ExtUtils::ParseXS tests
+dist/ExtUtils-ParseXS/t/101-standard_typemap_locations.t       ExtUtils::ParseXS tests
 dist/ExtUtils-ParseXS/t/lib/IncludeTester.pm   ExtUtils::ParseXS testing utility
 dist/ExtUtils-ParseXS/t/typemap                        Standard typemap for controlled testing
 dist/ExtUtils-ParseXS/t/XSInclude.xsh          Test file for ExtUtils::ParseXS tests

diff --git a/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pod b/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pod
index dd98103..f5ffb57 100644 (file)
--- a/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pod
+++ b/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pod
@@ -115,50 +115,6 @@ 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.

diff --git a/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm b/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm
index ff00a7a..b68ddd8 100644 (file)
--- a/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm
+++ b/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm
@@ -2,21 +2,104 @@ package ExtUtils::ParseXS::Utilities;
 use strict;
 use warnings;
 use Exporter;
+use File::Spec;
 our (@ISA, @EXPORT_OK);
 @ISA = qw(Exporter);
 @EXPORT_OK = qw(
   standard_typemap_locations
 );
 
+=head1 NAME
+
+ExtUtils::ParseXS::Utilities - Subroutines used with ExtUtils::ParseXS
+
+=head1 SYNOPSIS
+
+  use ExtUtils::ParseXS::Utilities qw(
+    standard_typemap_locations
+  );
+
+=head1 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 filepaths where F<typemap> files may be found.  The
+filepaths -- relative paths to files (not just directory paths) -- appear in this list in lowest-to-highest priority.
+
+The highest priority is to look in the current directory.  
+
+  'typemap'
+
+The second and third highest priorities are to look in the parent of the
+current directory and a directory called F<lib/ExtUtils> underneath the parent
+directory.
+
+  '../typemap',
+  '../lib/ExtUtils/typemap',
+
+The fourth through ninth highest priorities are to look in the corresponding
+grandparent, great-grandparent and great-great-grandparent directories.
+
+  '../../typemap',
+  '../../lib/ExtUtils/typemap',
+  '../../../typemap',
+  '../../../lib/ExtUtils/typemap',
+  '../../../../typemap',
+  '../../../../lib/ExtUtils/typemap',
+
+The tenth and subsequent priorities are to look in directories named
+F<ExtUtils> which are subdirectories of directories found in C<@INC> --
+I<provided> a file named F<typemap> actually exists in such a directory.
+Example:
+
+  '/usr/local/lib/perl5/5.10.1/ExtUtils/typemap',
+
+However, these filepaths appear in the list returned by
+C<standard_typemap_locations()> in reverse order, I<i.e.>, lowest-to-highest.
+
+  '/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
+
+=cut
+
 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)) {
-
+  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');
   }

diff --git a/dist/ExtUtils-ParseXS/t/101-standard_typemap_locations.t b/dist/ExtUtils-ParseXS/t/101-standard_typemap_locations.t
new file mode 100644 (file)
index 0000000..e9e7e59
--- /dev/null
+++ b/dist/ExtUtils-ParseXS/t/101-standard_typemap_locations.t
@@ -0,0 +1,25 @@
+#!/usr/bin/perl
+use strict;
+use warnings;
+use Test::More tests =>  3;
+use lib qw( lib );
+use ExtUtils::ParseXS::Utilities qw(
+  standard_typemap_locations
+);
+
+{
+    local @INC = @INC;
+    my @stl = standard_typemap_locations( \@INC );
+    ok( @stl >= 9, "At least 9 entries in typemap locations list" );
+    is( $stl[$#stl], 'typemap',
+        "Last element is typemap in current directory");
+    SKIP: {
+        skip "No lib/ExtUtils/ directories under directories in \@INC",
+        1
+        unless @stl > 9;
+        ok( -f $stl[-10],
+            "At least one typemap file exists underneath \@INC directories"
+        );
+    }
+}
+