ExtUti...pemaps(3perl)

🎀 NAME 🎀

hiii bestie, welcome to ExtUtils::Typemaps — the page from the 3perl manual section — and she Read/Write/Modifys Perl/XS typemap files. that's it, that's the girl. 💅

---

✨ SYNOPSIS ✨

okay so here's the whole vibe in code form, no cap:

# read/create file
my $typemap = ExtUtils::Typemaps->new(file => 'typemap');
# alternatively create an in-memory typemap
# $typemap = ExtUtils::Typemaps->new();
# alternatively create an in-memory typemap by parsing a string
# $typemap = ExtUtils::Typemaps->new(string => $sometypemap);

# add a mapping
$typemap->add_typemap(ctype => 'NV', xstype => 'T_NV');
$typemap->add_inputmap(
   xstype => 'T_NV', code => '$var = ($type)SvNV($arg);'
);
$typemap->add_outputmap(
   xstype => 'T_NV', code => 'sv_setnv($arg, (NV)$var);'
);
$typemap->add_string(string => $typemapstring);
                                         # will be parsed and merged

# remove a mapping (same for remove_typemap and remove_outputmap...)
$typemap->remove_inputmap(xstype => 'SomeType');

# save a typemap to a file
$typemap->write(file => 'anotherfile.map');

# merge the other typemap into this one
$typemap->merge(typemap => $another_typemap);

---

💖 DESCRIPTION 💖

this module can read, modify, create and write Perl XS typemap files. and if you're sitting here like "bestie what even IS a typemap 😭", go confer the perlxstut and perlxs manuals first, they've got you. 🫶

okay so real talk — this module is not entirely round-trip safe. for example, right now it literally just strips all comments. gone. poof. 💀 the order of entries in the maps is, however, preserved. so at least the vibes stay in sequence. ⭐

we check for duplicate entries in the typemap, but we do not check for missing "TYPEMAP" entries for "INPUTMAP" or "OUTPUTMAP" entries — because those might be hidden in a different typemap. sneaky little things. 🙈

---

🌸 METHODS 🌸

💫 new

returns a brand new typemap object. takes an optional "file" parameter — if it's set, that file gets read. and if the file doesn't exist? no drama, you just get an empty typemap back.

alternatively, if the "string" parameter is given, the supplied string gets parsed instead of a file. pick your fighter. ✨

💫 file

get/set the file that the typemap gets written to when the "write" method is called. it's giving "where do i save this" energy. 💾

💫 add_typemap

adds a "TYPEMAP" entry to the typemap. iconic.

• Required named arguments: the "ctype" (e.g. ctype => 'double') and the "xstype" (e.g. xstype => 'T_NV').
• Optional named arguments: "replace => 1" forces removal/replacement of existing "TYPEMAP" entries of the same "ctype". "skip => 1" triggers a "first come first serve" logic by which new entries that conflict with existing entries are silently ignored.

as an alternative to the named-parameters usage, you may pass in an "ExtUtils::Typemaps::Type" object as the first argument, and a copy of it will be added to the typemap. in that case, only the "replace" or "skip" named parameters may be used after the object. example, because examples slay:

$map->add_typemap($type_obj, replace => 1);

💫 add_inputmap

adds an "INPUT" entry to the typemap. 💅

• Required named arguments: the "xstype" (e.g. xstype => 'T_NV') and the "code" to associate with it for input.
• Optional named arguments: "replace => 1" forces removal/replacement of existing "INPUT" entries of the same "xstype". "skip => 1" triggers a "first come first serve" logic by which new entries that conflict with existing entries are silently ignored.

as an alternative to the named-parameters usage, you may pass in an "ExtUtils::Typemaps::InputMap" object as the first argument, and a copy of it will be added to the typemap. in that case, only the "replace" or "skip" named parameters may be used after the object. example:

$map->add_inputmap($type_obj, replace => 1);

💫 add_outputmap

adds an "OUTPUT" entry to the typemap. works exactly the same as "add_inputmap". copy-paste sibling energy, love that for her. 👑

💫 add_string

parses a string as a typemap and merges it into the typemap object.

• Required named argument: "string" to specify the string to parse.

💫 remove_typemap

removes a "TYPEMAP" entry from the typemap. bye bestie. 🦋

• Required named argument: "ctype" to specify the entry to remove from the typemap.

alternatively, you may pass a single "ExtUtils::Typemaps::Type" object.

💫 remove_inputmap

removes an "INPUT" entry from the typemap. 🧚

• Required named argument: "xstype" to specify the entry to remove from the typemap.

alternatively, you may pass a single "ExtUtils::Typemaps::InputMap" object.

💫 remove_outputmap

removes an "OUTPUT" entry from the typemap. 💜

• Required named argument: "xstype" to specify the entry to remove from the typemap.

alternatively, you may pass a single "ExtUtils::Typemaps::OutputMap" object.

💫 get_typemap

fetches an entry of the TYPEMAP section of the typemap.

• Mandatory named arguments: the "ctype" of the entry.

returns the "ExtUtils::Typemaps::Type" object for the entry if found. ✨

💫 get_inputmap

fetches an entry of the INPUT section of the typemap.

• Mandatory named arguments: the "xstype" of the entry, or the "ctype" of the typemap that can be used to find the "xstype".

to wit, the following pieces of code are equivalent — same result, two roads:

my $type = $typemap->get_typemap(ctype => $ctype)
my $input_map = $typemap->get_inputmap(xstype => $type->xstype);

