Debian Codegraph @

upstream/opensuse-tumbleweed/man3/ExtUtils::Typemaps.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::Typemaps 3pm"
61 .TH ExtUtils::Typemaps 3pm 2026-03-09 "perl v5.42.1" "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::Typemaps \- Read/Write/Modify Perl/XS typemap files
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 6
71 \& # read/create file
72 \& my $typemap = ExtUtils::Typemaps\->new(file => \*(Aqtypemap\*(Aq);
73 \& # alternatively create an in\-memory typemap
74 \& # $typemap = ExtUtils::Typemaps\->new();
75 \& # alternatively create an in\-memory typemap by parsing a string
76 \& # $typemap = ExtUtils::Typemaps\->new(string => $sometypemap);
77 \&
78 \& # add a mapping
79 \& $typemap\->add_typemap(ctype => \*(AqNV\*(Aq, xstype => \*(AqT_NV\*(Aq);
80 \& $typemap\->add_inputmap(
81 \& xstype => \*(AqT_NV\*(Aq, code => \*(Aq$var = ($type)SvNV($arg);\*(Aq
82 \& );
83 \& $typemap\->add_outputmap(
84 \& xstype => \*(AqT_NV\*(Aq, code => \*(Aqsv_setnv($arg, (NV)$var);\*(Aq
85 \& );
86 \& $typemap\->add_string(string => $typemapstring);
87 \& # will be parsed and merged
88 \&
89 \& # remove a mapping (same for remove_typemap and remove_outputmap...)
90 \& $typemap\->remove_inputmap(xstype => \*(AqSomeType\*(Aq);
91 \&
92 \& # save a typemap to a file
93 \& $typemap\->write(file => \*(Aqanotherfile.map\*(Aq);
94 \&
95 \& # merge the other typemap into this one
96 \& $typemap\->merge(typemap => $another_typemap);
97 .Ve
98 .SH DESCRIPTION
99 .IX Header "DESCRIPTION"
100 This module can read, modify, create and write Perl XS typemap files. If you don\*(Aqt know
101 what a typemap is, please confer the perlxstut and perlxs manuals.
102 .PP
103 The module is not entirely round\-trip safe: For example it currently simply strips all comments.
104 The order of entries in the maps is, however, preserved.
105 .PP
106 We check for duplicate entries in the typemap, but do not check for missing
107 \&\f(CW\*(C`TYPEMAP\*(C'\fR entries for \f(CW\*(C`INPUTMAP\*(C'\fR or \f(CW\*(C`OUTPUTMAP\*(C'\fR entries since these might be hidden
108 in a different typemap.
109 .SH METHODS
110 .IX Header "METHODS"
111 .SS new
112 .IX Subsection "new"
113 Returns a new typemap object. Takes an optional \f(CW\*(C`file\*(C'\fR parameter.
114 If set, the given file will be read. If the file doesn\*(Aqt exist, an empty typemap
115 is returned.
116 .PP
117 Alternatively, if the \f(CW\*(C`string\*(C'\fR parameter is given, the supplied
118 string will be parsed instead of a file.
119 .SS file
120 .IX Subsection "file"
121 Get/set the file that the typemap is written to when the
122 \&\f(CW\*(C`write\*(C'\fR method is called.
123 .SS add_typemap
124 .IX Subsection "add_typemap"
125 Add a \f(CW\*(C`TYPEMAP\*(C'\fR entry to the typemap.
126 .PP
127 Required named arguments: The \f(CW\*(C`ctype\*(C'\fR (e.g. \f(CW\*(C`ctype => \*(Aqdouble\*(Aq\*(C'\fR)
128 and the \f(CW\*(C`xstype\*(C'\fR (e.g. \f(CW\*(C`xstype => \*(AqT_NV\*(Aq\*(C'\fR).
129 .PP
130 Optional named arguments: \f(CW\*(C`replace => 1\*(C'\fR forces removal/replacement of
131 existing \f(CW\*(C`TYPEMAP\*(C'\fR entries of the same \f(CW\*(C`ctype\*(C'\fR. \f(CW\*(C`skip => 1\*(C'\fR
132 triggers a \fI"first come first serve"\fR logic by which new entries that conflict
133 with existing entries are silently ignored.
134 .PP
135 As an alternative to the named parameters usage, you may pass in
136 an \f(CW\*(C`ExtUtils::Typemaps::Type\*(C'\fR object as first argument, a copy of which will be
137 added to the typemap. In that case, only the \f(CW\*(C`replace\*(C'\fR or \f(CW\*(C`skip\*(C'\fR named parameters
138 may be used after the object. Example:
139 .PP
140 .Vb 1
141 \& $map\->add_typemap($type_obj, replace => 1);
142 .Ve
143 .SS add_inputmap
144 .IX Subsection "add_inputmap"
145 Add an \f(CW\*(C`INPUT\*(C'\fR entry to the typemap.
146 .PP
147 Required named arguments:
148 The \f(CW\*(C`xstype\*(C'\fR (e.g. \f(CW\*(C`xstype => \*(AqT_NV\*(Aq\*(C'\fR)
149 and the \f(CW\*(C`code\*(C'\fR to associate with it for input.
150 .PP
151 Optional named arguments: \f(CW\*(C`replace => 1\*(C'\fR forces removal/replacement of
152 existing \f(CW\*(C`INPUT\*(C'\fR entries of the same \f(CW\*(C`xstype\*(C'\fR. \f(CW\*(C`skip => 1\*(C'\fR
153 triggers a \fI"first come first serve"\fR logic by which new entries that conflict
154 with existing entries are silently ignored.
155 .PP
156 As an alternative to the named parameters usage, you may pass in
157 an \f(CW\*(C`ExtUtils::Typemaps::InputMap\*(C'\fR object as first argument, a copy of which will be
158 added to the typemap. In that case, only the \f(CW\*(C`replace\*(C'\fR or \f(CW\*(C`skip\*(C'\fR named parameters
159 may be used after the object. Example:
160 .PP
161 .Vb 1
162 \& $map\->add_inputmap($type_obj, replace => 1);
163 .Ve
164 .SS add_outputmap
165 .IX Subsection "add_outputmap"
166 Add an \f(CW\*(C`OUTPUT\*(C'\fR entry to the typemap.
167 Works exactly the same as \f(CW\*(C`add_inputmap\*(C'\fR.
168 .SS add_string
169 .IX Subsection "add_string"
170 Parses a string as a typemap and merge it into the typemap object.
171 .PP
172 Required named argument: \f(CW\*(C`string\*(C'\fR to specify the string to parse.
173 .SS remove_typemap
174 .IX Subsection "remove_typemap"
175 Removes a \f(CW\*(C`TYPEMAP\*(C'\fR entry from the typemap.
176 .PP
177 Required named argument: \f(CW\*(C`ctype\*(C'\fR to specify the entry to remove from the typemap.
178 .PP
179 Alternatively, you may pass a single \f(CW\*(C`ExtUtils::Typemaps::Type\*(C'\fR object.
180 .SS remove_inputmap
181 .IX Subsection "remove_inputmap"
182 Removes an \f(CW\*(C`INPUT\*(C'\fR entry from the typemap.
183 .PP
184 Required named argument: \f(CW\*(C`xstype\*(C'\fR to specify the entry to remove from the typemap.
185 .PP
186 Alternatively, you may pass a single \f(CW\*(C`ExtUtils::Typemaps::InputMap\*(C'\fR object.
187 .SS remove_outputmap
188 .IX Subsection "remove_outputmap"
189 Removes an \f(CW\*(C`OUTPUT\*(C'\fR entry from the typemap.
190 .PP
191 Required named argument: \f(CW\*(C`xstype\*(C'\fR to specify the entry to remove from the typemap.
192 .PP
193 Alternatively, you may pass a single \f(CW\*(C`ExtUtils::Typemaps::OutputMap\*(C'\fR object.
194 .SS get_typemap
195 .IX Subsection "get_typemap"
196 Fetches an entry of the TYPEMAP section of the typemap.
197 .PP
198 Mandatory named arguments: The \f(CW\*(C`ctype\*(C'\fR of the entry.
199 .PP
200 Returns the \f(CW\*(C`ExtUtils::Typemaps::Type\*(C'\fR
201 object for the entry if found.
202 .SS get_inputmap
203 .IX Subsection "get_inputmap"
204 Fetches an entry of the INPUT section of the
205 typemap.
206 .PP
207 Mandatory named arguments: The \f(CW\*(C`xstype\*(C'\fR of the
208 entry or the \f(CW\*(C`ctype\*(C'\fR of the typemap that can be used to find
209 the \f(CW\*(C`xstype\*(C'\fR. To wit, the following pieces of code
210 are equivalent:
211 .PP
212 .Vb 2
213 \& my $type = $typemap\->get_typemap(ctype => $ctype)
214 \& my $input_map = $typemap\->get_inputmap(xstype => $type\->xstype);
215 \&
216 \& my $input_map = $typemap\->get_inputmap(ctype => $ctype);
217 .Ve
218 .PP
219 Returns the \f(CW\*(C`ExtUtils::Typemaps::InputMap\*(C'\fR
220 object for the entry if found.
221 .SS get_outputmap
222 .IX Subsection "get_outputmap"
223 Fetches an entry of the OUTPUT section of the
224 typemap.
225 .PP
226 Mandatory named arguments: The \f(CW\*(C`xstype\*(C'\fR of the
227 entry or the \f(CW\*(C`ctype\*(C'\fR of the typemap that can be used to
228 resolve the \f(CW\*(C`xstype\*(C'\fR. (See above for an example.)
229 .PP
230 Returns the \f(CW\*(C`ExtUtils::Typemaps::InputMap\*(C'\fR
231 object for the entry if found.
232 .SS write
233 .IX Subsection "write"
234 Write the typemap to a file. Optionally takes a \f(CW\*(C`file\*(C'\fR argument. If given, the
235 typemap will be written to the specified file. If not, the typemap is written
236 to the currently stored file name (see "file" above, this defaults to the file
237 it was read from if any).
238 .SS as_string
239 .IX Subsection "as_string"
240 Generates and returns the string form of the typemap.
241 .SS as_embedded_typemap
242 .IX Subsection "as_embedded_typemap"
243 Generates and returns the string form of the typemap with the
244 appropriate prefix around it for verbatim inclusion into an
245 XS file as an embedded typemap. This will return a string like
246 .PP
247 .Vb 3
248 \& TYPEMAP: <<END_OF_TYPEMAP
249 \& ... typemap here (see as_string) ...
250 \& END_OF_TYPEMAP
251 .Ve
252 .PP
253 The method takes care not to use a HERE\-doc end marker that
254 appears in the typemap string itself.
255 .SS merge
256 .IX Subsection "merge"
257 Merges a given typemap into the object. Note that a failed merge
258 operation leaves the object in an inconsistent state so clone it if necessary.
259 .PP
260 Mandatory named arguments: Either \f(CW\*(C`typemap => $another_typemap_obj\*(C'\fR
261 or \f(CW\*(C`file => $path_to_typemap_file\*(C'\fR but not both.
262 .PP
263 Optional arguments: \f(CW\*(C`replace => 1\*(C'\fR to force replacement
264 of existing typemap entries without warning or \f(CW\*(C`skip => 1\*(C'\fR
265 to skip entries that exist already in the typemap.
266 .SS is_empty
267 .IX Subsection "is_empty"
268 Returns a bool indicating whether this typemap is entirely empty.
269 .SS list_mapped_ctypes
270 .IX Subsection "list_mapped_ctypes"
271 Returns a list of the C types that are mappable by
272 this typemap object.
273 .SS _get_typemap_hash
274 .IX Subsection "_get_typemap_hash"
275 Returns a hash mapping the C types to the XS types:
276 .PP
277 .Vb 8
278 \& {
279 \& \*(Aqchar **\*(Aq => \*(AqT_PACKEDARRAY\*(Aq,
280 \& \*(Aqbool_t\*(Aq => \*(AqT_IV\*(Aq,
281 \& \*(AqAV *\*(Aq => \*(AqT_AVREF\*(Aq,
282 \& \*(AqInputStream\*(Aq => \*(AqT_IN\*(Aq,
283 \& \*(Aqdouble\*(Aq => \*(AqT_DOUBLE\*(Aq,
284 \& # ...
285 \& }
286 .Ve
287 .PP
288 This is documented because it is used by \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR,
289 but it\*(Aqs not intended for general consumption. May be removed
290 at any time.
291 .SS _get_inputmap_hash
292 .IX Subsection "_get_inputmap_hash"
293 Returns a hash mapping the XS types (identifiers) to the
294 corresponding INPUT code:
295 .PP
296 .Vb 8
297 \& {
298 \& \*(AqT_CALLBACK\*(Aq => \*(Aq $var = make_perl_cb_$type($arg)
299 \& \*(Aq,
300 \& \*(AqT_OUT\*(Aq => \*(Aq $var = IoOFP(sv_2io($arg))
301 \& \*(Aq,
302 \& \*(AqT_REF_IV_PTR\*(Aq => \*(Aq if (sv_isa($arg, \e\e"${ntype}\e\e")) {
303 \& # ...
304 \& }
305 .Ve
306 .PP
307 This is documented because it is used by \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR,
308 but it\*(Aqs not intended for general consumption. May be removed
309 at any time.
310 .SS _get_outputmap_hash
311 .IX Subsection "_get_outputmap_hash"
312 Returns a hash mapping the XS types (identifiers) to the
313 corresponding OUTPUT code:
314 .PP
315 .Vb 10
316 \& {
317 \& \*(AqT_CALLBACK\*(Aq => \*(Aq sv_setpvn($arg, $var.context.value().chp(),
318 \& $var.context.value().size());
319 \& \*(Aq,
320 \& \*(AqT_OUT\*(Aq => \*(Aq {
321 \& GV *gv = (GV *)sv_newmortal();
322 \& gv_init_pvn(gv, gv_stashpvs("$Package",1),
323 \& "_\|_ANONIO_\|_",10,0);
324 \& if ( do_open(gv, "+>&", 3, FALSE, 0, 0, $var) )
325 \& sv_setsv(
326 \& $arg,
327 \& sv_bless(newRV((SV*)gv), gv_stashpv("$Package",1))
328 \& );
329 \& else
330 \& $arg = &PL_sv_undef;
331 \& }
332 \& \*(Aq,
333 \& # ...
334 \& }
335 .Ve
336 .PP
337 This is documented because it is used by \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR,
338 but it\*(Aqs not intended for general consumption. May be removed
339 at any time.
340 .SS _get_prototype_hash
341 .IX Subsection "_get_prototype_hash"
342 Returns a hash mapping the C types of the typemap to their
343 corresponding prototypes.
344 .PP
345 .Vb 8
346 \& {
347 \& \*(Aqchar **\*(Aq => \*(Aq$\*(Aq,
348 \& \*(Aqbool_t\*(Aq => \*(Aq$\*(Aq,
349 \& \*(AqAV *\*(Aq => \*(Aq$\*(Aq,
350 \& \*(AqInputStream\*(Aq => \*(Aq$\*(Aq,
351 \& \*(Aqdouble\*(Aq => \*(Aq$\*(Aq,
352 \& # ...
353 \& }
354 .Ve
355 .PP
356 This is documented because it is used by \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR,
357 but it\*(Aqs not intended for general consumption. May be removed
358 at any time.
359 .SS clone
360 .IX Subsection "clone"
361 Creates and returns a clone of a full typemaps object.
362 .PP
363 Takes named parameters: If \f(CW\*(C`shallow\*(C'\fR is true,
364 the clone will share the actual individual type/input/outputmap objects,
365 but not share their storage. Use with caution. Without \f(CW\*(C`shallow\*(C'\fR,
366 the clone will be fully independent.
367 .SS tidy_type
368 .IX Subsection "tidy_type"
369 Function to (heuristically) canonicalize a C type in terms of white space.
370 Works to some degree with C++ types. For example,
371 .PP
372 .Vb 1
373 \& $halfway_canonical_type = tidy_type(\*(Aq int * * const * \*(Aq);
374 .Ve
375 .PP
376 returns \f(CW\*(Aqint ** const *\*(Aq\fR.
377 .PP
378 Moved from \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR.
379 .SH CAVEATS
380 .IX Header "CAVEATS"
381 Inherits some evil code from \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR.
382 .SH "SEE ALSO"
383 .IX Header "SEE ALSO"
384 The parser is heavily inspired from the one in ExtUtils::ParseXS.
385 .PP
386 For details on typemaps: perlxstut, perlxs.
387 .SH AUTHOR
388 .IX Header "AUTHOR"
389 Steffen Mueller \f(CW\*(C`<[email protected]\*(C'\fR>
390 .SH "COPYRIGHT & LICENSE"
391 .IX Header "COPYRIGHT & LICENSE"
392 Copyright 2009, 2010, 2011, 2012, 2013 Steffen Mueller
393 .PP
394 This program is free software; you can redistribute it and/or
395 modify it under the same terms as Perl itself.