X-Original-To: pgsql-docs-postgresql.org@localhost.postgresql.org
Received: from localhost (unknown [200.46.204.144])
	by svr1.postgresql.org (Postfix) with ESMTP id D2971529DB;
	Tue, 12 Jul 2005 23:17:07 -0300 (ADT)
Received: from svr1.postgresql.org ([200.46.204.71])
	by localhost (av.hub.org [200.46.204.144]) (amavisd-new, port 10024)
	with ESMTP id 72210-09; Wed, 13 Jul 2005 02:16:59 +0000 (GMT)
Received: from mailbox.samurai.com (mailbox.samurai.com [205.207.28.82])
	by svr1.postgresql.org (Postfix) with ESMTP id 81343529C6;
	Tue, 12 Jul 2005 23:16:55 -0300 (ADT)
Received: from localhost (mailbox.samurai.com [205.207.28.82])
	by mailbox.samurai.com (Postfix) with ESMTP id 2BD419B4A2;
	Tue, 12 Jul 2005 22:17:00 -0400 (EDT)
Received: from mailbox.samurai.com ([205.207.28.82])
	by localhost (mailbox.samurai.com [205.207.28.82]) (amavisd-new,
	port 10024)
	with LMTP id 00975-01-3; Tue, 12 Jul 2005 22:16:58 -0400 (EDT)
Received: from [61.88.101.19] (unknown [61.88.101.19])
	(using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by mailbox.samurai.com (Postfix) with ESMTP id 08A869B4A0;
	Tue, 12 Jul 2005 22:16:56 -0400 (EDT)
Message-ID: <42D479A1.9020701@samurai.com>
Date: Wed, 13 Jul 2005 12:17:05 +1000
From: Neil Conway <neilc@samurai.com>
User-Agent: Mozilla Thunderbird 1.0.2 (Macintosh/20050317)
X-Accept-Language: en-us, en
MIME-Version: 1.0
To: David Fetter <david@fetter.org>
Cc: PostgreSQL Docs <pgsql-docs@postgresql.org>,
	PostgreSQL Patches <pgsql-patches@postgresql.org>
Subject: Re: [PATCHES] Doc patch: New PL/Perl Features
References: <20050712192129.GG12104@fetter.org>
	<20050712200156.GH12104@fetter.org>
In-Reply-To: <20050712200156.GH12104@fetter.org>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
X-Virus-Scanned: by amavisd-new at mailbox.samurai.com
X-Virus-Scanned: by amavisd-new at hub.org
X-Spam-Status: No, hits=0.016 tagged_above=0 required=5 tests=AWL
X-Spam-Level: 
X-Archive-Number: 200507/12
X-Sequence-Number: 3138

David Fetter wrote:
> On Tue, Jul 12, 2005 at 12:21:29PM -0700, David Fetter wrote:
> 
>>Folks,
>>
>>Please find enclosed document patches for PL/Perl features recently
>>introduced in CVS TIP.  These include:
>>
>>return_next
>>returning PostgreSQL arrays
>>spi_query/spi_fetchrow
>>use strict
>>
>>Cheers,
>>D
> 
> 
> Oops.  Persuant to corrections and clarifications by Andrew Dunstan,
> please find enclosed a better patch.

Applied with editorialization; see comments below. Thanks for the patch.

> +     <itemizedlist>
> +     <listitem>
> +         <para>
> +         Globally, by turning on plperl (one of the <xref
> +         linkend="guc-custom-variable-classes"
> +         endterm="custom_variable_classes"> you can use) and setting
> +         plperl.use_strict to true in your postgresql.conf, or
> +         </para>

Needs a <filename/> and a <literal/>. Also the <xref/> doesn't compile 
using openjade 1.3.1

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

Needs <productname/> around "PostgreSQL" for consistency with the rest 
of the SGML docs.

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

CREATE FUNCTION ... AS $$ ... $$ LANGUAGE plperl; would be more 
consistent with the other PL/Perl examples.

> ! CREATE OR REPLACE FUNCTION perl_set()
> ! RETURNS SETOF testrowperl
> ! LANGUAGE plperl AS $$
> !     return_next({f1 => 1, f2 => 'Hello', f3 => 'World' });
> !     return_next({ f1 => 2, f2 => 'Hello', f3 => 'PostgreSQL' });
> !     return_next({ f1 => 3, f2 => 'Hello', f3 => 'PL/Perl' });
> !     return undef;
> ! $$;
> ! </programlisting>

Should probably use "&gt;" not ">".

>        <term><literal><function>spi_exec_query</>(<replaceable>query</replaceable> [, <replaceable>max-rows</replaceable>])</literal></term>
>        <term><literal><function>spi_exec_query</>(<replaceable>command</replaceable>)</literal></term>
> +      <term><literal><function>spi_query</>(<replaceable>query</replaceable>)</literal></term>
> +      <term><literal><function>spi_fetchrow</>(<replaceable>result of spi_query</replaceable>)</literal></term>
> +      <term><literal>
> +      </literal></term>
>        <listitem>
>         <para>
>          Executes an SQL command.  Here is an example of a query

This needs more work -- the difference in behavior between spi_query() 
and spi_exec_query() is not described, so I didn't apply this hunk.

> *** 4103,4111 ****
>        when using custom variables:
>   
>   <programlisting>
> ! custom_variable_classes = 'plr,pljava'
>   plr.path = '/usr/lib/R'
>   pljava.foo = 1
>   plruby.bar = true        # generates error, unknown class name
>   </programlisting>
>       </para>
> --- 4103,4112 ----
>        when using custom variables:
>   
>   <programlisting>
> ! custom_variable_classes = 'plperl,plr,pljava'
>   plr.path = '/usr/lib/R'
>   pljava.foo = 1
> + plperl.use_strict = true # now without having to use pl/perlU! :)
>   plruby.bar = true        # generates error, unknown class name
>   </programlisting>
>       </para>

I didn't see why this was relevant, so I didn't apply it.

-Neil