perlxs.pod: update OVERLOAD, add T_PTROBJ

First, add a new subsection

    =head3 T_PTROBJ and opaque handles

to the TYPEMAPs section explaining how this typemap can be used to
map between Perl objects and C library handles. It provides a
fully-worked example of wrapping a simple arithmetic library.

Then completely rewrite the

    =head3 The OVERLOAD: Keyword

section. In particular, it now refers to the new T_PTROBJ example and
shows how it can be extended to use overloading.

Author: iabyn

dist/ExtUtils-ParseXS/lib/perlxs.pod

@@ -2125,6 +2125,8 @@ result in these declarations in the C code:
 
 With the appropriate XS typemap entries and C typedefs, this can be used
 to assist in declaring XSUBs which are passed and return Perl objects.
+See L</T_PTROBJ and opaque handles> for an example of this using
+the common C<T_PTROBJ> typemap type.
 
 =head3 XSUB Parameter Placeholders
 
@@ -3397,46 +3399,161 @@ prototype string, including the empty prototype.
 
 =head3 The OVERLOAD: Keyword
 
-Instead of writing an overloaded interface using pure Perl, you
-can also use the OVERLOAD keyword to define additional Perl names
-for your functions (like the ALIAS: keyword above).  However, the
-overloaded functions must be defined in such a way as to accept the number
-of parameters supplied by perl's overload system.  For most overload
-methods, it will be three parameters; for the C<nomethod> function it will
-be four.  However, the bitwise operators C<&>, C<|>, C<^>, and C<~> may be
-called with three I<or> five arguments (see L<overload>).
-
-If any
-function has the OVERLOAD: keyword, several additional lines
-will be defined in the c file generated by xsubpp in order to
-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
-T_PTROBJ_SPECIAL in L<perlxstypemap>.
-
-To use the OVERLOAD: keyword, create an XS function which takes
-three input parameters (or use the C-style '...' definition) like
-this:
+    MODULE = Foo PACKAGE = Foo::Bar
 
