A new fatal error :

[p5sagit/p5-mst-13.2.git] / pod / perlxs.pod

diff --git a/pod/perlxs.pod b/pod/perlxs.pod
index 0398641..0b66596 100644 (file)
--- a/pod/perlxs.pod
+++ b/pod/perlxs.pod
@@ -310,6 +310,10 @@ keyword and must follow immediately after it when used.
 
      [ XS code in package RPC ]
 
+The same package name can be used more than once, allowing for
+non-contiguous code. This is useful if you have a stronger ordering
+principle than package names.
+
 Although this keyword is optional and in some cases provides redundant
 information it should always be used.  This keyword will ensure that the
 XSUBs appear in the desired package.
@@ -839,6 +843,31 @@ However, the generated Perl function is called in very C-ish style:
   my ($day, $month);
   day_month($day, time, $month);
 
+=head2 The C<length(NAME)> Keyword
+
+If one of the input arguments to the C function is the length of a string
+argument C<NAME>, one can substitute the name of the length-argument by
+C<length(NAME)> in the XSUB declaration.  This argument must be omited when
+the generated Perl function is called.  E.g.,
+
+  void
+  dump_chars(char *s, short l)
+  {
+    short n = 0;
+    while (n < l) {
+        printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]);
+        n++;
+    }
+  }
+
+  MODULE = x           PACKAGE = x
+
+  void dump_chars(char *s, short length(s))
+
+should be called as C<dump_chars($string)>.
+
+This directive is supported with ANSI-type function declarations only.
+
 =head2 Variable-length Parameter Lists
 
 XSUBs can have variable-length parameter lists by specifying an ellipsis
@@ -1165,6 +1194,14 @@ prototypes.
           timep
           RETVAL
 
+If the prototypes are enabled, you can disable it locally for a given
+XSUB as in the following example:
+
+    void
+    rpcb_gettime_noproto()
+        PROTOTYPE: DISABLE
+    ...
+
 =head2 The ALIAS: Keyword
 
 The ALIAS: keyword allows an XSUB to have two or more unique Perl names
@@ -1189,6 +1226,57 @@ C<BAR::getit()> for this function.
         OUTPUT:
           timep
 
+=head2 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 with three parameters (except
+for the nomethod() function which needs four parameters).  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 below.
+
+To use the OVERLOAD: keyword, create an XS function which takes
+three input parameters ( or use the c style '...' definition) like
+this:
+
+    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, seperating
+multiple overloads with whitespace.  Note that "" (the stringify 
+overload) should be entered as \"\" (i.e. escaped).
+
+=head2 The FALLBACK: Keyword
+
+In addition to the OVERLOAD keyword, if you need to control how
+Perl autogenerates missing overloaded operators, you can set the
+FALLBACK keyword in the module header section, like this:
+
+    MODULE = RPC  PACKAGE = RPC
+
+    FALLBACK: TRUE
+    ...
+
+where FALLBACK can take any of the three values TRUE, FALSE, or
+UNDEF.  If you do not set any FALLBACK value when using OVERLOAD,
+it defaults to UNDEF.  FALLBACK is not used except when one or 
+more functions using OVERLOAD have been defined.  Please see
+L<overload/Fallback> for more details.
+
 =head2 The INTERFACE: Keyword
 
 This keyword declares the current XSUB as a keeper of the given
@@ -1722,20 +1810,20 @@ Below is an example module that makes use of the macros.
     #include "EXTERN.h"
     #include "perl.h"
     #include "XSUB.h"
- 
+
     /* Global Data */
- 
+
     #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
- 
+
     typedef struct {
         int count;
         char name[3][100];
     } my_cxt_t;
- 
+
     START_MY_CXT
- 
+
     MODULE = BlindMice           PACKAGE = BlindMice
- 
+
     BOOT:
     {
         MY_CXT_INIT;