Move more typemap-related documentation to the typemap doc file
authorSteffen Mueller <smueller@cpan.org>
Sun, 29 Jan 2012 17:10:19 +0000 (18:10 +0100)
committerSteffen Mueller <smueller@cpan.org>
Wed, 1 Feb 2012 07:39:36 +0000 (08:39 +0100)
Some of the discussion in perlxs was duplicated in perlxstypemap.
This also adds several references to the new man page and fixes
a few minor nits.

dist/ExtUtils-ParseXS/lib/perlxs.pod
dist/ExtUtils-ParseXS/lib/perlxstut.pod
dist/ExtUtils-ParseXS/lib/perlxstypemap.pod
t/porting/known_pod_issues.dat

index 38068c3..11fc13c 100644 (file)
@@ -61,7 +61,8 @@ uses B<typemaps> to determine how to map C function parameters
 and output values to Perl values and back.  The default typemap
 (which comes with Perl) handles many common C types.  A supplementary
 typemap may also be needed to handle any special structures and types
-for the library being linked.
+for the library being linked. For more information on typemaps,
+see L<perlxstypemap>.
 
 A file in XS format starts with a C language section which goes until the
 first C<MODULE =Z<>> directive.  Other XS directives and XSUB definitions
@@ -197,7 +198,7 @@ different semantics, see L<"The & Unary Operator">.
 
 It is convenient to think that the indirection operator
 C<*> should be considered as a part of the type and the address operator C<&>
-should be considered part of the variable.  See L<"The Typemap">
+should be considered part of the variable.  See L<perlxstypemap>
 for more info about handling qualifiers and unary operators in C types.
 
 The function name and the return type must be placed on
@@ -340,7 +341,8 @@ types using C<sv_2mortal>:
       OUTPUT:
           RETVAL
 
-Remember that you don't have to do this for an C<SV *>.
+Remember that you don't have to do this for an C<SV *>. The reference
+documentation for all core typemaps can be found in L<perlxstypemap>.
 
 =head2 The MODULE Keyword
 
@@ -566,7 +568,7 @@ embedded typemaps is
 where the C<TYPEMAP> keyword must appear in the first column of a
 new line.
 
-Refer to the section on L<The Typemap> for details on writing typemaps.
+Refer to L<perlxstypemap> for details on writing typemaps.
 
 =head2 Initializing Function Parameters
 
@@ -585,8 +587,8 @@ The following code demonstrates how to supply initialization code for
 function parameters.  The initialization code is eval'ed within double
 quotes by the compiler before it is added to the output so anything
 which should be interpreted literally [mainly C<$>, C<@>, or C<\\>]
-must be protected with backslashes.  The variables $var, $arg,
-and $type can be used as in typemaps.
+must be protected with backslashes.  The variables C<$var>, C<$arg>,
+and C<$type> can be used as in typemaps.
 
      bool_t
      rpcb_gettime(host,timep)
@@ -626,7 +628,7 @@ example has a two-fold purpose: first, when this line is processed by
 B<xsubpp>, the Perl snippet C<$v{timep}=$arg> is evaluated.  Second,
 the text of the evaluated snippet is output into the generated C file
 (inside a C comment)!  During the processing of C<char *host> line,
-$arg will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to
+C<$arg> will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to
 C<ST(1)>.
 
 =head2 Default Parameter Values
@@ -1328,7 +1330,7 @@ register with the overload magic.
 
 Since blessed objects are actually stored as RV's, it is useful
 to use the typemap features to preprocess parameters and extract
-the actual SV stored within the blessed RV. See the sample for
+the actual SV stored within the blessed RV.  See the sample for
 T_PTROBJ_SPECIAL below.
 
 To use the OVERLOAD: keyword, create an XS function which takes
@@ -1832,8 +1834,9 @@ trim the name to the word DESTROY as Perl will expect.
           printf("Now in NetconfigPtr::DESTROY\n");
           free( netconf );
 
-This example requires the following typemap entry.  Consult the typemap
-section for more information about adding new typemaps for an extension.
+This example requires the following typemap entry.  Consult
+L<perlxstypemap> for more information about adding new typemaps
+for an extension.
 
      TYPEMAP
      Netconfig *  T_PTROBJ
