Обсуждение: 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:

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.


--
Alvaro Herrera                                http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

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();

Andrew Dunstan <andrew@dunslane.net> writes:
> Is this better?

I suggest bytea -> <type>bytea</>, otherwise seems fine.

            regards, tom lane

Andrew Dunstan wrote:
>
>
> 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?

Yup, looks very nice.

This message also serves to test whether I removed the annoying
Mail-Followup-To header.  It was actually a _feature_ of mutt
(followup_to, which fired when I replied to a list to which I'm
subscribed), which I disabled.  Sorry about that.

ETOOMANYWHICH, sorry about that as well :-)

--
Alvaro Herrera                                http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.