Two fixes for plpgsql.sgml

On Wed, 2007-11-28 at 08:17 +0100, Guillaume Lelarge wrote:

This patch fixes two issues on plpgsql.sgml.

The first hunk seems like a regression to me: AFAICS the current
phrasing is what is intended.

*** 133,139 ****

      <para>
       <application>PL/pgSQL</> functions can also be declared to return
!      a <quote>set</>, or table, of any data type they can return a
single
       instance of.  Such a function generates its output by executing
       <command>RETURN NEXT</> for each desired element of the result
       set, or by using <command>RETURN QUERY</> to output the result of
--- 133,139 ----

<para>
<application>PL/pgSQL</> functions can also be declared to return
! a <quote>set</>, or table, or any data type they can return a
single
instance of. Such a function generates its output by executing
<command>RETURN NEXT</> for each desired element of the result
set, or by using <command>RETURN QUERY</> to output the result of

-Neil

Neil Conway a �crit :

On Wed, 2007-11-28 at 08:17 +0100, Guillaume Lelarge wrote:

This patch fixes two issues on plpgsql.sgml.

The first hunk seems like a regression to me: AFAICS the current
phrasing is what is intended.

*** 133,139 ****

<para>
<application>PL/pgSQL</> functions can also be declared to return
!      a <quote>set</>, or table, of any data type they can return a
single
instance of.  Such a function generates its output by executing
<command>RETURN NEXT</> for each desired element of the result
set, or by using <command>RETURN QUERY</> to output the result of
--- 133,139 ----

<para>
<application>PL/pgSQL</> functions can also be declared to return
! a <quote>set</>, or table, or any data type they can return a
single
instance of. Such a function generates its output by executing
<command>RETURN NEXT</> for each desired element of the result
set, or by using <command>RETURN QUERY</> to output the result of

That's why I said that it needs to be reviewed carefully :) It just
means I didn't understand the sentence. Can you explain why the last
part is needed ? (the part that starts with "of any data type...")

Thanks.

--
Guillaume.
http://www.postgresqlfr.org
http://dalibo.com

Guillaume Lelarge wrote:

Neil Conway a ?crit :

On Wed, 2007-11-28 at 08:17 +0100, Guillaume Lelarge wrote:

This patch fixes two issues on plpgsql.sgml.

The first hunk seems like a regression to me: AFAICS the current
phrasing is what is intended.

*** 133,139 ****

<para>
<application>PL/pgSQL</> functions can also be declared to return
!      a <quote>set</>, or table, of any data type they can return a
single
instance of.  Such a function generates its output by executing
<command>RETURN NEXT</> for each desired element of the result
set, or by using <command>RETURN QUERY</> to output the result of
--- 133,139 ----

<para>
<application>PL/pgSQL</> functions can also be declared to return
! a <quote>set</>, or table, or any data type they can return a
single
instance of. Such a function generates its output by executing
<command>RETURN NEXT</> for each desired element of the result
set, or by using <command>RETURN QUERY</> to output the result of

That's why I said that it needs to be reviewed carefully :) It just
means I didn't understand the sentence. Can you explain why the last
part is needed ? (the part that starts with "of any data type...")

Agreed. I couldn't find any value to that phrase and couldn't find better
wording, so I removed it. Patch attached and applied.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian <bruce@momjian.us> writes:

Agreed. I couldn't find any value to that phrase and couldn't find better
wording, so I removed it. Patch attached and applied.

This is not an improvement.

The point of the original wording is that you have to say
RETURNS SETOF sometype
you can't just say, eg,
RETURNS SET

Your new wording would lead the reader to the assumption that he can
just declare a function as returning "set".

Please revert the change.

regards, tom lane

Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> writes:

Agreed. I couldn't find any value to that phrase and couldn't find better
wording, so I removed it. Patch attached and applied.

This is not an improvement.

The point of the original wording is that you have to say
RETURNS SETOF sometype
you can't just say, eg,
RETURNS SET

Your new wording would lead the reader to the assumption that he can
just declare a function as returning "set".

Please revert the change.

I found the original confusing, as did the author, so I updated the docs
again.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian wrote:

--- 132,142 ----
</para>

<para>
! <application>PL/pgSQL</> functions can also be declared to return a
! group of values, either as a single row, or a group of rows, like a
! table. Such a function generates its output by executing
! <command>RETURN NEXT</> for each desired element of the result set,
! or by using <command>RETURN QUERY</> to output the result of
evaluating a query.
</para>

Hmm, ISTM the correct terminology is "set of rows". I have never heard
of "a group of rows". It seems to me the easiest way out of the problem
would have been substituting the commas in the original with parens:

<application>PL/pgSQL</> functions can also be declared to return
a <quote>set</> (or <quote>table</>) of any data type they can return a single
instance of.

The point of "any datatype they can return a single instance of" is that
this can be a set of scalar values (e.g. "RETURNS SETOF int") or of a
complex type ("RETURNS SETOF table"), or anything else they can return a
single instance of :-P (SETOF anyelement? SETOF table%TYPE?)

--
Alvaro Herrera http://www.PlanetPostgreSQL.org/
"World domination is proceeding according to plan" (Andrew Morton)

Alvaro Herrera wrote:

Bruce Momjian wrote:

--- 132,142 ----
</para>

<para>
! <application>PL/pgSQL</> functions can also be declared to return a
! group of values, either as a single row, or a group of rows, like a
! table. Such a function generates its output by executing
! <command>RETURN NEXT</> for each desired element of the result set,
! or by using <command>RETURN QUERY</> to output the result of
evaluating a query.
</para>

Hmm, ISTM the correct terminology is "set of rows". I have never heard
of "a group of rows". It seems to me the easiest way out of the problem
would have been substituting the commas in the original with parens:

<application>PL/pgSQL</> functions can also be declared to return
a <quote>set</> (or <quote>table</>) of any data type they can return a single
instance of.

The point of "any datatype they can return a single instance of" is that
this can be a set of scalar values (e.g. "RETURNS SETOF int") or of a
complex type ("RETURNS SETOF table"), or anything else they can return a
single instance of :-P (SETOF anyelement? SETOF table%TYPE?)

Good idea, updated:

<application>PL/pgSQL</> functions can also be declared to return
a <quote>set</> (or table) of any data type that can be returned as
a single instance. Such a function generates its output by executing
<command>RETURN NEXT</> for each desired element of the result
set, or by using <command>RETURN QUERY</> to output the result of
evaluating a query.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian a �crit :

Alvaro Herrera wrote:

[...]
The point of "any datatype they can return a single instance of" is that
this can be a set of scalar values (e.g. "RETURNS SETOF int") or of a
complex type ("RETURNS SETOF table"), or anything else they can return a
single instance of :-P (SETOF anyelement? SETOF table%TYPE?)

Good idea, updated:

<application>PL/pgSQL</> functions can also be declared to return
a <quote>set</> (or table) of any data type that can be returned as
a single instance. Such a function generates its output by executing
<command>RETURN NEXT</> for each desired element of the result
set, or by using <command>RETURN QUERY</> to output the result of
evaluating a query.

Great. Now I better understand this part. Thank you all.

--
Guillaume.
http://www.postgresqlfr.org
http://dalibo.com