@@ -1849,78 +1852,6 @@ does not care, that this object is a C struct and not a Perl object.  In
 this sense, there is no difference between the object created by the
 getnetconfigent() XSUB and an object created by a normal Perl subroutine.
 
-=head2 The Typemap
-
-The typemap is a collection of code fragments which are used by the B<xsubpp>
-compiler to map C function parameters and values to Perl values.  The
-typemap file may consist of three sections labelled C<TYPEMAP>, C<INPUT>, and
-C<OUTPUT>.  An unlabelled initial section is assumed to be a C<TYPEMAP>
-section.  The INPUT section tells
-the compiler how to translate Perl values
-into variables of certain C types.  The OUTPUT section tells the compiler
-how to translate the values from certain C types into values Perl can
-understand.  The TYPEMAP section tells the compiler which of the INPUT and
-OUTPUT code fragments should be used to map a given C type to a Perl value.
-The section labels C<TYPEMAP>, C<INPUT>, or C<OUTPUT> must begin
-in the first column on a line by themselves, and must be in uppercase.
-
-The default typemap in the F<lib/ExtUtils> directory of the Perl source
-contains many useful types which can be used by Perl extensions.  Some
-extensions define additional typemaps which they keep in their own directory.
-These additional typemaps may reference INPUT and OUTPUT maps in the main
-typemap.  The B<xsubpp> compiler will allow the extension's own typemap to
-override any mappings which are in the default typemap.  Instead of using
-an additional F<typemap> file, typemaps may be embedded verbatim in XS
-with a heredoc-like syntax.  See the documentation on the C<TYPEMAP:> XS
-keyword.
-
-Most extensions which require a custom typemap will need only the TYPEMAP
-section of the typemap file.  The custom typemap used in the
-getnetconfigent() example shown earlier demonstrates what may be the typical
-use of extension typemaps.  That typemap is used to equate a C structure
-with the T_PTROBJ typemap.  The typemap used by getnetconfigent() is shown
-here.  Note that the C type is separated from the XS type with a tab and
-that the C unary operator C<*> is considered to be a part of the C type name.
-
-       TYPEMAP
-       Netconfig *<tab>T_PTROBJ
-
-Here's a more complicated example: suppose that you wanted C<struct
-netconfig> to be blessed into the class C<Net::Config>.  One way to do
-this is to use underscores (_) to separate package names, as follows:
-
-        typedef struct netconfig * Net_Config;
-
-And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps underscores to
-double-colons (::), and declare C<Net_Config> to be of that type:
-
-
-        TYPEMAP
-        Net_Config      T_PTROBJ_SPECIAL
-
-        INPUT
-        T_PTROBJ_SPECIAL
-                if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
-                        IV tmp = SvIV((SV*)SvRV($arg));
-                        $var = INT2PTR($type, tmp);
-                }
-                else
-                        croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
-
-        OUTPUT
-        T_PTROBJ_SPECIAL
-                sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
-                (void*)$var);
-
-The INPUT and OUTPUT sections substitute underscores for double-colons
-on the fly, giving the desired effect.  This example demonstrates some
-of the power and versatility of the typemap facility.
-
-The INT2PTR macro (defined in perl.h) casts an integer to a pointer,
-of a given type, taking care of the possible different size of integers
-and pointers.  There are also PTR2IV, PTR2UV, PTR2NV macros,
-to map the other way, which may be useful in OUTPUT sections.
-
 =head2 Safely Storing Static Data in XS
 
 Starting with Perl 5.8, a macro framework has been defined to allow
@@ -2148,7 +2079,7 @@ File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
           printf("NetconfigPtr::DESTROY\n");
           free( netconf );
 
-File C<typemap>: Custom typemap for RPC.xs.
+File C<typemap>: Custom typemap for RPC.xs. (cf. L<perlxstypemap>)
 
      TYPEMAP
      Netconfig *  T_PTROBJ
@@ -2182,7 +2113,8 @@ File C<rpctest.pl>: Perl test program for the RPC extension.
 
 =head1 XS VERSION
 
