This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Revise some of the placements into EU::PXS::Constants.
[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
1d40e528 10 trim_whitespace
73e91d5a 11 tidy_type
c1e43162 12 C_string
a65c06db
SM
13);
14
f3aadd09
SM
15=head1 NAME
16
17ExtUtils::ParseXS::Utilities - Subroutines used with ExtUtils::ParseXS
18
19=head1 SYNOPSIS
20
21 use ExtUtils::ParseXS::Utilities qw(
22 standard_typemap_locations
1d40e528 23 trim_whitespace
73e91d5a 24 tidy_type
f3aadd09
SM
25 );
26
27=head1 SUBROUTINES
28
29The following functions are not considered to be part of the public interface.
30They are documented here for the benefit of future maintainers of this module.
31
32=head2 C<standard_typemap_locations()>
33
34=over 4
35
36=item * Purpose
37
38Provide a list of filepaths where F<typemap> files may be found. The
39filepaths -- relative paths to files (not just directory paths) -- appear in this list in lowest-to-highest priority.
40
41The highest priority is to look in the current directory.
42
43 'typemap'
44
45The second and third highest priorities are to look in the parent of the
46current directory and a directory called F<lib/ExtUtils> underneath the parent
47directory.
48
49 '../typemap',
50 '../lib/ExtUtils/typemap',
51
52The fourth through ninth highest priorities are to look in the corresponding
53grandparent, great-grandparent and great-great-grandparent directories.
54
55 '../../typemap',
56 '../../lib/ExtUtils/typemap',
57 '../../../typemap',
58 '../../../lib/ExtUtils/typemap',
59 '../../../../typemap',
60 '../../../../lib/ExtUtils/typemap',
61
62The tenth and subsequent priorities are to look in directories named
63F<ExtUtils> which are subdirectories of directories found in C<@INC> --
64I<provided> a file named F<typemap> actually exists in such a directory.
65Example:
66
67 '/usr/local/lib/perl5/5.10.1/ExtUtils/typemap',
68
69However, these filepaths appear in the list returned by
70C<standard_typemap_locations()> in reverse order, I<i.e.>, lowest-to-highest.
71
72 '/usr/local/lib/perl5/5.10.1/ExtUtils/typemap',
73 '../../../../lib/ExtUtils/typemap',
74 '../../../../typemap',
75 '../../../lib/ExtUtils/typemap',
76 '../../../typemap',
77 '../../lib/ExtUtils/typemap',
78 '../../typemap',
79 '../lib/ExtUtils/typemap',
80 '../typemap',
81 'typemap'
82
83=item * Arguments
84
85 my @stl = standard_typemap_locations( \@INC );
86
87Reference to C<@INC>.
88
89=item * Return Value
90
91Array holding list of directories to be searched for F<typemap> files.
92
93=back
94
95=cut
96
a65c06db
SM
97sub standard_typemap_locations {
98 my $include_ref = shift;
a65c06db
SM
99 my @tm = qw(typemap);
100
f3aadd09
SM
101 my $updir = File::Spec->updir();
102 foreach my $dir (
103 File::Spec->catdir(($updir) x 1),
104 File::Spec->catdir(($updir) x 2),
105 File::Spec->catdir(($updir) x 3),
106 File::Spec->catdir(($updir) x 4),
107 ) {
a65c06db
SM
108 unshift @tm, File::Spec->catfile($dir, 'typemap');
109 unshift @tm, File::Spec->catfile($dir, lib => ExtUtils => 'typemap');
110 }
111 foreach my $dir (@{ $include_ref}) {
112 my $file = File::Spec->catfile($dir, ExtUtils => 'typemap');
113 unshift @tm, $file if -e $file;
114 }
115 return @tm;
116}
117
1d40e528
JK
118=head2 C<trim_whitespace()>
119
120=over 4
121
122=item * Purpose
123
124Perform an in-place trimming of leading and trailing whitespace from the
125first argument provided to the function.
126
127=item * Argument
128
129 trim_whitespace($arg);
130
131=item * Return Value
132
133None. Remember: this is an I<in-place> modification of the argument.
134
135=back
136
137=cut
138
139sub trim_whitespace {
140 $_[0] =~ s/^\s+|\s+$//go;
141}
142
73e91d5a
JK
143=head2 C<tidy_type()>
144
145=over 4
146
147=item * Purpose
148
149Rationalize any asterisks (C<*>) by joining them into bunches, removing
150interior whitespace, then trimming leading and trailing whitespace.
151
152=item * Arguments
153
154 ($ret_type) = tidy_type($_);
155
156String to be cleaned up.
157
158=item * Return Value
159
160String cleaned up.
161
162=back
163
164=cut
165
166sub tidy_type {
167 local ($_) = @_;
168
169 # rationalise any '*' by joining them into bunches and removing whitespace
170 s#\s*(\*+)\s*#$1#g;
171 s#(\*+)# $1 #g;
172
173 # change multiple whitespace into a single space
174 s/\s+/ /g;
175
176 # trim leading & trailing whitespace
177 trim_whitespace($_);
178
179 $_;
180}
181
c1e43162
JK
182=head2 C<C_string()>
183
184=over 4
185
186=item * Purpose
187
188Escape backslashes (C<\>) in prototype strings.
189
190=item * Arguments
191
192 $ProtoThisXSUB = C_string($_);
193
194String needing escaping.
195
196=item * Return Value
197
198Properly escaped string.
199
200=back
201
202=cut
203
204sub C_string {
205 my($string) = @_;
206
207 $string =~ s[\\][\\\\]g;
208 $string;
209}
210
a65c06db 2111;