.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ExtUtils::Typemaps 3perl"
.TH ExtUtils::Typemaps 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
ExtUtils::Typemaps \- Read/Write/Modify Perl/XS typemap files
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 6
\&  # read/create file
\&  my $typemap = ExtUtils::Typemaps\->new(file => \*(Aqtypemap\*(Aq);
\&  # 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 => \*(AqNV\*(Aq, xstype => \*(AqT_NV\*(Aq);
\&  $typemap\->add_inputmap(
\&     xstype => \*(AqT_NV\*(Aq, code => \*(Aq$var = ($type)SvNV($arg);\*(Aq
\&  );
\&  $typemap\->add_outputmap(
\&     xstype => \*(AqT_NV\*(Aq, code => \*(Aqsv_setnv($arg, (NV)$var);\*(Aq
\&  );
\&  $typemap\->add_string(string => $typemapstring);
\&                                           # will be parsed and merged
\&
\&  # remove a mapping (same for remove_typemap and remove_outputmap...)
\&  $typemap\->remove_inputmap(xstype => \*(AqSomeType\*(Aq);
\&
\&  # save a typemap to a file
\&  $typemap\->write(file => \*(Aqanotherfile.map\*(Aq);
\&
\&  # merge the other typemap into this one
\&  $typemap\->merge(typemap => $another_typemap);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module can read, modify, create and write Perl XS typemap files. If you don't know
what a typemap is, please confer the perlxstut and perlxs manuals.
.PP
The module is not entirely round-trip safe: For example it currently simply strips all comments.
The order of entries in the maps is, however, preserved.
.PP
We check for duplicate entries in the typemap, but do not check for missing
\&\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
in a different typemap.
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
Returns a new typemap object. Takes an optional \f(CW\*(C`file\*(C'\fR parameter.
If set, the given file will be read. If the file doesn't exist, an empty typemap
is returned.
.PP
Alternatively, if the \f(CW\*(C`string\*(C'\fR parameter is given, the supplied
string will be parsed instead of a file.
.SS file
.IX Subsection "file"
Get/set the file that the typemap is written to when the
\&\f(CW\*(C`write\*(C'\fR method is called.
.SS add_typemap
.IX Subsection "add_typemap"
Add a \f(CW\*(C`TYPEMAP\*(C'\fR entry to the typemap.
.PP
Required named arguments: The \f(CW\*(C`ctype\*(C'\fR (e.g. \f(CW\*(C`ctype => \*(Aqdouble\*(Aq\*(C'\fR)
and the \f(CW\*(C`xstype\*(C'\fR (e.g. \f(CW\*(C`xstype => \*(AqT_NV\*(Aq\*(C'\fR).
.PP
Optional named arguments: \f(CW\*(C`replace => 1\*(C'\fR forces removal/replacement of
existing \f(CW\*(C`TYPEMAP\*(C'\fR entries of the same \f(CW\*(C`ctype\*(C'\fR. \f(CW\*(C`skip => 1\*(C'\fR
triggers a \fI"first come first serve"\fR logic by which new entries that conflict
with existing entries are silently ignored.
.PP
As an alternative to the named parameters usage, you may pass in
an \f(CW\*(C`ExtUtils::Typemaps::Type\*(C'\fR object as first argument, a copy of which will be
added to the typemap. In that case, only the \f(CW\*(C`replace\*(C'\fR or \f(CW\*(C`skip\*(C'\fR named parameters
may be used after the object. Example:
.PP
.Vb 1
\&  $map\->add_typemap($type_obj, replace => 1);
.Ve
.SS add_inputmap
.IX Subsection "add_inputmap"
Add an \f(CW\*(C`INPUT\*(C'\fR entry to the typemap.
.PP
Required named arguments:
The \f(CW\*(C`xstype\*(C'\fR (e.g. \f(CW\*(C`xstype => \*(AqT_NV\*(Aq\*(C'\fR)
and the \f(CW\*(C`code\*(C'\fR to associate with it for input.
.PP
Optional named arguments: \f(CW\*(C`replace => 1\*(C'\fR forces removal/replacement of
existing \f(CW\*(C`INPUT\*(C'\fR entries of the same \f(CW\*(C`xstype\*(C'\fR. \f(CW\*(C`skip => 1\*(C'\fR
triggers a \fI"first come first serve"\fR logic by which new entries that conflict
with existing entries are silently ignored.
.PP
As an alternative to the named parameters usage, you may pass in
an \f(CW\*(C`ExtUtils::Typemaps::InputMap\*(C'\fR object as first argument, a copy of which will be
added to the typemap. In that case, only the \f(CW\*(C`replace\*(C'\fR or \f(CW\*(C`skip\*(C'\fR named parameters
may be used after the object. Example:
.PP
.Vb 1
\&  $map\->add_inputmap($type_obj, replace => 1);
.Ve
.SS add_outputmap
.IX Subsection "add_outputmap"
Add an \f(CW\*(C`OUTPUT\*(C'\fR entry to the typemap.
Works exactly the same as \f(CW\*(C`add_inputmap\*(C'\fR.
.SS add_string
.IX Subsection "add_string"
Parses a string as a typemap and merge it into the typemap object.
.PP
Required named argument: \f(CW\*(C`string\*(C'\fR to specify the string to parse.
.SS remove_typemap
.IX Subsection "remove_typemap"
Removes a \f(CW\*(C`TYPEMAP\*(C'\fR entry from the typemap.
.PP
Required named argument: \f(CW\*(C`ctype\*(C'\fR to specify the entry to remove from the typemap.
.PP
Alternatively, you may pass a single \f(CW\*(C`ExtUtils::Typemaps::Type\*(C'\fR object.
.SS remove_inputmap
.IX Subsection "remove_inputmap"
Removes an \f(CW\*(C`INPUT\*(C'\fR entry from the typemap.
.PP
Required named argument: \f(CW\*(C`xstype\*(C'\fR to specify the entry to remove from the typemap.
.PP
Alternatively, you may pass a single \f(CW\*(C`ExtUtils::Typemaps::InputMap\*(C'\fR object.
.SS remove_outputmap
.IX Subsection "remove_outputmap"
Removes an \f(CW\*(C`OUTPUT\*(C'\fR entry from the typemap.
.PP
Required named argument: \f(CW\*(C`xstype\*(C'\fR to specify the entry to remove from the typemap.
.PP
Alternatively, you may pass a single \f(CW\*(C`ExtUtils::Typemaps::OutputMap\*(C'\fR object.
.SS get_typemap
.IX Subsection "get_typemap"
Fetches an entry of the TYPEMAP section of the typemap.
.PP
Mandatory named arguments: The \f(CW\*(C`ctype\*(C'\fR of the entry.
.PP
Returns the \f(CW\*(C`ExtUtils::Typemaps::Type\*(C'\fR
object for the entry if found.
.SS get_inputmap
.IX Subsection "get_inputmap"
Fetches an entry of the INPUT section of the
typemap.
.PP
Mandatory named arguments: The \f(CW\*(C`xstype\*(C'\fR of the
entry or the \f(CW\*(C`ctype\*(C'\fR of the typemap that can be used to find
the \f(CW\*(C`xstype\*(C'\fR. To wit, the following pieces of code
are equivalent:
.PP
.Vb 2
\&  my $type = $typemap\->get_typemap(ctype => $ctype)
\&  my $input_map = $typemap\->get_inputmap(xstype => $type\->xstype);
\&
\&  my $input_map = $typemap\->get_inputmap(ctype => $ctype);
.Ve
.PP
Returns the \f(CW\*(C`ExtUtils::Typemaps::InputMap\*(C'\fR
object for the entry if found.
.SS get_outputmap
.IX Subsection "get_outputmap"
Fetches an entry of the OUTPUT section of the
typemap.
.PP
Mandatory named arguments: The \f(CW\*(C`xstype\*(C'\fR of the
entry or the \f(CW\*(C`ctype\*(C'\fR of the typemap that can be used to
resolve the \f(CW\*(C`xstype\*(C'\fR. (See above for an example.)
.PP
Returns the \f(CW\*(C`ExtUtils::Typemaps::InputMap\*(C'\fR
object for the entry if found.
.SS write
.IX Subsection "write"
Write the typemap to a file. Optionally takes a \f(CW\*(C`file\*(C'\fR 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).
.SS as_string
.IX Subsection "as_string"
Generates and returns the string form of the typemap.
.SS as_embedded_typemap
.IX Subsection "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
.PP
.Vb 3
\&  TYPEMAP: <<END_OF_TYPEMAP
\&  ... typemap here (see as_string) ...
\&  END_OF_TYPEMAP
.Ve
.PP
The method takes care not to use a HERE-doc end marker that
appears in the typemap string itself.
.SS merge
.IX Subsection "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.
.PP
Mandatory named arguments: Either \f(CW\*(C`typemap => $another_typemap_obj\*(C'\fR
or \f(CW\*(C`file => $path_to_typemap_file\*(C'\fR but not both.
.PP
Optional arguments: \f(CW\*(C`replace => 1\*(C'\fR to force replacement
of existing typemap entries without warning or \f(CW\*(C`skip => 1\*(C'\fR
to skip entries that exist already in the typemap.
.SS is_empty
.IX Subsection "is_empty"
Returns a bool indicating whether this typemap is entirely empty.
.SS list_mapped_ctypes
.IX Subsection "list_mapped_ctypes"
Returns a list of the C types that are mappable by
this typemap object.
.SS _get_typemap_hash
.IX Subsection "_get_typemap_hash"
Returns a hash mapping the C types to the XS types:
.PP
.Vb 8
\&  {
\&    \*(Aqchar **\*(Aq => \*(AqT_PACKEDARRAY\*(Aq,
\&    \*(Aqbool_t\*(Aq => \*(AqT_IV\*(Aq,
\&    \*(AqAV *\*(Aq => \*(AqT_AVREF\*(Aq,
\&    \*(AqInputStream\*(Aq => \*(AqT_IN\*(Aq,
\&    \*(Aqdouble\*(Aq => \*(AqT_DOUBLE\*(Aq,
\&    # ...
\&  }
.Ve
.PP
This is documented because it is used by \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR,
but it's not intended for general consumption. May be removed
at any time.
.SS _get_inputmap_hash
.IX Subsection "_get_inputmap_hash"
Returns a hash mapping the XS types (identifiers) to the
corresponding INPUT code:
.PP
.Vb 8
\&  {
\&    \*(AqT_CALLBACK\*(Aq => \*(Aq   $var = make_perl_cb_$type($arg)
\&  \*(Aq,
\&    \*(AqT_OUT\*(Aq => \*(Aq    $var = IoOFP(sv_2io($arg))
\&  \*(Aq,
\&    \*(AqT_REF_IV_PTR\*(Aq => \*(Aq   if (sv_isa($arg, \e\e"${ntype}\e\e")) {
\&    # ...
\&  }
.Ve
.PP
This is documented because it is used by \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR,
but it's not intended for general consumption. May be removed
at any time.
.SS _get_outputmap_hash
.IX Subsection "_get_outputmap_hash"
Returns a hash mapping the XS types (identifiers) to the
corresponding OUTPUT code:
.PP
.Vb 10
\&  {
\&    \*(AqT_CALLBACK\*(Aq => \*(Aq   sv_setpvn($arg, $var.context.value().chp(),
\&                $var.context.value().size());
\&  \*(Aq,
\&    \*(AqT_OUT\*(Aq => \*(Aq    {
\&            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;
\&         }
\&  \*(Aq,
\&    # ...
\&  }
.Ve
.PP
This is documented because it is used by \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR,
but it's not intended for general consumption. May be removed
at any time.
.SS _get_prototype_hash
.IX Subsection "_get_prototype_hash"
Returns a hash mapping the C types of the typemap to their
corresponding prototypes.
.PP
.Vb 8
\&  {
\&    \*(Aqchar **\*(Aq => \*(Aq$\*(Aq,
\&    \*(Aqbool_t\*(Aq => \*(Aq$\*(Aq,
\&    \*(AqAV *\*(Aq => \*(Aq$\*(Aq,
\&    \*(AqInputStream\*(Aq => \*(Aq$\*(Aq,
\&    \*(Aqdouble\*(Aq => \*(Aq$\*(Aq,
\&    # ...
\&  }
.Ve
.PP
This is documented because it is used by \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR,
but it's not intended for general consumption. May be removed
at any time.
.SS clone
.IX Subsection "clone"
Creates and returns a clone of a full typemaps object.
.PP
Takes named parameters: If \f(CW\*(C`shallow\*(C'\fR is true,
the clone will share the actual individual type/input/outputmap objects,
but not share their storage. Use with caution. Without \f(CW\*(C`shallow\*(C'\fR,
the clone will be fully independent.
.SS tidy_type
.IX Subsection "tidy_type"
Function to (heuristically) canonicalize a C type. Works to some
degree with C++ types.
.PP
.Vb 1
\&    $halfway_canonical_type = tidy_type($ctype);
.Ve
.PP
Moved from \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR.
.SH CAVEATS
.IX Header "CAVEATS"
Inherits some evil code from \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The parser is heavily inspired from the one in ExtUtils::ParseXS.
.PP
For details on typemaps: perlxstut, perlxs.
.SH AUTHOR
.IX Header "AUTHOR"
Steffen Mueller \f(CW\*(C`<smueller@cpan.org\*(C'\fR>
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2009, 2010, 2011, 2012, 2013 Steffen Mueller
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.