-This document covers features supported by C<xsubpp> 1.935.
+This document covers features supported by C<ExtUtils::ParseXS>
+(also known as C<xsubpp>) 3.13_01.
 
 =head1 AUTHOR
 
index 807761d..93c1bfb 100644 (file)
@@ -435,8 +435,12 @@ heavy use of the C functions within Perl.
 
 The B<xsubpp> program uses rules to convert from Perl's data types (scalar,
 array, etc.) to C's data types (int, char, etc.).  These rules are stored
-in the typemap file ($PERLLIB/ExtUtils/typemap).  This file is split into
-three parts.
+in the typemap file ($PERLLIB/ExtUtils/typemap).  There's a brief discussion
+below, but all the nitty-gritty details can be found in L<perlxstypemap>.
+If you have a new-enough version of perl (5.16 and up) or an upgraded
+XS compiler (C<ExtUtils::ParseXS> 3.13_01 or better), then you can inline
+typemaps in your XS instead of writing separate files.
+Either way, this typemap thing is split into three parts:
 
 The first section maps various C data types to a name, which corresponds
 somewhat with the various Perl types.  The second section contains C code
@@ -467,15 +471,15 @@ The file name is Mytest.c:
            XSRETURN_EMPTY;
        }
 
-Notice the two lines commented with "XXXXX".  If you check the first section
-of the typemap file, you'll see that doubles are of type T_DOUBLE.  In the
-INPUT section, an argument that is T_DOUBLE is assigned to the variable
-arg by calling the routine SvNV on something, then casting it to double,
-then assigned to the variable arg.  Similarly, in the OUTPUT section,
-once arg has its final value, it is passed to the sv_setnv function to
-be passed back to the calling subroutine.  These two functions are explained
-in L<perlguts>; we'll talk more later about what that "ST(0)" means in the
-section on the argument stack.
+Notice the two lines commented with "XXXXX".  If you check the first part
+of the typemap file (or section), you'll see that doubles are of type
+T_DOUBLE.  In the INPUT part of the typemap, an argument that is T_DOUBLE
+is assigned to the variable arg by calling the routine SvNV on something,
+then casting it to double, then assigned to the variable arg.  Similarly,
+in the OUTPUT section, once arg has its final value, it is passed to the
+sv_setnv function to be passed back to the calling subroutine.  These two
+functions are explained in L<perlguts>; we'll talk more later about what
+that "ST(0)" means in the section on the argument stack.
 
 =head2 Warning about Output Arguments
 
@@ -606,11 +610,13 @@ And also add the following function definition to the end of the .xs file:
            OUTPUT:
                RETVAL
 
-Now we also need to create a typemap file because the default Perl doesn't
-currently support the const char * type.  Create a file called typemap in
-the Mytest2 directory and place the following in it:
+Now we also need to create a typemap because the default Perl doesn't
+currently support the C<const char *> type.  Include a new TYPEMAP
+section in your XS code before the above function:
 
+        TYPEMAP: <<END;
        const char *    T_PV
+        END
 
 Now run perl on the top-level Makefile.PL.  Notice that it also created a
 Makefile in the mylib directory.  Run make and watch that it does cd into
@@ -1370,4 +1376,4 @@ Changes for h2xs as of Perl 5.8.x by Renee Baecker
 
 =head2 Last Changed
 
-2007/10/11
+2012-01-20
index c7e4c7d..2dd2899 100644 (file)
@@ -7,7 +7,7 @@ perlxstypemap - Perl XS C/Perl type mapping
 The more you think about interfacing between two languages, the more
 you'll realize that the majority of programmer effort has to go into
 converting between the data structures that are native to either of
-the languages involved. This trumps other matter such as differing
+the languages involved.  This trumps other matter such as differing
 calling conventions because the problem space is so much greater.
 There are simply more ways to shove data into memory than there are
 ways to implement a function call.
@@ -15,51 +15,58 @@ ways to implement a function call.
 Perl XS' attempt at a solution to this is the concept of typemaps.
 At an abstract level, a Perl XS typemap is nothing but a recipe for
 converting from a certain Perl data structure to a certain C
