|
1 | 1 | <!-- |
2 | | -$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.45 2005/08/24 19:16:49 tgl Exp $ |
| 2 | +$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.46 2005/10/12 14:28:33 momjian Exp $ |
3 | 3 | --> |
4 | 4 |
|
5 | 5 | <chapter id="plperl"> |
@@ -53,22 +53,34 @@ CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types |
53 | 53 | # PL/Perl function body |
54 | 54 | $$ LANGUAGE plperl; |
55 | 55 | </programlisting> |
56 | | - The body of the function is ordinary Perl code. A PL/Perl function must |
| 56 | + The body of the function is ordinary Perl code. In fact, the PL/Perl |
| 57 | + glue code wraps it inside a Perl subroutine. A PL/Perl function must |
57 | 58 | always return a scalar value. You can return more complex structures |
58 | 59 | (arrays, records, and sets) by returning a reference, as discussed below. |
59 | 60 | Never return a list. |
60 | 61 | </para> |
61 | 62 |
|
| 63 | + <note> |
62 | 64 | <para> |
63 | | - The syntax of the <command>CREATE FUNCTION</command> command requires |
64 | | - the function body to be written as a string constant. It is usually |
65 | | - most convenient to use dollar quoting (see <xref |
66 | | - linkend="sql-syntax-dollar-quoting">) for the string constant. |
67 | | - If you choose to use regular single-quoted string constant syntax, |
68 | | - you must escape single quote marks (<literal>'</>) and backslashes |
69 | | - (<literal>\</>) used in the body of the function, typically by |
70 | | - doubling them (see <xref linkend="sql-syntax-strings">). |
| 65 | + The use of named nested subroutines is dangerous in Perl, especially if |
| 66 | + they refer to lexical variables in the enclosing scope. Because a PL/Perl |
| 67 | + function is wrapped in a subroutine, any named subroutine you create will |
| 68 | + be nested. In general, it is far safer to create anonymous subroutines |
| 69 | + which you call via a coderef. See the <literal>perldiag</literal> |
| 70 | + man page for more details. |
71 | 71 | </para> |
| 72 | + </note> |
| 73 | + |
| 74 | + <para> |
| 75 | + The syntax of the <command>CREATE FUNCTION</command> command requires |
| 76 | + the function body to be written as a string constant. It is usually |
| 77 | + most convenient to use dollar quoting (see <xref |
| 78 | + linkend="sql-syntax-dollar-quoting">) for the string constant. |
| 79 | + If you choose to use regular single-quoted string constant syntax, |
| 80 | + you must escape single quote marks (<literal>'</>) and backslashes |
| 81 | + (<literal>\</>) used in the body of the function, typically by |
| 82 | + doubling them (see <xref linkend="sql-syntax-strings">). |
| 83 | + </para> |
72 | 84 |
|
73 | 85 | <para> |
74 | 86 | Arguments and results are handled as in any other Perl subroutine: |
|