Re: document plperl argument and return value representation - Mailing list pgsql-patches

Alvaro Herrera wrote:
> Andrew Dunstan wrote:
>
>> 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.
>>
>
> I find the mix of arguments and results a bit confusing.  Maybe you
> could put them in separate paragraphs.
>
>

Is this better?

I also took the opportunity to replace an unbalanced quote mark that was
screwing up the syntax highlighting.

cheers

andrew
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 23:44:04 -0000
***************
*** 138,150 ****
    </para>

    <para>
     Perl can return <productname>PostgreSQL</productname> arrays as
     references to Perl arrays.  Here is an example:

  <programlisting>
  CREATE OR REPLACE function returns_array()
  RETURNS text[][] AS $$
!     return [['a"b','c,d'],['e\\f','g']];
  $$ LANGUAGE plperl;

  select returns_array();
--- 138,180 ----
    </para>

    <para>
+    Anything in a function argument 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. 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>
+
+   </para>
+
+   <para>
+    Similarly, values passed back to <productname>PostgreSQL</productname>
+    must be in the external text representation format. For example, 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:

  <programlisting>
  CREATE OR REPLACE function returns_array()
  RETURNS text[][] AS $$
!     return [['a"b','c,d'],['e\\f','g']];
  $$ LANGUAGE plperl;

  select returns_array();