ExtUtils::Typemaps(3pm)

1ExtUtils::Typemaps(3) User Contributed Perl DocumentationExtUtils::Typemaps(3)
2
3
4

NAME

6       ExtUtils::Typemaps - Read/Write/Modify Perl/XS typemap files
7

SYNOPSIS

9         # read/create file
10         my $typemap = ExtUtils::Typemaps->new(file => 'typemap');
11         # alternatively create an in-memory typemap
12         # $typemap = ExtUtils::Typemaps->new();
13         # alternatively create an in-memory typemap by parsing a string
14         # $typemap = ExtUtils::Typemaps->new(string => $sometypemap);
15
16         # add a mapping
17         $typemap->add_typemap(ctype => 'NV', xstype => 'T_NV');
18         $typemap->add_inputmap(
19            xstype => 'T_NV', code => '$var = ($type)SvNV($arg);'
20         );
21         $typemap->add_outputmap(
22            xstype => 'T_NV', code => 'sv_setnv($arg, (NV)$var);'
23         );
24         $typemap->add_string(string => $typemapstring);
25                                                  # will be parsed and merged
26
27         # remove a mapping (same for remove_typemap and remove_outputmap...)
28         $typemap->remove_inputmap(xstype => 'SomeType');
29
30         # save a typemap to a file
31         $typemap->write(file => 'anotherfile.map');
32
33         # merge the other typemap into this one
34         $typemap->merge(typemap => $another_typemap);
35

DESCRIPTION

37       This module can read, modify, create and write Perl XS typemap files.
38       If you don't know what a typemap is, please confer the perlxstut and
39       perlxs manuals.
40
41       The module is not entirely round-trip safe: For example it currently
42       simply strips all comments.  The order of entries in the maps is,
43       however, preserved.
44
45       We check for duplicate entries in the typemap, but do not check for
46       missing "TYPEMAP" entries for "INPUTMAP" or "OUTPUTMAP" entries since
47       these might be hidden in a different typemap.
48

METHODS

