From 95ef6a344821655ce4d0a74999ac49dd6af6d342 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 21 Mar 2002 16:02:16 +0000
Subject: First phase of SCHEMA changes, concentrating on fixing the grammar
 and the parsetree representation.  As yet we don't *do* anything with schema
 names, just drop 'em on the floor; but you can enter schema-compatible
 command syntax, and there's even a primitive CREATE SCHEMA command. No doc
 updates yet, except to note that you can now extract a field from a
 function-returning-row's result with (foo(...)).fieldname.

---
 doc/src/sgml/xfunc.sgml | 46 ++++++++++++++++++++++++++--------------------
 1 file changed, 26 insertions(+), 20 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 73c0287d446..262c1e2e8c7 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.49 2002/03/11 05:03:52 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.50 2002/03/21 16:00:28 tgl Exp $
 -->
 
  <chapter id="xfunc">
@@ -306,7 +306,8 @@ CREATE FUNCTION new_emp() RETURNS EMP AS '
        <para>
 	The  target  list  order must be exactly the same as
 	that in which the columns appear in the table associated
-	with the composite type.
+	with the composite type.  (Naming the columns, as we did above,
+	is irrelevant to the system.)
        </para>
       </listitem>
       <listitem>
@@ -328,28 +329,46 @@ ERROR:  function declared to return emp returns varchar instead of text at colum
      there are some unpleasant restrictions on how functions returning
      composite types can be used.  Briefly, when calling a function that
      returns a row, we cannot retrieve the entire row.  We must either
-     project a single attribute out of the row or pass the entire row into
+     extract a single attribute out of the row or pass the entire row into
      another function.  (Trying to display the entire row value will yield
      a meaningless number.)  For example,
 
 <programlisting>
-SELECT name(new_emp());
+SELECT (new_emp()).name;
 </programlisting>
 
 <screen>
  name
 ------
  None
+</screen>
+
+     We need the extra parentheses to keep the parser from getting confused:
+
+<screen>
+SELECT new_emp().name;
+ERROR:  parser: parse error at or near "."
 </screen>
     </para>
 
     <para>
-     This example makes use of the
-     function notation for projecting attributes.  The  simple  way 
-     to explain this is that we can usually use the
+     Another approach is to use
+     functional notation for extracting attributes.  The  simple  way 
+     to explain this is that we can use the
      notations <literal>attribute(table)</>  and  <literal>table.attribute</>
      interchangeably:
 
+<programlisting>
+SELECT name(new_emp());
+</programlisting>
+
+<screen>
+ name
+------
+ None
+</screen>
+    </para>
+
 <programlisting>
 --
 -- this is the same as:
@@ -367,19 +386,6 @@ SELECT name(EMP) AS youngster
 </screen>
     </para>
 
-    <para>
-	The reason why, in general, we must use the function
-        syntax  for projecting attributes of function return
-        values is that the parser  just  doesn't  understand
-        the  dot syntax for projection when combined
-        with function calls.
-
-<screen>
-SELECT new_emp().name AS nobody;
-ERROR:  parser: parse error at or near "."
-</screen>
-    </para>
-
     <para>
      Another way to use a function returning a row result is to declare a
      second function accepting a row type parameter, and pass the function
-- 
cgit v1.2.3