1ExtUtils::ParseXS::UtilUisteiresC(o3n)tributed Perl DocuEmxetnUttaitliso:n:ParseXS::Utilities(3)
2
3
4

NAME

6       ExtUtils::ParseXS::Utilities - Subroutines used with ExtUtils::ParseXS
7

SYNOPSIS

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

SUBROUTINES

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)