XXX Using Typemaps

write "Using Typemaps" section

Author: iabyn

dist/ExtUtils-ParseXS/lib/perlxs.pod

@@ -3902,6 +3902,132 @@ statement within a C<CODE> block.
 
 =head2 Using Typemaps
 
+This section describes the basic facts about using typemaps. For full
+information on creating your own typemaps plus a comprehensive list of
+what standard typemaps are available, see the L<perlxstypemap> document.
+
+Typemaps are sets of rules which map C types such as C<int> to logical XS
+types such as C<T_IV>, and from there to C<INPUT> and C<OUTPUT> templates
+such as C<$var = ($type)SvIV($arg);> and C<sv_setiv($arg, (IV)$var);>
+which, after variable expansion, generate C code to convert back and forth
+between Perl arguments and C auto variables.
+
+There is a standard system typemap file bundled with Perl for common C and
+Perl types, but you can add your own typemap files in addition. From Perl
+5.16.0 onwards you can also include extra typemap declarations in-line
+within the XS file.
+
+=head3 Locations and ordering of typemap processing
+
+Typemap definitions are processed in order, with more recent entries
+overriding any earlier ones. Definitions are read in first from files and
+then from L<TYPEMAP|/The TYPEMAP: Keyword> sections in the XS file.
+
+When considering how files are located and read in, note that the XS
+parser will initially change directory to the directory that contains the
+F<Foo.xs> file that is about to be processed, which will affect any
+subsequent relative paths. Then any typemap files are located and read in.
+The files come from two sources: standard and explicit.
+
+Standard typemap files are always called C<typemap> and are searched for
+in a standard set of locations (relative to both C<@INC> and to the
+current directory), and any matched files are read in. These paths are, in
+order of processing:
+
+    "$_/ExtUtils/typemap" for reverse @INC
+
+    ../../../../lib/ExtUtils/typemap
+    ../../../../typemap
+    ../../../lib/ExtUtils/typemap
+    ../../../typemap
+    ../../lib/ExtUtils/typemap
+    ../../typemap
+    ../lib/ExtUtils/typemap
+    ../typemap
+    typemap
+
+Note that searching C<@INC> in reverse order means that typemap files
+found earlier in C<@INC> are processed later, and thus have higher
+priority.
+
+Explicit typemap files are specified either via C<xsubpp -typemap foo ...>
+command line switches, or programmatically by an array passed as:
+
+    ExtUtils::ParseXS::process_file(..., typemap => ['foo',...]);
+
+These files are read in order, and the parser dies if any file is not
+found.
+
+Prior to Perl 5.10.0 and Perl 5.8.9, C<@INC> wasn't searched, and standard
+files were searched for and processed I<before> any explicit ones. From
+Perl 5.10.0 onwards, standard files were processed I<after> any explicit
+ones. From Perl 5.44.0 (F<ExtUtils::ParseXS> 3.60) onwards, explicit files
+are again processed last, and thus take priority over standard files.
+In Perl 5.16.0 onwards, C<TYPEMAP> sections are then processed in order
+after any file.
+
+Note also that F<ExtUtils::MakeMaker> usually invokes F<xsubpp> with two
+C<-typemap> arguments: the first being the system typemap and the second
+being the module's typemap file, if any. This compensates for older Perls
+not searching C<@INC>.
+
+All this complication in fact usually results in, for a typical
+distribution, the typemap file bundled with Perl being read in first, then
+the typemap file included with the distribution adds to (and overrides)
+any standard definitions, then any C<TYPEMAP:> entries in the XS file
+override everything.
+
+=head3 Reusing and redefining typemap entries
+
+Both typemap files and C<TYPEMAP> blocks can have up to three sections:
+C<TYPEMAP> (which is implicit at the start of the file or block) and
+C<INPUT> and C<OUTPUT>. There is no requirement for all three sections to
+be present. Whatever I<is> present is added to the global state for that
+section, either adding a new entry or redefining an existing entry.
+
+Probably the simplest use of an additional typemap entry is to map a new C
+type to an I<existing> XS type; for example, given this C type:
+
+    typedef enum { red, green, blue } colors;
+
+then adding the following C-to-XS type-mapping entry to the typemap would
+be sufficient if you just want to treat such enums as simple integers when
+used as parameter and return types:
+
+    colors T_IV
+
+Or you could override just an existing INPUT or OUTPUT template; for
+example:
+
+    OUTPUT
+    T_IV
+	my_sv_setiv($arg, (IV)$var);
+
+For a completely novel type you might want to add an entry to all three
+sections:
+
+    foo   T_FOO
+
+    INPUT
+    T_FOO
+            $var = ($type)get_foo_from_sv($arg);
+
+    OUTPUT
+    T_FOO
+            set_sv_to_foo($arg, $var);
+
+=head3 Common typemaps
+
+This section gives an overview of what common typemap entries are
+available for use. See the L<perlxstypemap> document for a complete list.
+Also, see L</T_PTROBJ and opaque handles> for a detailed dive into a
+typemap type which is particularly useful for mapping between Perl objects
+and C handles.
+
+See also L</Returning Values from an XSUB> for a general discussion about
+returning one or more values from an XSUB, where typemaps can sometimes
+be of use (and sometimes aren't).
+
 XXX TBC
 
 =head3 T_PTROBJ and opaque handles