Debian Codegraph @

upstream/debian-unstable/man3/ExtUtils::ParseXS::Utilities.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "ExtUtils::ParseXS::Utilities 3perl"
58 .TH ExtUtils::ParseXS::Utilities 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ExtUtils::ParseXS::Utilities \- Subroutines used with ExtUtils::ParseXS
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 10
68 \& use ExtUtils::ParseXS::Utilities qw(
69 \& standard_typemap_locations
70 \& trim_whitespace
71 \& C_string
72 \& valid_proto_string
73 \& process_typemaps
74 \& map_type
75 \& standard_XS_defs
76 \& assign_func_args
77 \& analyze_preprocessor_statements
78 \& set_cond
79 \& Warn
80 \& blurt
81 \& death
82 \& check_conditional_preprocessor_statements
83 \& escape_file_for_line_directive
84 \& report_typemap_failure
85 \& );
86 .Ve
87 .SH SUBROUTINES
88 .IX Header "SUBROUTINES"
89 The following functions are not considered to be part of the public interface.
90 They are documented here for the benefit of future maintainers of this module.
91 .ie n .SS standard_typemap_locations()
92 .el .SS \f(CWstandard_typemap_locations()\fP
93 .IX Subsection "standard_typemap_locations()"
94 .IP \(bu 4
95 Purpose
96 .Sp
97 Provide a list of filepaths where \fItypemap\fR files may be found. The
98 filepaths \-\- relative paths to files (not just directory paths) \-\- appear in this list in lowest-to-highest priority.
99 .Sp
100 The highest priority is to look in the current directory.
101 .Sp
102 .Vb 1
103 \& \*(Aqtypemap\*(Aq
104 .Ve
105 .Sp
106 The second and third highest priorities are to look in the parent of the
107 current directory and a directory called \fIlib/ExtUtils\fR underneath the parent
108 directory.
109 .Sp
110 .Vb 2
111 \& \*(Aq../typemap\*(Aq,
112 \& \*(Aq../lib/ExtUtils/typemap\*(Aq,
113 .Ve
114 .Sp
115 The fourth through ninth highest priorities are to look in the corresponding
116 grandparent, great-grandparent and great-great-grandparent directories.
117 .Sp
118 .Vb 6
119 \& \*(Aq../../typemap\*(Aq,
120 \& \*(Aq../../lib/ExtUtils/typemap\*(Aq,
121 \& \*(Aq../../../typemap\*(Aq,
122 \& \*(Aq../../../lib/ExtUtils/typemap\*(Aq,
123 \& \*(Aq../../../../typemap\*(Aq,
124 \& \*(Aq../../../../lib/ExtUtils/typemap\*(Aq,
125 .Ve
126 .Sp
127 The tenth and subsequent priorities are to look in directories named
128 \&\fIExtUtils\fR which are subdirectories of directories found in \f(CW@INC\fR \-\-
129 \&\fIprovided\fR a file named \fItypemap\fR actually exists in such a directory.
130 Example:
131 .Sp
132 .Vb 1
133 \& \*(Aq/usr/local/lib/perl5/5.10.1/ExtUtils/typemap\*(Aq,
134 .Ve
135 .Sp
136 However, these filepaths appear in the list returned by
137 \&\f(CWstandard_typemap_locations()\fR in reverse order, \fIi.e.\fR, lowest-to-highest.
138 .Sp
139 .Vb 10
140 \& \*(Aq/usr/local/lib/perl5/5.10.1/ExtUtils/typemap\*(Aq,
141 \& \*(Aq../../../../lib/ExtUtils/typemap\*(Aq,
142 \& \*(Aq../../../../typemap\*(Aq,
143 \& \*(Aq../../../lib/ExtUtils/typemap\*(Aq,
144 \& \*(Aq../../../typemap\*(Aq,
145 \& \*(Aq../../lib/ExtUtils/typemap\*(Aq,
146 \& \*(Aq../../typemap\*(Aq,
147 \& \*(Aq../lib/ExtUtils/typemap\*(Aq,
148 \& \*(Aq../typemap\*(Aq,
149 \& \*(Aqtypemap\*(Aq
150 .Ve
151 .IP \(bu 4
152 Arguments
153 .Sp
154 .Vb 1
155 \& my @stl = standard_typemap_locations( \e@INC );
156 .Ve
157 .Sp
158 Reference to \f(CW@INC\fR.
159 .IP \(bu 4
160 Return Value
161 .Sp
162 Array holding list of directories to be searched for \fItypemap\fR files.
163 .ie n .SS trim_whitespace()
164 .el .SS \f(CWtrim_whitespace()\fP
165 .IX Subsection "trim_whitespace()"
166 .IP \(bu 4
167 Purpose
168 .Sp
169 Perform an in-place trimming of leading and trailing whitespace from the
170 first argument provided to the function.
171 .IP \(bu 4
172 Argument
173 .Sp
174 .Vb 1
175 \& trim_whitespace($arg);
176 .Ve
177 .IP \(bu 4
178 Return Value
179 .Sp
180 None. Remember: this is an \fIin-place\fR modification of the argument.
181 .ie n .SS C_string()
182 .el .SS \f(CWC_string()\fP
183 .IX Subsection "C_string()"
184 .IP \(bu 4
185 Purpose
186 .Sp
187 Escape backslashes (\f(CW\*(C`\e\*(C'\fR) in prototype strings.
188 .IP \(bu 4
189 Arguments
190 .Sp
191 .Vb 1
192 \& $ProtoThisXSUB = C_string($_);
193 .Ve
194 .Sp
195 String needing escaping.
196 .IP \(bu 4
197 Return Value
198 .Sp
199 Properly escaped string.
200 .ie n .SS valid_proto_string()
201 .el .SS \f(CWvalid_proto_string()\fP
202 .IX Subsection "valid_proto_string()"
203 .IP \(bu 4
204 Purpose
205 .Sp
206 Validate prototype string.
207 .IP \(bu 4
208 Arguments
209 .Sp
210 String needing checking.
211 .IP \(bu 4
212 Return Value
213 .Sp
214 Upon success, returns the same string passed as argument.
215 .Sp
216 Upon failure, returns \f(CW0\fR.
217 .ie n .SS process_typemaps()
218 .el .SS \f(CWprocess_typemaps()\fP
219 .IX Subsection "process_typemaps()"
220 .IP \(bu 4
221 Purpose
222 .Sp
223 Process all typemap files.
224 .IP \(bu 4
225 Arguments
226 .Sp
227 .Vb 1
228 \& my $typemaps_object = process_typemaps( $args{typemap}, $pwd );
229 .Ve
230 .Sp
231 List of two elements: \f(CW\*(C`typemap\*(C'\fR element from \f(CW%args\fR; current working
232 directory.
233 .IP \(bu 4
234 Return Value
235 .Sp
236 Upon success, returns an ExtUtils::Typemaps object.
237 .ie n .SS map_type()
238 .el .SS \f(CWmap_type()\fP
239 .IX Subsection "map_type()"
240 .IP \(bu 4
241 Purpose
242 .Sp
243 Performs a mapping at several places inside \f(CW\*(C`PARAGRAPH\*(C'\fR loop.
244 .IP \(bu 4
245 Arguments
246 .Sp
247 .Vb 1
248 \& $type = map_type($self, $type, $varname);
249 .Ve
250 .Sp
251 List of three arguments.
252 .IP \(bu 4
253 Return Value
254 .Sp
255 String holding augmented version of second argument.
256 .ie n .SS standard_XS_defs()
257 .el .SS \f(CWstandard_XS_defs()\fP
258 .IX Subsection "standard_XS_defs()"
259 .IP \(bu 4
260 Purpose
261 .Sp
262 Writes to the \f(CW\*(C`.c\*(C'\fR output file certain preprocessor directives and function
263 headers needed in all such files.
264 .IP \(bu 4
265 Arguments
266 .Sp
267 None.
268 .IP \(bu 4
269 Return Value
270 .Sp
271 Returns true.
272 .ie n .SS assign_func_args()
273 .el .SS \f(CWassign_func_args()\fP
274 .IX Subsection "assign_func_args()"
275 .IP \(bu 4
276 Purpose
277 .Sp
278 Perform assignment to the \f(CW\*(C`func_args\*(C'\fR attribute.
279 .IP \(bu 4
280 Arguments
281 .Sp
282 .Vb 1
283 \& $string = assign_func_args($self, $argsref, $class);
284 .Ve
285 .Sp
286 List of three elements. Second is an array reference; third is a string.
287 .IP \(bu 4
288 Return Value
289 .Sp
290 String.
291 .ie n .SS analyze_preprocessor_statements()
292 .el .SS \f(CWanalyze_preprocessor_statements()\fP
293 .IX Subsection "analyze_preprocessor_statements()"
294 .IP \(bu 4
295 Purpose
296 .Sp
297 Within each function inside each Xsub, print to the \fI.c\fR output file certain
298 preprocessor statements.
299 .IP \(bu 4
300 Arguments
301 .Sp
302 .Vb 4
303 \& ( $self, $XSS_work_idx, $BootCode_ref ) =
304 \& analyze_preprocessor_statements(
305 \& $self, $statement, $XSS_work_idx, $BootCode_ref
306 \& );
307 .Ve
308 .Sp
309 List of four elements.
310 .IP \(bu 4
311 Return Value
312 .Sp
313 Modifed values of three of the arguments passed to the function. In
314 particular, the \f(CW\*(C`XSStack\*(C'\fR and \f(CW\*(C`InitFileCode\*(C'\fR attributes are modified.
315 .ie n .SS set_cond()
316 .el .SS \f(CWset_cond()\fP
317 .IX Subsection "set_cond()"
318 .IP \(bu 4
319 Purpose
320 .IP \(bu 4
321 Arguments
322 .IP \(bu 4
323 Return Value
324 .ie n .SS current_line_number()
325 .el .SS \f(CWcurrent_line_number()\fP
326 .IX Subsection "current_line_number()"
327 .IP \(bu 4
328 Purpose
329 .Sp
330 Figures out the current line number in the XS file.
331 .IP \(bu 4
332 Arguments
333 .Sp
334 \&\f(CW$self\fR
335 .IP \(bu 4
336 Return Value
337 .Sp
338 The current line number.
339 .ie n .SS Warn()
340 .el .SS \f(CWWarn()\fP
341 .IX Subsection "Warn()"
342 .IP \(bu 4
343 Purpose
344 .Sp
345 Print warnings with line number details at the end.
346 .IP \(bu 4
347 Arguments
348 .Sp
349 List of text to output.
350 .IP \(bu 4
351 Return Value
352 .Sp
353 None.
354 .ie n .SS WarnHint()
355 .el .SS \f(CWWarnHint()\fP
356 .IX Subsection "WarnHint()"
357 .IP \(bu 4
358 Purpose
359 .Sp
360 Prints warning with line number details. The last argument is assumed
361 to be a hint string.
362 .IP \(bu 4
363 Arguments
364 .Sp
365 List of strings to warn, followed by one argument representing a hint.
366 If that argument is defined then it will be split on newlines and output
367 line by line after the main warning.
368 .IP \(bu 4
369 Return Value
370 .Sp
371 None.
372 .ie n .SS _MsgHint()
373 .el .SS \f(CW_MsgHint()\fP
374 .IX Subsection "_MsgHint()"
375 .IP \(bu 4
376 Purpose
377 .Sp
378 Constructs an exception message with line number details. The last argument is
379 assumed to be a hint string.
380 .IP \(bu 4
381 Arguments
382 .Sp
383 List of strings to warn, followed by one argument representing a hint.
384 If that argument is defined then it will be split on newlines and concatenated
385 line by line (parenthesized) after the main message.
386 .IP \(bu 4
387 Return Value
388 .Sp
389 The constructed string.
390 .ie n .SS blurt()
391 .el .SS \f(CWblurt()\fP
392 .IX Subsection "blurt()"
393 .IP \(bu 4
394 Purpose
395 .IP \(bu 4
396 Arguments
397 .IP \(bu 4
398 Return Value
399 .ie n .SS death()
400 .el .SS \f(CWdeath()\fP
401 .IX Subsection "death()"
402 .IP \(bu 4
403 Purpose
404 .IP \(bu 4
405 Arguments
406 .IP \(bu 4
407 Return Value
408 .ie n .SS check_conditional_preprocessor_statements()
409 .el .SS \f(CWcheck_conditional_preprocessor_statements()\fP
410 .IX Subsection "check_conditional_preprocessor_statements()"
411 .IP \(bu 4
412 Purpose
413 .IP \(bu 4
414 Arguments
415 .IP \(bu 4
416 Return Value
417 .ie n .SS escape_file_for_line_directive()
418 .el .SS \f(CWescape_file_for_line_directive()\fP
419 .IX Subsection "escape_file_for_line_directive()"
420 .IP \(bu 4
421 Purpose
422 .Sp
423 Escapes a given code source name (typically a file name but can also
424 be a command that was read from) so that double-quotes and backslashes are escaped.
425 .IP \(bu 4
426 Arguments
427 .Sp
428 A string.
429 .IP \(bu 4
430 Return Value
431 .Sp
432 A string with escapes for double-quotes and backslashes.
433 .ie n .SS """report_typemap_failure"""
434 .el .SS \f(CWreport_typemap_failure\fP
435 .IX Subsection "report_typemap_failure"
436 .IP \(bu 4
437 Purpose
438 .Sp
439 Do error reporting for missing typemaps.
440 .IP \(bu 4
441 Arguments
442 .Sp
443 The \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR object.
444 .Sp
445 An \f(CW\*(C`ExtUtils::Typemaps\*(C'\fR object.
446 .Sp
447 The string that represents the C type that was not found in the typemap.
448 .Sp
449 Optionally, the string \f(CW\*(C`death\*(C'\fR or \f(CW\*(C`blurt\*(C'\fR to choose
450 whether the error is immediately fatal or not. Default: \f(CW\*(C`blurt\*(C'\fR
451 .IP \(bu 4
452 Return Value
453 .Sp
454 Returns nothing. Depending on the arguments, this
455 may call \f(CW\*(C`death\*(C'\fR or \f(CW\*(C`blurt\*(C'\fR, the former of which is
456 fatal.