Debian Codegraph @

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