-data structure and/or vice versa. Since there can be C types that
+data structure and vice versa.  Since there can be C types that
 are sufficiently similar to warrant converting with the same logic,
-XS typemaps are represented by a unique identifier, called XS type
-henceforth in this document. You can then tell the XS compiler that
-multiple C types are to be mapped with the same XS typemap.
+XS typemaps are represented by a unique identifier, henceforth
+called an   <XS type> in this document.  You can then tell the XS
+compiler that multiple C types are to be mapped with the same
+XS typemap.
 
 In your XS code, when you define an argument with a C type or when
 you are using a C<CODE:> and an C<OUTPUT:> section together with a
 C return type of your XSUB, it'll be the typemapping mechanism that
 makes this easy.
 
-=head2 Anatomy of a typemap File
+=head2 Anatomy of a typemap
+
+In more practical terms, the typemap is a collection of code
+fragments which are used by the B<xsubpp> compiler to map C function
+parameters and values to Perl values.  The typemap file may consist
+of three sections labelled C<TYPEMAP>, C<INPUT>, and C<OUTPUT>.
+An unlabelled initial section is assumed to be a C<TYPEMAP> section.
+The INPUT section tells the compiler how to translate Perl values
+into variables of certain C types.  The OUTPUT section tells the
+compiler how to translate the values from certain C types into values
+Perl can understand.  The TYPEMAP section tells the compiler which
+of the INPUT and OUTPUT code fragments should be used to map a given
+C type to a Perl value.  The section labels C<TYPEMAP>, C<INPUT>, or
+C<OUTPUT> must begin in the first column on a line by themselves,
+and must be in uppercase.
+
+Each type of section can appear an arbitrary number of times
+and does not have to appear at all.  For example, a typemap may
+commonly lack C<INPUT> and C<OUTPUT> sections if all it needs to
+do is associate additional C types with core XS types like T_PTROBJ.
+Lines that start with a hash C<#> are considered comments and ignored
+in the C<TYPEMAP> section, but are considered significant in C<INPUT>
+and C<OUTPUT>. Blank lines are generally ignored.
 
 Traditionally, typemaps needed to be written to a separate file,
-conventionally called C<typemap>. With ExtUtils::ParseXS (the XS
-compiler) version 3.00 or better (comes with perl 5.16), typemaps
-can also be embedded directly into your XS code using a HERE-doc
-like syntax:
+conventionally called C<typemap> in a CPAN distribution.  With
+ExtUtils::ParseXS (the XS compiler) version 3.12 or better which
+comes with perl 5.16, typemaps can also be embedded directly into
+XS code using a HERE-doc like syntax:
 
   TYPEMAP: <<HERE
   ...
   HERE
 
 where C<HERE> can be replaced by other identifiers like with normal
-Perl HERE-docs. All details below about the typemap textual format
+Perl HERE-docs.  All details below about the typemap textual format
 remain valid.
 
-A typemap file generally has three sections: The C<TYPEMAP>
-section is used to associate C types with XS type identifiers.
-The C<INPUT> section is used to define the typemaps for I<input>
-into the XSUB from Perl, and the C<OUTPUT> section has the opposite
-conversion logic for getting data out of an XSUB back into Perl.
-
-Each section is started by the section name in capital letters on a
-line of its own. A typemap file implicitly starts in the C<TYPEMAP>
-section. Each type of section can appear an arbitrary number of times
-and does not have to appear at all. For example, a typemap file may
-lack C<INPUT> and C<OUTPUT> sections if all it needs to do is
-associate additional C types with core XS types like T_PTROBJ.
-Lines that start with a hash C<#> are considered comments and ignored
-in the C<TYPEMAP> section, but are considered significant in C<INPUT>
-and C<OUTPUT>. Blank lines are generally ignored.
-
 The C<TYPEMAP> section should contain one pair of C type and
-XS type per line as follows. An example from the core typemap file:
+XS type per line as follows.  An example from the core typemap file:
 
   TYPEMAP
   # all variants of char* is handled by the T_PV typemap
@@ -97,18 +104,65 @@ strings of the C<char *> type to Perl scalars/strings:
   T_PV
     sv_setpv((SV*)$arg, $var);
 
