Thread: Two fixes for plpgsql.sgml
Hi, This patch fixes two issues on plpgsql.sgml. Please review them carefully, at least the second one. Thanks. Regards. PS : this patch should be in context diff if my .cvsrc is correctly set up... at least, it doesn't look like my previous patch :) -- Guillaume. http://www.postgresqlfr.org http://dalibo.com Index: doc/src/sgml/plpgsql.sgml =================================================================== RCS file: /projects/cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v retrieving revision 1.117 diff -c -r1.117 plpgsql.sgml *** doc/src/sgml/plpgsql.sgml 26 Oct 2007 01:11:09 -0000 1.117 --- doc/src/sgml/plpgsql.sgml 28 Nov 2007 07:11:58 -0000 *************** *** 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 *************** *** 1428,1434 **** WHERE fooid > 0 LOOP -- can do some processing here ! RETURN NEXT r; -- return next row of SELECT END LOOP; RETURN; END --- 1428,1434 ---- WHERE fooid > 0 LOOP -- can do some processing here ! RETURN NEXT r; -- return current row of SELECT END LOOP; RETURN; END
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. + Index: doc/src/sgml/plpgsql.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v retrieving revision 1.118 diff -c -c -r1.118 plpgsql.sgml *** doc/src/sgml/plpgsql.sgml 28 Nov 2007 15:42:31 -0000 1.118 --- doc/src/sgml/plpgsql.sgml 28 Nov 2007 20:11:15 -0000 *************** *** 133,141 **** <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 evaluating a query. </para> --- 133,140 ---- <para> <application>PL/pgSQL</> functions can also be declared to return ! a <quote>set</>, or 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> *************** *** 1428,1434 **** WHERE fooid > 0 LOOP -- can do some processing here ! RETURN NEXT r; -- return next row of SELECT END LOOP; RETURN; END --- 1427,1433 ---- WHERE fooid > 0 LOOP -- can do some processing here ! RETURN NEXT r; -- return current row of SELECT END LOOP; RETURN; END
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. + Index: plpgsql.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v retrieving revision 1.119 diff -c -r1.119 plpgsql.sgml *** plpgsql.sgml 28 Nov 2007 20:13:06 -0000 1.119 --- plpgsql.sgml 28 Nov 2007 20:56:17 -0000 *************** *** 132,141 **** </para> <para> ! <application>PL/pgSQL</> functions can also be declared to return ! a <quote>set</>, or 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> --- 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>
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