document plperl argument and return value representation

The attached docs patch makes clearer how arguments and return values in
pl/perl are escaped. This is to clarify the situation that Theo
Schlossnagle recently reported on -bugs.

If there's no objection I will apply this.

cheers

andrew
? plperldoc.patch
Index: plperl.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v
retrieving revision 2.65
diff -c -r2.65 plperl.sgml
*** plperl.sgml    3 May 2007 15:05:56 -0000    2.65
--- plperl.sgml    3 May 2007 22:19:05 -0000
***************
*** 138,143 ****
--- 138,169 ----
    </para>

    <para>
+    Anything in a function argument or result that is not a reference is
+    a string, which is in the standard <productname>PostgreSQL</productname>
+    external text representation for the relevant data type. In the case of
+    ordinary numeric or text types, Perl will just do the right thing and
+    the programmer will normally not have to worry about it. However, in
+    other cases the argument will need to be converted into a form that is
+    more usable in Perl, and the return result will need to be converted to
+    the form that <productname>PostgreSQL</productname> expects. For example,
+    here is how to convert an argument of type bytea into unescaped binary
+    data:
+
+ <programlisting>
+     my $arg = shift;
+     $arg =~ s!\\(\d{3})!chr(oct($1))!ge;
+ </programlisting>
+
+    and here is how to escape binary data for a return value of type bytea:
+
+ <programlisting>
+     $retval =~ s!([^ -~])!sprintf("\\%03o",ord($1))!ge;
+     return $retval;
+ </programlisting>
+
+   </para>
+
+   <para>
     Perl can return <productname>PostgreSQL</productname> arrays as
     references to Perl arrays.  Here is an example: