Debian Codegraph @

upstream/mageia-cauldron/man3pm/ExtUtils::ParseXS::Utilities.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "ExtUtils::ParseXS::Utilities 3pm"
61 .TH ExtUtils::ParseXS::Utilities 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 ExtUtils::ParseXS::Utilities \- Subroutines used with ExtUtils::ParseXS
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 10
71 \& use ExtUtils::ParseXS::Utilities qw(
72 \& standard_typemap_locations
73 \& trim_whitespace
74 \& C_string
75 \& valid_proto_string
76 \& process_typemaps
77 \& map_type
78 \& standard_XS_defs
79 \& analyze_preprocessor_statement
80 \& set_cond
81 \& Warn
82 \& blurt
83 \& death
84 \& check_conditional_preprocessor_statements
85 \& escape_file_for_line_directive
86 \& report_typemap_failure
87 \& );
88 .Ve
89 .SH SUBROUTINES
90 .IX Header "SUBROUTINES"
91 The following functions are not considered to be part of the public interface.
92 They are documented here for the benefit of future maintainers of this module.
93 .ie n .SS standard_typemap_locations()
94 .el .SS \f(CWstandard_typemap_locations()\fP
95 .IX Subsection "standard_typemap_locations()"
96 .IP \(bu 4
97 Purpose
98 .Sp
99 Provide a list of filepaths where \fItypemap\fR files may be found. The
100 filepaths \-\- relative paths to files (not just directory paths) \-\- appear in this list in lowest\-to\-highest priority.
101 .Sp
102 The highest priority is to look in the current directory.
103 .Sp
104 .Vb 1
105 \& \*(Aqtypemap\*(Aq
106 .Ve
107 .Sp
108 The second and third highest priorities are to look in the parent of the
109 current directory and a directory called \fIlib/ExtUtils\fR underneath the parent
110 directory.
111 .Sp
112 .Vb 2
113 \& \*(Aq../typemap\*(Aq,
114 \& \*(Aq../lib/ExtUtils/typemap\*(Aq,
115 .Ve
116 .Sp
117 The fourth through ninth highest priorities are to look in the corresponding
118 grandparent, great\-grandparent and great\-great\-grandparent directories.
119 .Sp
120 .Vb 6
121 \& \*(Aq../../typemap\*(Aq,
122 \& \*(Aq../../lib/ExtUtils/typemap\*(Aq,
123 \& \*(Aq../../../typemap\*(Aq,
124 \& \*(Aq../../../lib/ExtUtils/typemap\*(Aq,
125 \& \*(Aq../../../../typemap\*(Aq,
126 \& \*(Aq../../../../lib/ExtUtils/typemap\*(Aq,
127 .Ve
128 .Sp
129 The tenth and subsequent priorities are to look in directories named
130 \&\fIExtUtils\fR which are subdirectories of directories found in \f(CW@INC\fR \-\-
131 \&\fIprovided\fR a file named \fItypemap\fR actually exists in such a directory.
132 Example:
133 .Sp
134 .Vb 1
135 \& \*(Aq/usr/local/lib/perl5/5.10.1/ExtUtils/typemap\*(Aq,
136 .Ve
137 .Sp
138 However, these filepaths appear in the list returned by
139 \&\f(CWstandard_typemap_locations()\fR in reverse order, \fIi.e.\fR, lowest\-to\-highest.
140 .Sp
141 .Vb 10
142 \& \*(Aq/usr/local/lib/perl5/5.10.1/ExtUtils/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 \& \*(Aq../lib/ExtUtils/typemap\*(Aq,
150 \& \*(Aq../typemap\*(Aq,
151 \& \*(Aqtypemap\*(Aq
152 .Ve
153 .IP \(bu 4
154 Arguments
155 .Sp
156 .Vb 1
157 \& my @stl = standard_typemap_locations( \e@INC );
158 .Ve
159 .Sp
160 Reference to \f(CW@INC\fR.
161 .IP \(bu 4
162 Return Value
163 .Sp
164 Array holding list of directories to be searched for \fItypemap\fR files.
165 .ie n .SS trim_whitespace()
166 .el .SS \f(CWtrim_whitespace()\fP
167 .IX Subsection "trim_whitespace()"
168 .IP \(bu 4
169 Purpose
170 .Sp
171 Perform an in\-place trimming of leading and trailing whitespace from the
172 first argument provided to the function.
173 .IP \(bu 4
174 Argument
175 .Sp
176 .Vb 1
177 \& trim_whitespace($arg);
178 .Ve
179 .IP \(bu 4
180 Return Value
181 .Sp
182 None. Remember: this is an \fIin\-place\fR modification of the argument.
183 .ie n .SS C_string()
184 .el .SS \f(CWC_string()\fP
185 .IX Subsection "C_string()"
186 .IP \(bu 4
187 Purpose
188 .Sp
189 Escape backslashes (\f(CW\*(C`\e\*(C'\fR) in prototype strings.
190 .IP \(bu 4
191 Arguments
192 .Sp
193 .Vb 1
194 \& $ProtoThisXSUB = C_string($_);
195 .Ve
196 .Sp
197 String needing escaping.
198 .IP \(bu 4
199 Return Value
200 .Sp
201 Properly escaped string.
202 .ie n .SS valid_proto_string()
203 .el .SS \f(CWvalid_proto_string()\fP
204 .IX Subsection "valid_proto_string()"
205 .IP \(bu 4
206 Purpose
207 .Sp
208 Validate prototype string.
209 .IP \(bu 4
210 Arguments
211 .Sp
212 String needing checking.
213 .IP \(bu 4
214 Return Value
215 .Sp
216 Upon success, returns the same string passed as argument.
217 .Sp
218 Upon failure, returns \f(CW0\fR.
219 .ie n .SS process_typemaps()
220 .el .SS \f(CWprocess_typemaps()\fP
221 .IX Subsection "process_typemaps()"
222 .IP \(bu 4
223 Purpose
224 .Sp
225 Process all typemap files.
226 .IP \(bu 4
227 Arguments
228 .Sp
229 .Vb 1
230 \& my $typemaps_object = process_typemaps( $args{typemap}, $pwd );
231 .Ve
232 .Sp
233 List of two elements: \f(CW\*(C`typemap\*(C'\fR element from \f(CW%args\fR; current working
234 directory.
235 .IP \(bu 4
236 Return Value
237 .Sp
238 Upon success, returns an ExtUtils::Typemaps object.
239 .ie n .SS """map_type($self, $type, $varname)"""
240 .el .SS "\f(CWmap_type($self, $type, $varname)\fP"
241 .IX Subsection "map_type($self, $type, $varname)"
242 Returns a mapped version of the C type \f(CW$type\fR. In particular, it
243 converts \f(CW\*(C`Foo::bar\*(C'\fR to \f(CW\*(C`Foo_\|_bar\*(C'\fR, converts the special \f(CW\*(C`array(type,n)\*(C'\fR
244 into \f(CW\*(C`type *\*(C'\fR, and inserts \f(CW$varname\fR (if present) into any function
245 pointer type. So \f(CW\*(C`...(*)...\*(C'\fR becomes \f(CW\*(C`...(* foo)...\*(C'\fR.
246 .ie n .SS standard_XS_defs()
247 .el .SS \f(CWstandard_XS_defs()\fP
248 .IX Subsection "standard_XS_defs()"
249 .IP \(bu 4
250 Purpose
251 .Sp
252 Writes to the \f(CW\*(C`.c\*(C'\fR output file certain preprocessor directives and function
253 headers needed in all such files.
254 .IP \(bu 4
255 Arguments
256 .Sp
257 None.
258 .IP \(bu 4
259 Return Value
260 .Sp
261 Returns true.
262 .ie n .SS analyze_preprocessor_statement()
263 .el .SS \f(CWanalyze_preprocessor_statement()\fP
264 .IX Subsection "analyze_preprocessor_statement()"
265 .IP \(bu 4
266 Purpose
267 .Sp
268 Process a CPP conditional line (\f(CW\*(C`#if\*(C'\fR etc), to keep track of conditional
269 nesting. In particular, it updates \f(CW\*(C`@{$self\->{XS_parse_stack}}\*(C'\fR which
270 contains the current list of nested conditions, and
271 \&\f(CW\*(C`$self\->{XS_parse_stack_top_if_idx}\*(C'\fR which indicates the most recent
272 \&\f(CW\*(C`if\*(C'\fR in that stack. So an \f(CW\*(C`#if\*(C'\fR pushes, an \f(CW\*(C`#endif\*(C'\fR pops, an \f(CW\*(C`#else\*(C'\fR
273 modifies etc. Each element is a hash of the form:
274 .Sp
275 .Vb 3
276 \& {
277 \& type => \*(Aqif\*(Aq,
278 \& varname => \*(AqXSubPPtmpAAAA\*(Aq, # maintained by caller
279 \&
280 \& # XS functions defined within this branch of the
281 \& # conditional (maintained by caller)
282 \& functions => {
283 \& \*(AqFoo::Bar::baz\*(Aq => 1,
284 \& ...
285 \& }
286 \& # XS functions seen within any previous branch
287 \& other_functions => {... }
288 .Ve
289 .Sp
290 It also updates \f(CW\*(C`$self\->{bootcode_early}\*(C'\fR and
291 \&\f(CW\*(C`$self\->{bootcode_late}\*(C'\fR with extra CPP directives.
292 .IP \(bu 4
293 Arguments
294 .Sp
295 .Vb 1
296 \& $self\->analyze_preprocessor_statement($statement);
297 .Ve
298 .ie n .SS set_cond()
299 .el .SS \f(CWset_cond()\fP
300 .IX Subsection "set_cond()"
301 .IP \(bu 4
302 Purpose
303 .Sp
304 Return a string containing a snippet of C code which tests for the \*(Aqwrong
305 number of arguments passed\*(Aq condition, depending on whether there are
306 default arguments or ellipsis.
307 .IP \(bu 4
308 Arguments
309 .Sp
310 \&\f(CW\*(C`ellipsis\*(C'\fR true if the xsub\*(Aqs signature has a trailing \f(CW\*(C`, ...\*(C'\fR.
311 .Sp
312 \&\f(CW$min_args\fR the smallest number of args which may be passed.
313 .Sp
314 \&\f(CW$num_args\fR the number of parameters in the signature.
315 .IP \(bu 4
316 Return Value
317 .Sp
318 The text of a short C code snippet.
319 .ie n .SS current_line_number()
320 .el .SS \f(CWcurrent_line_number()\fP
321 .IX Subsection "current_line_number()"
322 .IP \(bu 4
323 Purpose
324 .Sp
325 Figures out the current line number in the XS file.
326 .IP \(bu 4
327 Arguments
328 .Sp
329 \&\f(CW$self\fR
330 .IP \(bu 4
331 Return Value
332 .Sp
333 The current line number.
334 .SS "Error handling methods"
335 .IX Subsection "Error handling methods"
336 There are four main methods for reporting warnings and errors.
337 .ie n .IP """$self\->Warn(@messages)""" 4
338 .el .IP \f(CW$self\->Warn(@messages)\fR 4
339 .IX Item "$self->Warn(@messages)"
340 This is equivalent to:
341 .Sp
342 .Vb 1
343 \& warn "@messages in foo.xs, line 123\en";
344 .Ve
345 .Sp
346 The file and line number are based on the file currently being parsed. It
347 is intended for use where you wish to warn, but can continue parsing and
348 still generate a correct C output file.
349 .ie n .IP """$self\->blurt(@messages)""" 4
350 .el .IP \f(CW$self\->blurt(@messages)\fR 4
351 .IX Item "$self->blurt(@messages)"
352 This is equivalent to \f(CW\*(C`Warn\*(C'\fR, except that it also increments the internal
353 error count (which can be retrieved with \f(CWreport_error_count()\fR). It is
354 used to report an error, but where parsing can continue (so typically for
355 a semantic error rather than a syntax error). It is expected that the
356 caller will eventually signal failure in some fashion. For example,
357 \&\f(CW\*(C`xsubpp\*(C'\fR has this as its last line:
358 .Sp
359 .Vb 1
360 \& exit($self\->report_error_count() ? 1 : 0);
361 .Ve
362 .ie n .IP """$self\->death(@messages)""" 4
363 .el .IP \f(CW$self\->death(@messages)\fR 4
364 .IX Item "$self->death(@messages)"
365 This normally equivalent to:
366 .Sp
367 .Vb 2
368 \& $self\->Warn(@messages);
369 \& exit(1);
370 .Ve
371 .Sp
372 It is used for something like a syntax error, where parsing can\*(Aqt
373 continue. However, this is inconvenient for testing purposes, as the
374 error can\*(Aqt be trapped. So if \f(CW$self\fR is created with the \f(CW\*(C`die_on_error\*(C'\fR
375 flag, or if \f(CW$ExtUtils::ParseXS::DIE_ON_ERROR\fR is true when \fBprocess_file()\fR
376 is called, then instead it will \fBdie()\fR with that message.
377 .ie n .IP """$self\->WarnHint(@messages, $hints)""" 4
378 .el .IP "\f(CW$self\->WarnHint(@messages, $hints)\fR" 4
379 .IX Item "$self->WarnHint(@messages, $hints)"
380 This is a more obscure twin to \f(CW\*(C`Warn\*(C'\fR, which does the same as \f(CW\*(C`Warn\*(C'\fR,
381 but afterwards, outputs any lines contained in the \f(CW$hints\fR string, with
382 each line wrapped in parentheses. For example:
383 .Sp
384 .Vb 2
385 \& $self\->WarnHint(@messages,
386 \& "Have you set the foo switch?\enSee the manual for further info");
387 .Ve
388 .ie n .SS check_conditional_preprocessor_statements()
389 .el .SS \f(CWcheck_conditional_preprocessor_statements()\fP
390 .IX Subsection "check_conditional_preprocessor_statements()"
391 .IP \(bu 4
392 Purpose
393 .Sp
394 Warn if the lines in \f(CW\*(C`@{ $self\->{line} }\*(C'\fR don\*(Aqt have balanced \f(CW\*(C`#if\*(C'\fR,
395 \&\f(CW\*(C`endif\*(C'\fR etc.
396 .IP \(bu 4
397 Arguments
398 .Sp
399 None
400 .IP \(bu 4
401 Return Value
402 .Sp
403 None
404 .ie n .SS escape_file_for_line_directive()
405 .el .SS \f(CWescape_file_for_line_directive()\fP
406 .IX Subsection "escape_file_for_line_directive()"
407 .IP \(bu 4
408 Purpose
409 .Sp
410 Escapes a given code source name (typically a file name but can also
411 be a command that was read from) so that double\-quotes and backslashes are escaped.
412 .IP \(bu 4
413 Arguments
414 .Sp
415 A string.
416 .IP \(bu 4
417 Return Value
418 .Sp
419 A string with escapes for double\-quotes and backslashes.
420 .ie n .SS """report_typemap_failure"""
421 .el .SS \f(CWreport_typemap_failure\fP
422 .IX Subsection "report_typemap_failure"
423 .IP \(bu 4
424 Purpose
425 .Sp
426 Do error reporting for missing typemaps.
427 .IP \(bu 4
428 Arguments
429 .Sp
430 The \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR object.
431 .Sp
432 An \f(CW\*(C`ExtUtils::Typemaps\*(C'\fR object.
433 .Sp
434 The string that represents the C type that was not found in the typemap.
435 .Sp
436 Optionally, the string \f(CW\*(C`death\*(C'\fR or \f(CW\*(C`blurt\*(C'\fR to choose
437 whether the error is immediately fatal or not. Default: \f(CW\*(C`blurt\*(C'\fR
438 .IP \(bu 4
439 Return Value
440 .Sp
441 Returns nothing. Depending on the arguments, this
442 may call \f(CW\*(C`death\*(C'\fR or \f(CW\*(C`blurt\*(C'\fR, the former of which is
443 fatal.