-    SV *
-    cmp (lobj, robj, swap)
-        My_Module_obj lobj
-        My_Module_obj robj
-        IV            swap
-      OVERLOAD: cmp <=>
-        { /* function defined here */}
-
-In this case, the function will overload both of the three way
-comparison operators.  For all overload operations using non-alpha
-characters, you must type the parameter without quoting, separating
-multiple overloads with whitespace.  Note that "" (the stringify
-overload) should be entered as \"\" (i.e. escaped).
-
-Since, as mentioned above, bitwise operators may take extra arguments, you
-may want to use something like C<(lobj, robj, swap, ...)> (with
-literal C<...>) as your parameter list.
+    SV*
+    subtract(SV* a, SV* b, bool swap)
+      OVERLOAD: - -=
+      CODE:
+        ...
+
+The C<OVERLOAD> keyword allows you to declare that this XSUB acts as an
+overload method for the specified operators in the current package. The
+example above is approximately equivalent to this Perl code:
+
+    package Foo::Bar;
+
+    sub subtract { ... }
+
+    use overload
+        '-'  => \&subtract,
+        '-=' => \&subtract;
+
+The rest of the line following the keyword, plus any further lines until
+the next keyword, are interpreted as a space-separated list of overloaded
+operators. There is no check that they are valid operator names. The names
+and symbols will eventually end up within double-quoted strings
+in the C file, so double-quotes need to be escaped; in particular:
+
+      OVERLOAD: \"\"
+
+This could be regarded as a bug.
+
+XSUBs used for overload methods are invoked with the same arguments as
+Perl subroutines would be: for example, an overloaded binary operator will
+trigger a call to the XSUB method with the first argument being an
+overloaded object representing one of the two operands of the binary
+operator; the second being the other operand (which may or may not be an
+object); and third, a swap flag. See L<overload> for the full details
+of how these functions will be called, with what arguments. Note that
+swap can in fact be undef in addition to false, to indicate an assign
+overload such as C<+=>.
+
+Bitwise operator methods sometimes take extra arguments: in
+particular under C<use feature 'bitwise'>. So you may want to use an
+ellipsis (something like C<(lobj, robj, swap, ...)>) to skip them.
+
+The net effect of the C<OVERLOAD> keyword is to add some extra code to
+the boot XSUB to register this XSUB as the handler for the specified
+overload actions, in the same way that C<use overload> does for Perl
+methods.
+
+See also the file-scoped L<FALLBACK|/The FALLBACK: Keyword> keyword for
+details of how to set the fallback behaviour for the current package.
+
+Note that C<OVERLOAD> shouldn't be mixed with the L<ALIAS|/The ALIAS:
+Keyword> keyword; the value of C<ix> will be undefined for any overload
+method call.
+
+The L</T_PTROBJ and opaque handles> section contains a fully-worked
+example of using the C<T_PTROBJ> typemap to wrap a simple arithmetic
+library. The result of that wrapper allows you to write Perl code such as
+
+    my $i2  = My::Num->new(2);
+    my $i7  = My::Num->new(7);
+    my $i13 = My::Num->new(13);
+
+    my $x = $i13->add($i7)->divide($i2);
+    printf "val=%d\n", $x->val();
+
+Using overloading, we would like to be able to write those last two lines
+more simply as:
+
+    my $x = ($i13 + $i7)/$i2;
+    printf "val=%d\n", $x;
+
+The following additions and modifications to that example XS code show how
+to add overloading:
+
+    FALLBACK: UNDEF
+
+    int
+    mynum_val(My::Num x, ...)
+      OVERLOAD: 0+
+
+    My::Num
+    mynum_add(My::Num x, My::Num y, bool swap)
+      OVERLOAD: +
+      C_ARGS: x, y
+      INIT:
+        if (swap) {
+            mynum* tmp = x; x = y; y = tmp;
+        }
+
+     # and three similar XSUBs for mynum_subtract, mynum_multiply,
+     # mynum_divide
+
+The C<FALLBACK> line isn't actually necessary as this is the default
+anyway, but is included to remind you that the keyword can be used.
+
+Overloading is added to the C<mynum_val()> method so that it automatically
+returns the value of an object when used in a numeric context (such as for
+the C<printf> above). The ellipsis is added to ignore the extra two
+arguments passed to an overload method.
+
+The original C<mynum_add()> method which, via aliasing, handled all four
+of the arithmetic operations, is now split into four separate XSUBs, since
+C<ALIAS> and C<OVERLOAD> doesn't mix.
+
+The main change to each arithmetic XSUB part from adding the C<OVERLOAD>
+keyword, is that there is an extra C<swap> parameter. There's no real need
+to use it for addition and multiplication, but it is important for the
+non-commutative subtraction and division operations.
+
+That example uses the C<T_PTROBJ> typemap to process the second argument,
+which in the most general usage may not be an object. For example the
+second and third of these lines will croak with an C<Expected foo to be of
+type My::Num, got scalar> error:
+
+    $i13 + My::Num->new(7);
+    $i13 + 7;
+    $i13 + "7";
+
+If it is necessary to handle this, then you may need to create your own
+typemap: for example, something similar to C<T_PTROBJ>, but with an INPUT
+template along the lines of:
+
+    T_MYNUM
+        SV *sv = $arg;
+        SvGETMAGIC(sv);
+        if (!SvROK(sv)) {
+            sv = sv_newmortal();
+            sv_setref_pv(sv, "$ntype", mynum_new(SvIV($arg));
+        }
+        ....
+
+Finally, although not directly related to XS, the following could be added
+to F<Num.pm> to allow integer literals to be used directly:
+
+    sub import {
+        overload::constant integer =>
+            sub {
+                my $str = shift;
+                return My::Num->new($str);
+            };
+    }
+
+which then allows these lines:
+
+    my $i2  = My::Num->new(2);
+    my $i7  = My::Num->new(7);
+    my $i13 = My::Num->new(13);
+
+to be rewritten more cleanly as:
+
+    my $i2  = 2;
+    my $i7  = 7;
+    my $i13 = 13;
 
 =head3 The ATTRS: Keyword
 
@@ -3644,6 +3761,153 @@ the different argument lists.
 
 XXX TBC
 
+=head3 T_PTROBJ and opaque handles
+
+A common interface arrangement for C libraries is that some sort of
+I<create> function creates and returns a handle, which is a pointer to
+some opaque data. Other function calls are then passed that handle as an
+argument, until finally some sort of destroy function frees the handle and
+its data. The C<T_PTROBJ> typemap is one common method for mapping Perl
+objects to such C library handles. Behind the scenes, it uses blessed
+scalar objects with the scalar's integer value set to the address of the
+handle. The C<INPUT> code template of the C<T_PTROBJ> typemap retrieves the
+pointer from the scalar object referred to by a passed RV argument, while
+the C<OUTPUT> template creates a new blessed RV-to-SV with the handle
+address stored in it.
+
+For the purposes of an example, we'll create here a minimal example C
+library called C<mynum>, which we'll then proceed to wrap using XS. This
+library just stores an integer in its opaque data. In real life you would
+be wrapping an existing library which stores something more interesting,
+such as a complex number or a multiple precision integer.
+
+The following sample library code might go in the initial 'C' part of the
+XS file:
+
+    typedef struct { int i; } mynum;
+
+    mynum* mynum_new(int i)
+    {
+        mynum* x = (mynum*)malloc(sizeof(mynum));
+        x->i = i;
+        return x;
+    }
+
+    void   mynum_destroy  (mynum *x)
+                          { free((void*)x); }
+
+    int    mynum_val      (mynum *x)
+                          { return x->i; }
+
+    mynum* mynum_add      (mynum *x, mynum *y)
+                          { return mynum_new(x->i + y->i); }
+
+    mynum* mynum_subtract (mynum *x, mynum *y)
+                          { return mynum_new(x->i - y->i); }
+
+    mynum* mynum_multiply (mynum *x, mynum *y)
+                          { return mynum_new(x->i * y->i); }
+
+    mynum* mynum_divide   (mynum *x, mynum *y)
+                          { return mynum_new(x->i / y->i); }
+
+The C<mynum> struct holds the opaque handle data. The C<mynum_new()>
+function creates a numeric value and returns a handle to it. The other
+functions then take such handles as arguments, including a destroy
+function to free a handle's data.
+
+The following XS code shows an example of how this library might be
+wrapped and be made accessible from Perl via C<My::Num> objects:
+
+    typedef mynum *My__Num;
+
+    MODULE = My::Num PACKAGE = My::Num PREFIX = mynum_
+
+    PROTOTYPES: DISABLE
+
+    TYPEMAP: <<EOF
+    My::Num T_PTROBJ
+    EOF
+
+    My::Num
+    mynum_new(class, int i)
+        C_ARGS: i
+
+    void
+    DESTROY(My::Num x)
+        CODE:
+            mynum_destroy(x);
+
+    int
+    mynum_val(My::Num x)
+
+    My::Num
+    mynum_add(My::Num x, My::Num y)
+      ALIAS: subtract = 1
+             multiply = 2
+             divide   = 3
+      CODE:
+        switch (ix) {
+            case 0: RETVAL = mynum_add(x, y);      break;
+            case 1: RETVAL = mynum_subtract(x, y); break;
+            case 2: RETVAL = mynum_multiply(x, y); break;
+            case 3: RETVAL = mynum_divide(x, y);   break;
+        }
+      OUTPUT:
+        RETVAL
+
+The XSUBs in this example are mostly declared with parameter and return
+types of C<My::Num> which, as explained in L</Fully-qualified type names
+and Perl objects>, is looked up as-is in the typemap, but has C<s/:/_/g>
+applied to the type name to convert it to the C<My__Num> C type when used
+in the declaration of the XSUB's auto variables.
+
+Going through this code in order: while still in the 'C' half of the XS
+file, we add a typedef which says that the C<My__Num> C type is equivalent
+to a pointer to a handle from that arithmetic library.
+
+Next, the C<MODULE> line includes a C<mynum_> prefix, which means that
+the names of the XSUBs in the Perl namespace will be C<My::Num::new()> etc
+rather than C<My::Num::mynum_new()>.
+
+Then a C<TYPEMAP> declaration is used to map the C<My::Num> pseudo-type to
+the C<T_PTROBJ> XS type.
+
+Next comes the C<new()> class method. This will be called from perl as
+C<< My::Num->new(99); >> for example. Its first parameter will be the
+class name, which we don't use here, and the second parameter is the value
+to initialise the object to. The XSUB autocalls the library C<mynum_new()>
+function with just the C<i> value. This returns a handle, which the
+C<T_PTROBJ> C<OUTPUT> map converts into a blessed scalar ref containing
+the handle.
+
+Next, the C<DESTROY()> method is just a thin wrapper around
+C<mynum_destroy()>, while C<val()> returns the integer value of the
+object.
+
+Finally, four binary functions are defined, sharing the same XSUB body via
+aliases.
+
+This XS module might be accessed from Perl using code like this:
+
+    use My::Num;
+
+    my $i2  = My::Num->new(2);
+    my $i7  = My::Num->new(7);
+    my $i13 = My::Num->new(13);
+
+    my $x = $i13->add($i7)->divide($i2);
+    printf "val=%d\n", $x->val();  # prints "val=10"
+
+See L</The OVERLOAD: Keyword> for an example of how to extend this using
+overloading so that the expression could be written more simply as
+C<($i13 + $i7)/$i2>.
+
+Note that, as a very special case, the XS compiler translates the XS
+typemap name using C<s/OBJ$/REF/> when looking up INPUT typemap entries
+for an XSUB named C<DESTROY>. So for such subs, the C<T_PTRREF> typemap
+entry will be used instead.
+
 =head2 Using XS With C++
 
 If an XSUB name contains C<::>, it is considered to be a C++ method.