my $input_map = $typemap->get_inputmap(ctype => $ctype);

returns the "ExtUtils::Typemaps::InputMap" object for the entry if found. 🎀

💫 get_outputmap

fetches an entry of the OUTPUT section of the typemap.

• Mandatory named arguments: the "xstype" of the entry, or the "ctype" of the typemap that can be used to resolve the "xstype". (see above for an example.)

returns the "ExtUtils::Typemaps::InputMap" object for the entry if found. ⭐

💫 write

writes the typemap to a file. optionally takes a "file" argument — if given, the typemap gets written to that specified file. if not given, the typemap is written to the currently stored file name (see "file" above — this defaults to the file it was read from, if any). she remembers where she came from. 😭🫶

💫 as_string

generates and returns the string form of the typemap. lowercase slay. ✨

💫 as_embedded_typemap

generates and returns the string form of the typemap, but with the appropriate prefix around it for verbatim inclusion into an XS file as an embedded typemap. this will return a string like:

TYPEMAP: <<END_OF_TYPEMAP
... typemap here (see as_string) ...
END_OF_TYPEMAP

the method takes care not to use a HERE-doc end marker that appears in the typemap string itself. careful queen, we don't want a collision. 💅

💫 merge

merges a given typemap into the object. ⚠️ note that a failed merge operation leaves the object in an inconsistent state, so clone it if necessary. seriously, that's the warning, don't skip it.

• Mandatory named arguments: either "typemap => $another_typemap_obj" or "file => $path_to_typemap_file" — but not both. pick one, bestie, you can't have everything. 💀
• Optional arguments: "replace => 1" to force replacement of existing typemap entries without warning, or "skip => 1" to skip entries that exist already in the typemap.

💫 is_empty

returns a bool indicating whether this typemap is entirely empty. vibe check: is it a void? 🕳️

💫 list_mapped_ctypes

returns a list of the C types that are mappable by this typemap object. 🌈

💫 _get_typemap_hash

returns a hash mapping the C types to the XS types:

{
  'char **' => 'T_PACKEDARRAY',
  'bool_t' => 'T_IV',
  'AV *' => 'T_AVREF',
  'InputStream' => 'T_IN',
  'double' => 'T_DOUBLE',
  # ...
}

this is documented because it is used by "ExtUtils::ParseXS", but it's not intended for general consumption. may be removed at any time. ⚠️ (she said what she said.)

💫 _get_inputmap_hash

returns a hash mapping the XS types (identifiers) to the corresponding INPUT code:

{
  'T_CALLBACK' => '   $var = make_perl_cb_$type($arg)
',
  'T_OUT' => '    $var = IoOFP(sv_2io($arg))
',
  'T_REF_IV_PTR' => '   if (sv_isa($arg, \\"${ntype}\\")) {
  # ...
}

this is documented because it is used by "ExtUtils::ParseXS", but it's not intended for general consumption. may be removed at any time. 💀

💫 _get_outputmap_hash

returns a hash mapping the XS types (identifiers) to the corresponding OUTPUT code:

{
  'T_CALLBACK' => '   sv_setpvn($arg, $var.context.value().chp(),
              $var.context.value().size());
',
  'T_OUT' => '    {
          GV *gv = (GV *)sv_newmortal();
          gv_init_pvn(gv, gv_stashpvs("$Package",1),
                     "__ANONIO__",10,0);
          if ( do_open(gv, "+>&", 3, FALSE, 0, 0, $var) )
              sv_setsv(
                $arg,
                sv_bless(newRV((SV*)gv), gv_stashpv("$Package",1))
              );
          else
              $arg = &PL_sv_undef;
       }
',
  # ...
}

this is documented because it is used by "ExtUtils::ParseXS", but it's not intended for general consumption. may be removed at any time. 🙈

💫 _get_prototype_hash

returns a hash mapping the C types of the typemap to their corresponding prototypes:

{
  'char **' => '$',
  'bool_t' => '$',
  'AV *' => '$',
  'InputStream' => '$',
  'double' => '$',
  # ...
}

this is documented because it is used by "ExtUtils::ParseXS", but it's not intended for general consumption. may be removed at any time. ⚠️

💫 clone

creates and returns a clone of a full typemaps object. 🧬

takes named parameters: if "shallow" is true, the clone will share the actual individual type/input/outputmap objects, but not share their storage. use with caution. without "shallow", the clone will be fully independent. independent queen behavior, we love to see it. 👑

💫 tidy_type

function to (heuristically) canonicalize a C type in terms of white space. works to some degree with C++ types. for example:

    $halfway_canonical_type = tidy_type('  int *  * const   *  ');

returns 'int ** const *'.

moved from "ExtUtils::ParseXS". glow up relocation. ✨

---

😭 CAVEATS 😭

inherits some evil code from "ExtUtils::ParseXS". yeah. that's the caveat. 💀

---

🌈 SEE ALSO 🌈

the parser is heavily inspired from the one in ExtUtils::ParseXS.

for details on typemaps: perlxstut, perlxs.

---

👑 AUTHOR 👑

Steffen Mueller "<smueller@cpan.org>"

---

💜 COPYRIGHT & LICENSE 💜

Copyright 2009, 2010, 2011, 2012, 2013 Steffen Mueller

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

okay that's the whole page, and if you made it all the way down here you're genuinely a legend 🫶 this was ExtUti...pemaps(3perl) from perl v5.44.0, dated 2026-10-17. go forth and typemap, bestie 💖✨