This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Move POD for internal sub from ParseXS.pod to Utilities.pm
[perl5.git] / dist / ExtUtils-ParseXS / lib / ExtUtils / ParseXS / Utilities.pm
CommitLineData
a65c06db
SM
1package ExtUtils::ParseXS::Utilities;
2use strict;
3use warnings;
4use Exporter;
f3aadd09 5use File::Spec;
a65c06db
SM
6our (@ISA, @EXPORT_OK);
7@ISA = qw(Exporter);
8@EXPORT_OK = qw(
9 standard_typemap_locations
10);
11
f3aadd09
SM
12=head1 NAME
13
14ExtUtils::ParseXS::Utilities - Subroutines used with ExtUtils::ParseXS
15
16=head1 SYNOPSIS
17
18 use ExtUtils::ParseXS::Utilities qw(
19 standard_typemap_locations
20 );
21
22=head1 SUBROUTINES
23
24The following functions are not considered to be part of the public interface.
25They are documented here for the benefit of future maintainers of this module.
26
27=head2 C<standard_typemap_locations()>
28
29=over 4
30
31=item * Purpose
32
33Provide a list of filepaths where F<typemap> files may be found. The
34filepaths -- relative paths to files (not just directory paths) -- appear in this list in lowest-to-highest priority.
35
36The highest priority is to look in the current directory.
37
38 'typemap'
39
40The second and third highest priorities are to look in the parent of the
41current directory and a directory called F<lib/ExtUtils> underneath the parent
42directory.
43
44 '../typemap',
45 '../lib/ExtUtils/typemap',
46
47The fourth through ninth highest priorities are to look in the corresponding
48grandparent, great-grandparent and great-great-grandparent directories.
49
50 '../../typemap',
51 '../../lib/ExtUtils/typemap',
52 '../../../typemap',
53 '../../../lib/ExtUtils/typemap',
54 '../../../../typemap',
55 '../../../../lib/ExtUtils/typemap',
56
57The tenth and subsequent priorities are to look in directories named
58F<ExtUtils> which are subdirectories of directories found in C<@INC> --
59I<provided> a file named F<typemap> actually exists in such a directory.
60Example:
61
62 '/usr/local/lib/perl5/5.10.1/ExtUtils/typemap',
63
64However, these filepaths appear in the list returned by
65C<standard_typemap_locations()> in reverse order, I<i.e.>, lowest-to-highest.
66
67 '/usr/local/lib/perl5/5.10.1/ExtUtils/typemap',
68 '../../../../lib/ExtUtils/typemap',
69 '../../../../typemap',
70 '../../../lib/ExtUtils/typemap',
71 '../../../typemap',
72 '../../lib/ExtUtils/typemap',
73 '../../typemap',
74 '../lib/ExtUtils/typemap',
75 '../typemap',
76 'typemap'
77
78=item * Arguments
79
80 my @stl = standard_typemap_locations( \@INC );
81
82Reference to C<@INC>.
83
84=item * Return Value
85
86Array holding list of directories to be searched for F<typemap> files.
87
88=back
89
90=cut
91
a65c06db
SM
92sub standard_typemap_locations {
93 my $include_ref = shift;
a65c06db
SM
94 my @tm = qw(typemap);
95
f3aadd09
SM
96 my $updir = File::Spec->updir();
97 foreach my $dir (
98 File::Spec->catdir(($updir) x 1),
99 File::Spec->catdir(($updir) x 2),
100 File::Spec->catdir(($updir) x 3),
101 File::Spec->catdir(($updir) x 4),
102 ) {
a65c06db
SM
103 unshift @tm, File::Spec->catfile($dir, 'typemap');
104 unshift @tm, File::Spec->catfile($dir, lib => ExtUtils => 'typemap');
105 }
106 foreach my $dir (@{ $include_ref}) {
107 my $file = File::Spec->catfile($dir, ExtUtils => 'typemap');
108 unshift @tm, $file if -e $file;
109 }
110 return @tm;
111}
112
1131;