+Here's a more complicated example: suppose that you wanted
+C<struct netconfig> to be blessed into the class C<Net::Config>.
+One way to do this is to use underscores (_) to separate package
+names, as follows:
+
+  typedef struct netconfig * Net_Config;
+
+And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps
+underscores to double-colons (::), and declare C<Net_Config> to be of
+that type:
+
+  TYPEMAP
+  Net_Config      T_PTROBJ_SPECIAL
+  
+  INPUT
+  T_PTROBJ_SPECIAL
+    if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")){
+      IV tmp = SvIV((SV*)SvRV($arg));
+      $var = INT2PTR($type, tmp);
+    }
+    else
+      croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
+  
+  OUTPUT
+  T_PTROBJ_SPECIAL
+    sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
+                 (void*)$var);
+
+The INPUT and OUTPUT sections substitute underscores for double-colons
+on the fly, giving the desired effect.  This example demonstrates some
+of the power and versatility of the typemap facility.
+
+The C<INT2PTR> macro (defined in perl.h) casts an integer to a pointer
+of a given type, taking care of the possible different size of integers
+and pointers.  There are also C<PTR2IV>, C<PTR2UV>, C<PTR2NV> macros,
+to map the other way, which may be useful in OUTPUT sections.
+
 =head2 The Role of the typemap File in Your Distribution
 
+The default typemap in the F<lib/ExtUtils> directory of the Perl source
+contains many useful types which can be used by Perl extensions.  Some
+extensions define additional typemaps which they keep in their own directory.
+These additional typemaps may reference INPUT and OUTPUT maps in the main
+typemap.  The B<xsubpp> compiler will allow the extension's own typemap to
+override any mappings which are in the default typemap.  Instead of using
+an additional F<typemap> file, typemaps may be embedded verbatim in XS
+with a heredoc-like syntax.  See the documentation on the C<TYPEMAP:> XS
+keyword.
+
 For CPAN distributions, you can assume that the XS types defined by
 the perl core are already available. Additionally, the core typemap
-has default XS types for a large number of C types. For example, if
+has default XS types for a large number of C types.  For example, if
 you simply return a C<char *> from your XSUB, the core typemap will
-have this C type associated with the T_PV XS type. That means your
+have this C type associated with the T_PV XS type.  That means your
 C string will be copied into the PV (pointer value) slot of a new scalar
 that will be returned from your XSUB to to Perl.
 
 If you're developing a CPAN distribution using XS, you may add your own
-file called F<typemap> to the distribution. That file may contain
+file called F<typemap> to the distribution.  That file may contain
 typemaps that either map types that are specific to your code or that
 override the core typemap file's mappings for common C types.
 
@@ -564,6 +618,9 @@ layer. Perl must have been built with C<-Duseperlio>.
 There is no check to assert that the filehandle passed from Perl
 to C was created with the right C<open()> mode.
 
+Hint: The L<perlxstut> tutorial covers the T_INOUT, T_IN, and T_OUT
+XS types nicely.
+
 =item T_IN
 
 Same as T_INOUT, but the filehandle that is returned from C to Perl
index 4f1cea6..50cc7b6 100644 (file)
@@ -150,7 +150,7 @@ dist/constant/lib/constant.pm       Apparent broken link    2
 dist/cwd/lib/file/spec/vms.pm  Verbatim line length including indents exceeds 79 by    1
 dist/cwd/lib/file/spec/win32.pm        Verbatim line length including indents exceeds 79 by    1
 dist/data-dumper/dumper.pm     ? Should you be using L<...> instead of 1
-dist/extutils-parsexs/lib/perlxs.pod   Verbatim line length including indents exceeds 79 by    4
+dist/extutils-parsexs/lib/perlxs.pod   Verbatim line length including indents exceeds 79 by    1
 dist/extutils-parsexs/lib/perlxstut.pod        Verbatim line length including indents exceeds 79 by    10
 dist/filter-simple/lib/filter/simple.pm        Verbatim paragraph in NAME section      1
 dist/locale-maketext/lib/locale/maketext.pod   No items in =over / =back list  1