1ExtUtils::ParseXS::UtilUisteiresC(o3n)tributed Perl DocuEmxetnUttaitliso:n:ParseXS::Utilities(3)
2
3
4
6 ExtUtils::ParseXS::Utilities - Subroutines used with ExtUtils::ParseXS
7
9 use ExtUtils::ParseXS::Utilities qw(
10 standard_typemap_locations
11 trim_whitespace
12 C_string
13 valid_proto_string
14 process_typemaps
15 map_type
16 standard_XS_defs
17 assign_func_args
18 analyze_preprocessor_statements
19 set_cond
20 Warn
21 blurt
22 death
23 check_conditional_preprocessor_statements
24 escape_file_for_line_directive
25 report_typemap_failure
26 );
27
29 The following functions are not considered to be part of the public
30 interface. They are documented here for the benefit of future
31 maintainers of this module.
32
33 standard_typemap_locations()
34 • Purpose
35
36 Provide a list of filepaths where typemap files may be found. The
37 filepaths -- relative paths to files (not just directory paths) --
38 appear in this list in lowest-to-highest priority.
39
40 The highest priority is to look in the current directory.
41
42 'typemap'
43
44 The second and third highest priorities are to look in the parent
45 of the current directory and a directory called lib/ExtUtils
46 underneath the parent directory.
47
48 '../typemap',
49 '../lib/ExtUtils/typemap',
50
51 The fourth through ninth highest priorities are to look in the
52 corresponding grandparent, great-grandparent and great-great-
53 grandparent directories.
54
55 '../../typemap',
56 '../../lib/ExtUtils/typemap',
57 '../../../typemap',
58 '../../../lib/ExtUtils/typemap',
59 '../../../../typemap',
60 '../../../../lib/ExtUtils/typemap',
61
62 The tenth and subsequent priorities are to look in directories
63 named ExtUtils which are subdirectories of directories found in
64 @INC -- provided a file named typemap actually exists in such a
65 directory. Example:
66
67 '/usr/local/lib/perl5/5.10.1/ExtUtils/typemap',
68
69 However, these filepaths appear in the list returned by
70 standard_typemap_locations() in reverse order, i.e., lowest-to-
71 highest.
72
73 '/usr/local/lib/perl5/5.10.1/ExtUtils/typemap',
74 '../../../../lib/ExtUtils/typemap',
75 '../../../../typemap',
76 '../../../lib/ExtUtils/typemap',
77 '../../../typemap',
78 '../../lib/ExtUtils/typemap',
79 '../../typemap',
80 '../lib/ExtUtils/typemap',
81 '../typemap',
82 'typemap'
83
84 • Arguments
85
86 my @stl = standard_typemap_locations( \@INC );
87
88 Reference to @INC.
89
90 • Return Value
91
92 Array holding list of directories to be searched for typemap files.
93
94 trim_whitespace()
95 • Purpose
96
97 Perform an in-place trimming of leading and trailing whitespace
98 from the first argument provided to the function.
99
100 • Argument
101
102 trim_whitespace($arg);
103
104 • Return Value
105
106 None. Remember: this is an in-place modification of the argument.
107
108 C_string()
109 • Purpose
110
111 Escape backslashes ("\") in prototype strings.
112
113 • Arguments
114
115 $ProtoThisXSUB = C_string($_);
116
117 String needing escaping.
118
119 • Return Value
120
121 Properly escaped string.
122
123 valid_proto_string()
124 • Purpose
125
126 Validate prototype string.
127
128 • Arguments
129
130 String needing checking.
131
132 • Return Value
133
134 Upon success, returns the same string passed as argument.
135
136 Upon failure, returns 0.
137
138 process_typemaps()
139 • Purpose
140
141 Process all typemap files.
142
143 • Arguments
144
145 my $typemaps_object = process_typemaps( $args{typemap}, $pwd );
146
147 List of two elements: "typemap" element from %args; current
148 working directory.
149
150 • Return Value
151
152 Upon success, returns an ExtUtils::Typemaps object.
153
154 map_type()
155 • Purpose
156
157 Performs a mapping at several places inside "PARAGRAPH" loop.
158
159 • Arguments
160
161 $type = map_type($self, $type, $varname);
162
163 List of three arguments.
164
165 • Return Value
166
167 String holding augmented version of second argument.
168
169 standard_XS_defs()
170 • Purpose
171
172 Writes to the ".c" output file certain preprocessor directives and
173 function headers needed in all such files.
174
175 • Arguments
176
177 None.
178
179 • Return Value
180
181 Returns true.
182
183 assign_func_args()
184 • Purpose
185
186 Perform assignment to the "func_args" attribute.
187
188 • Arguments
189
190 $string = assign_func_args($self, $argsref, $class);
191
192 List of three elements. Second is an array reference; third is a
193 string.
194
195 • Return Value
196
197 String.
198
199 analyze_preprocessor_statements()
200 • Purpose
201
202 Within each function inside each Xsub, print to the .c output file
203 certain preprocessor statements.
204
205 • Arguments
206
207 ( $self, $XSS_work_idx, $BootCode_ref ) =
208 analyze_preprocessor_statements(
209 $self, $statement, $XSS_work_idx, $BootCode_ref
210 );
211
212 List of four elements.
213
214 • Return Value
215
216 Modifed values of three of the arguments passed to the function.
217 In particular, the "XSStack" and "InitFileCode" attributes are
218 modified.
219
220 set_cond()
221 • Purpose
222
223 • Arguments
224
225 • Return Value
226
227 current_line_number()
228 • Purpose
229
230 Figures out the current line number in the XS file.
231
232 • Arguments
233
234 $self
235
236 • Return Value
237
238 The current line number.
239
240 Warn()
241 • Purpose
242
243 Print warnings with line number details at the end.
244
245 • Arguments
246
247 List of text to output.
248
249 • Return Value
250
251 None.
252
253 WarnHint()
254 • Purpose
255
256 Prints warning with line number details. The last argument is
257 assumed to be a hint string.
258
259 • Arguments
260
261 List of strings to warn, followed by one argument representing a
262 hint. If that argument is defined then it will be split on
263 newlines and output line by line after the main warning.
264
265 • Return Value
266
267 None.
268
269 _MsgHint()
270 • Purpose
271
272 Constructs an exception message with line number details. The last
273 argument is assumed to be a hint string.
274
275 • Arguments
276
277 List of strings to warn, followed by one argument representing a
278 hint. If that argument is defined then it will be split on
279 newlines and concatenated line by line (parenthesized) after the
280 main message.
281
282 • Return Value
283
284 The constructed string.
285
286 blurt()
287 • Purpose
288
289 • Arguments
290
291 • Return Value
292
293 death()
294 • Purpose
295
296 • Arguments
297
298 • Return Value
299
300 check_conditional_preprocessor_statements()
301 • Purpose
302
303 • Arguments
304
305 • Return Value
306
307 escape_file_for_line_directive()
308 • Purpose
309
310 Escapes a given code source name (typically a file name but can
311 also be a command that was read from) so that double-quotes and
312 backslashes are escaped.
313
314 • Arguments
315
316 A string.
317
318 • Return Value
319
320 A string with escapes for double-quotes and backslashes.
321
322 "report_typemap_failure"
323 • Purpose
324
325 Do error reporting for missing typemaps.
326
327 • Arguments
328
329 The "ExtUtils::ParseXS" object.
330
331 An "ExtUtils::Typemaps" object.
332
333 The string that represents the C type that was not found in the
334 typemap.
335
336 Optionally, the string "death" or "blurt" to choose whether the
337 error is immediately fatal or not. Default: "blurt"
338
339 • Return Value
340
341 Returns nothing. Depending on the arguments, this may call "death"
342 or "blurt", the former of which is fatal.
343
344
345
346perl v5.38.0 2023-07-20 ExtUtils::ParseXS::Utilities(3)