50   new
51       Returns a new typemap object. Takes an optional "file" parameter.  If
52       set, the given file will be read. If the file doesn't exist, an empty
53       typemap is returned.
54
55       Alternatively, if the "string" parameter is given, the supplied string
56       will be parsed instead of a file.
57
58   file
59       Get/set the file that the typemap is written to when the "write" method
60       is called.
61
62   add_typemap
63       Add a "TYPEMAP" entry to the typemap.
64
65       Required named arguments: The "ctype" (e.g. "ctype => 'double'") and
66       the "xstype" (e.g. "xstype => 'T_NV'").
67
68       Optional named arguments: "replace => 1" forces removal/replacement of
69       existing "TYPEMAP" entries of the same "ctype". "skip => 1" triggers a
70       "first come first serve" logic by which new entries that conflict with
71       existing entries are silently ignored.
72
73       As an alternative to the named parameters usage, you may pass in an
74       "ExtUtils::Typemaps::Type" object as first argument, a copy of which
75       will be added to the typemap. In that case, only the "replace" or
76       "skip" named parameters may be used after the object. Example:
77
78         $map->add_typemap($type_obj, replace => 1);
79
80   add_inputmap
81       Add an "INPUT" entry to the typemap.
82
83       Required named arguments: The "xstype" (e.g. "xstype => 'T_NV'") and
84       the "code" to associate with it for input.
85
86       Optional named arguments: "replace => 1" forces removal/replacement of
87       existing "INPUT" entries of the same "xstype". "skip => 1" triggers a
88       "first come first serve" logic by which new entries that conflict with
89       existing entries are silently ignored.
90
91       As an alternative to the named parameters usage, you may pass in an
92       "ExtUtils::Typemaps::InputMap" object as first argument, a copy of
93       which will be added to the typemap. In that case, only the "replace" or
94       "skip" named parameters may be used after the object. Example:
95
96         $map->add_inputmap($type_obj, replace => 1);
97
98   add_outputmap
99       Add an "OUTPUT" entry to the typemap.  Works exactly the same as
100       "add_inputmap".
101
102   add_string
103       Parses a string as a typemap and merge it into the typemap object.
104
105       Required named argument: "string" to specify the string to parse.
106
107   remove_typemap
108       Removes a "TYPEMAP" entry from the typemap.
109
110       Required named argument: "ctype" to specify the entry to remove from
111       the typemap.
112
113       Alternatively, you may pass a single "ExtUtils::Typemaps::Type" object.
114
115   remove_inputmap
116       Removes an "INPUT" entry from the typemap.
117
118       Required named argument: "xstype" to specify the entry to remove from
119       the typemap.
120
121       Alternatively, you may pass a single "ExtUtils::Typemaps::InputMap"
122       object.
123
124   remove_inputmap
125       Removes an "OUTPUT" entry from the typemap.
126
127       Required named argument: "xstype" to specify the entry to remove from
128       the typemap.
129
130       Alternatively, you may pass a single "ExtUtils::Typemaps::OutputMap"
131       object.
132
133   get_typemap
134       Fetches an entry of the TYPEMAP section of the typemap.
135
136       Mandatory named arguments: The "ctype" of the entry.
137
138       Returns the "ExtUtils::Typemaps::Type" object for the entry if found.
139
140   get_inputmap
141       Fetches an entry of the INPUT section of the typemap.
142
143       Mandatory named arguments: The "xstype" of the entry or the "ctype" of
144       the typemap that can be used to find the "xstype". To wit, the
145       following pieces of code are equivalent:
146
147         my $type = $typemap->get_typemap(ctype => $ctype)
148         my $input_map = $typemap->get_inputmap(xstype => $type->xstype);
149
150         my $input_map = $typemap->get_inputmap(ctype => $ctype);
151
152       Returns the "ExtUtils::Typemaps::InputMap" object for the entry if
153       found.
154
155   get_outputmap
156       Fetches an entry of the OUTPUT section of the typemap.
157
158       Mandatory named arguments: The "xstype" of the entry or the "ctype" of
159       the typemap that can be used to resolve the "xstype". (See above for an
160       example.)
161
162       Returns the "ExtUtils::Typemaps::InputMap" object for the entry if
163       found.
164
165   write
166       Write the typemap to a file. Optionally takes a "file" argument. If
167       given, the typemap will be written to the specified file. If not, the
168       typemap is written to the currently stored file name (see "file" above,
169       this defaults to the file it was read from if any).
170
171   as_string
172       Generates and returns the string form of the typemap.
173
174   as_embedded_typemap
175       Generates and returns the string form of the typemap with the
176       appropriate prefix around it for verbatim inclusion into an XS file as
177       an embedded typemap. This will return a string like
178
179         TYPEMAP: <<END_OF_TYPEMAP
180         ... typemap here (see as_string) ...
181         END_OF_TYPEMAP
182
183       The method takes care not to use a HERE-doc end marker that appears in
184       the typemap string itself.
185
186   merge
187       Merges a given typemap into the object. Note that a failed merge
188       operation leaves the object in an inconsistent state so clone it if
189       necessary.
190
191       Mandatory named arguments: Either "typemap => $another_typemap_obj" or
192       "file => $path_to_typemap_file" but not both.
193
194       Optional arguments: "replace => 1" to force replacement of existing
195       typemap entries without warning or "skip => 1" to skip entries that
196       exist already in the typemap.
197
198   is_empty
199       Returns a bool indicating whether this typemap is entirely empty.
200
201   list_mapped_ctypes
202       Returns a list of the C types that are mappable by this typemap object.
203
204   _get_typemap_hash
205       Returns a hash mapping the C types to the XS types:
206
207         {
208           'char **' => 'T_PACKEDARRAY',
209           'bool_t' => 'T_IV',
210           'AV *' => 'T_AVREF',
211           'InputStream' => 'T_IN',
212           'double' => 'T_DOUBLE',
213           # ...
214         }
215
216       This is documented because it is used by "ExtUtils::ParseXS", but it's
217       not intended for general consumption. May be removed at any time.
218
219   _get_inputmap_hash
220       Returns a hash mapping the XS types (identifiers) to the corresponding
221       INPUT code:
222
223         {
224           'T_CALLBACK' => '   $var = make_perl_cb_$type($arg)
225         ',
226           'T_OUT' => '    $var = IoOFP(sv_2io($arg))
227         ',
228           'T_REF_IV_PTR' => '   if (sv_isa($arg, \\"${ntype}\\")) {
229           # ...
230         }
231
232       This is documented because it is used by "ExtUtils::ParseXS", but it's
233       not intended for general consumption. May be removed at any time.
234
235   _get_outputmap_hash
236       Returns a hash mapping the XS types (identifiers) to the corresponding
237       OUTPUT code:
238
239         {
240           'T_CALLBACK' => '   sv_setpvn($arg, $var.context.value().chp(),
241                       $var.context.value().size());
242         ',
243           'T_OUT' => '    {
244                   GV *gv = (GV *)sv_newmortal();
245                   gv_init_pvn(gv, gv_stashpvs("$Package",1),
246                              "__ANONIO__",10,0);
247                   if ( do_open(gv, "+>&", 3, FALSE, 0, 0, $var) )
248                       sv_setsv(
249                         $arg,
250                         sv_bless(newRV((SV*)gv), gv_stashpv("$Package",1))
251                       );
252                   else
253                       $arg = &PL_sv_undef;
254                }
255         ',
256           # ...
257         }
258
259       This is documented because it is used by "ExtUtils::ParseXS", but it's
260       not intended for general consumption. May be removed at any time.
261
262   _get_prototype_hash
263       Returns a hash mapping the C types of the typemap to their
264       corresponding prototypes.
265
266         {
267           'char **' => '$',
268           'bool_t' => '$',
269           'AV *' => '$',
270           'InputStream' => '$',
271           'double' => '$',
272           # ...
273         }
274
275       This is documented because it is used by "ExtUtils::ParseXS", but it's
276       not intended for general consumption. May be removed at any time.
277
278   clone
279       Creates and returns a clone of a full typemaps object.
280
281       Takes named parameters: If "shallow" is true, the clone will share the
282       actual individual type/input/outputmap objects, but not share their
283       storage. Use with caution. Without "shallow", the clone will be fully
284       independent.
285
286   tidy_type
287       Function to (heuristically) canonicalize a C type. Works to some degree
288       with C++ types.
289
290           $halfway_canonical_type = tidy_type($ctype);
291
292       Moved from "ExtUtils::ParseXS".
293

CAVEATS

295       Inherits some evil code from "ExtUtils::ParseXS".
296

AUTHOR

303       Steffen Mueller "<smueller@cpan.org">
304

COPYRIGHT & LICENSE

306       Copyright 2009, 2010, 2011, 2012, 2013 Steffen Mueller
307
308       This program is free software; you can redistribute it and/or modify it
309       under the same terms as Perl itself.
310
311
312
313perl v5.32.0                      2020-07-28             ExtUtils::Typemaps(3)