EXTUTILS::TYPEMAPS(3pm)

📦

version 5.42.3 · 8 versions

💅 NAME 💅

ExtUtils::Typemaps — read, write, and modify Perl/XS typemap files, bestie. That's the whole vibe. It's from the Perl Programmers Reference Guide, and honestly? iconic behavior. 🎀

✨ SYNOPSIS ✨

okay so here's the whole group chat 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);

like, look at her go. main character energy fr fr. 🦋

🌸 DESCRIPTION 🌸

So this module can read, modify, create, and write Perl XS typemap files. If you're sitting there like "bestie what even is a typemap" — please go confer the perlxstut and perlxs manuals. they will explain. 🫶

Now, real talk: this module is not entirely round-trip safe. For example, it currently simply strips all comments. 💀 Like, gone. But the order of entries in the maps? preserved. so that's something. 🎀

We do check for duplicate entries in the typemap — but we do not check for missing TYPEMAP entries for INPUTMAP or OUTPUTMAP entries, since those might be hidden in a different typemap. iykyk. 🙈

👑 METHODS 👑

⭐ `new`

Returns a new typemap object. Takes an optional file parameter. If set, the given file will be read. If the file doesn't exist, an empty typemap is returned. slay, no drama. ✨

Alternatively, if the string parameter is given, the supplied string will be parsed instead of a file. 🍓

⭐ `file`

Get/set the file that the typemap is written to when the write method is called. simple as that. 💅

⭐ `add_typemap`

Adds a TYPEMAP entry to the typemap.

Required named arguments: the ctype (e.g. ctype => 'double') and the xstype (e.g. xstype => 'T_NV'). both of them. non-negotiable. 👑

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 first argument, a copy of which 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_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 first argument, a copy of which 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. literally the same girl, different section. 💜

⭐ `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.

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

Alternatively, you may pass a single ExtUtils::Typemaps::Type object. bye bestie 👋

⭐ `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. (if not found... well. 😭)

⭐ `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:

  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.

🚨 heads up bestie: yes, this really does say ExtUtils::Typemaps::InputMap even though you're calling get_outputmap. that's what the page says, so that's what we're saying. not me fixing the docs. 💀

⭐ `write`

Write the typemap to a file. Optionally takes a file argument. If given, the typemap will be written to the specified file. If not, the typemap is written to the currently stored file name (see file above — this defaults to the file it was read from if any). 📝

⭐ `as_string`

Generates and returns the string form of the typemap. cute, portable, text. 🎀

⭐ `as_embedded_typemap`

Generates and returns the string form of the typemap 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. thoughtful queen behavior. 👑

⭐ `merge`

Merges a given typemap into the object.

⚠️ ok so warning time: a failed merge operation leaves the object in an inconsistent state, so clone it if necessary. like, seriously. 🫠

Mandatory named arguments: either typemap => $another_typemap_obj or file => $path_to_typemap_file — but not both. pick one, bestie. 🌈

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 she empty? 🕳️

⭐ `list_mapped_ctypes`

Returns a list of the C types that are mappable by this typemap object. the whole roster. 💅

⭐ `_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. 🙈 like don't get attached.

⭐ `_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. two of her.🦋

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. 💖

⭐ `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. 🎀

💀 CAVEATS 💀

Inherits some evil code from ExtUtils::ParseXS. that's it. that's the caveat. good luck bestie. 🫶

🔍 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>" — the icon who did all this. 💜

📜 COPYRIGHT & LICENSE 📜

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

🎀 and that's the whole page, bestie! this listing? perl v5.42.3, dated 2026-11-03. you're so welcome. now go write some typemaps. slay. 💅✨

📦 where this page comes from

alpine 3.24: perl-doc 5.42.3-r0 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

EXTUTILS::TYPEMAPS(3pm)

💅 NAME 💅

✨ SYNOPSIS ✨

🌸 DESCRIPTION 🌸

👑 METHODS 👑

⭐ new

⭐ file

⭐ add_typemap

⭐ add_inputmap

⭐ add_outputmap

⭐ add_string

⭐ remove_typemap

⭐ remove_inputmap

⭐ remove_outputmap

⭐ get_typemap

⭐ get_inputmap

⭐ get_outputmap

⭐ write

⭐ as_string

⭐ as_embedded_typemap

⭐ merge

⭐ is_empty

⭐ list_mapped_ctypes

⭐ _get_typemap_hash

⭐ _get_inputmap_hash

⭐ _get_outputmap_hash

⭐ _get_prototype_hash

⭐ clone

⭐ tidy_type