From 95f202c0212f87ec2610b20643cb74c310f54952 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Wed, 24 Aug 2005 18:56:07 +0000
Subject: [PATCH] Adjust description of use_strict parameter.  Some other minor
 editorial cleanup.

---
 doc/src/sgml/plperl.sgml  | 71 +++++++++++++++++++++--------------------------
 doc/src/sgml/runtime.sgml |  8 +++---
 2 files changed, 36 insertions(+), 43 deletions(-)

diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml
index 2702508880..e7cdd2eb3c 100644
--- a/doc/src/sgml/plperl.sgml
+++ b/doc/src/sgml/plperl.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.43 2005/08/12 21:42:53 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.44 2005/08/24 18:56:07 tgl Exp $
 -->
 
  <chapter id="plperl">
@@ -46,46 +46,18 @@ $PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.43 2005/08/12 21:42:53 momjian E
   <para>
    To create a function in the PL/Perl language, use the standard
    <xref linkend="sql-createfunction" endterm="sql-createfunction-title">
-   syntax.  A PL/Perl function must always return a scalar value.  You
-   can return more complex structures (arrays, records, and sets) 
-   in the appropriate context by returning a reference.
-   Never return a list.  Here follows an example of a PL/Perl
-   function.
+   syntax:
 
 <programlisting>
 CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types</replaceable>) RETURNS <replaceable>return-type</replaceable> AS $$
     # PL/Perl function body
 $$ LANGUAGE plperl;
 </programlisting>
-   The body of the function is ordinary Perl code.
+   The body of the function is ordinary Perl code. A PL/Perl function must
+   always return a scalar value.  You can return more complex structures
+   (arrays, records, and sets) by returning a reference, as discussed below.
+   Never return a list.
   </para>
-    <para>
-    As with ordinary Perl code, you should use the strict pragma,
-    which you can do in one of two ways:
-
-    <itemizedlist>
-     <listitem>
-      <para>
-       Globally, by adding <quote>plperl</quote> to the list of <xref
-        linkend="guc-custom-variable-classes"> and setting
-       <literal>plperl.use_strict</literal> to true in
-       <filename>postgresql.conf</filename>
-      </para>
-    </listitem>
-     <listitem>
-      <para>
-       One function at a time, by using PL/PerlU (you must be database
-       superuser to do this) and including
-
-<programlisting>
-use strict;
-</programlisting>
-
-        in the function body.
-        </para>
-    </listitem>
-    </itemizedlist>
-    </para>
 
    <para>
     The syntax of the <command>CREATE FUNCTION</command> command requires
@@ -205,13 +177,13 @@ SELECT * FROM perl_row();
 
   <para>
     PL/Perl functions can also return sets of either scalar or
-    composite types.  In general, you'll want to return rows one at a
-    time both to speed up startup time and to keep from queueing up
+    composite types.  Usually you'll want to return rows one at a
+    time, both to speed up startup time and to keep from queueing up
     the entire result set in memory.  You can do this with
     <function>return_next</function> as illustrated below.  Note that
     after the last <function>return_next</function>, you must put
-    either <literal>return;</literal> or (better) <literal>return
-    undef;</literal>
+    either <literal>return</literal> or (better) <literal>return
+    undef</literal>.
 
 <programlisting>
 CREATE OR REPLACE FUNCTION perl_set_int(int)
@@ -237,7 +209,7 @@ $$ LANGUAGE plperl;
     contains either scalars, references to arrays, or references to
     hashes for simple types, array types, and composite types,
     respectively.  Here are some simple examples of returning the entire
-    result set as a reference:
+    result set as an array reference:
 
 <programlisting>
 CREATE OR REPLACE FUNCTION perl_set_int(int) RETURNS SETOF INTEGER AS $$
@@ -267,6 +239,27 @@ SELECT * FROM perl_set();
      it is a hazard if you declare a <application>PL/Perl</> function
      as returning a domain type.
     </para>
+
+  <para>
+   If you wish to use the <literal>strict</> pragma with your code,
+   the easiest way to do so is to <command>SET</>
+   <literal>plperl.use_strict</literal> to true.  This parameter affects
+   subsequent compilations of <application>PL/Perl</> functions, but not
+   functions already compiled in the current session.  To set the
+   parameter before <application>PL/Perl</> has been loaded, it is
+   necessary to have added <quote><literal>plperl</></> to the <xref
+   linkend="guc-custom-variable-classes"> list in
+   <filename>postgresql.conf</filename>.
+  </para>
+
+  <para>
+   Another way to use the <literal>strict</> pragma is to just put
+<programlisting>
+use strict;
+</programlisting>
+   in the function body.  But this only works for <application>PL/PerlU</>
+   functions, since <literal>use</> is not a trusted operation.
+  </para>
  </sect1>
 
  <sect1 id="plperl-database">
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index a699e0096b..320f1bfb8e 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.347 2005/08/22 17:34:56 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.348 2005/08/24 18:56:07 tgl Exp $
 -->
 
 <chapter Id="runtime">
@@ -4382,10 +4382,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
      when using custom variables:
 
 <programlisting>
-custom_variable_classes = 'plr,pljava'
+custom_variable_classes = 'plr,plperl'
 plr.path = '/usr/lib/R'
-pljava.foo = 1
-plruby.bar = true        # generates error, unknown class name
+plperl.use_strict = true
+plruby.use_strict = true        # generates error: unknown class name
 </programlisting>
     </para>
    </sect2>
-- 
2.11.0