<!-- doc/src/sgml/plperl.sgml -->

 <chapter id="plperl">
  <title>PL/Perl &mdash; Perl Procedural Language</title>

  <indexterm zone="plperl">
   <primary>PL/Perl</primary>
  </indexterm>

  <indexterm zone="plperl">
   <primary>Perl</primary>
  </indexterm>

  <para>
   PL/Perl is a loadable procedural language that enables you to write
   <productname>PostgreSQL</productname> functions and procedures in the
   <ulink url="https://www.perl.org">Perl programming language</ulink>.
  </para>

  <para>
   The main advantage to using PL/Perl is that this allows use,
   within stored functions and procedures, of the manyfold <quote>string
   munging</quote> operators and functions available for Perl.  Parsing
   complex strings might be easier using Perl than it is with the
   string functions and control structures provided in PL/pgSQL.
  </para>

  <para>
   To install PL/Perl in a particular database, use
   <literal>CREATE EXTENSION plperl</literal>.
  </para>

  <tip>
   <para>
    If a language is installed into <literal>template1</literal>, all subsequently
    created databases will have the language installed automatically.
   </para>
  </tip>

  <note>
   <para>
    Users of source packages must specially enable the build of
    PL/Perl during the installation process.  (Refer to <xref
    linkend="installation"/> for more information.)  Users of
    binary packages might find PL/Perl in a separate subpackage.
   </para>
  </note>

 <sect1 id="plperl-funcs">
  <title>PL/Perl Functions and Arguments</title>

  <para>
   To create a function in the PL/Perl language, use the standard
   <xref linkend="sql-createfunction"/>
   syntax:

<programlisting>
CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types</replaceable>)
RETURNS <replaceable>return-type</replaceable>
-- function attributes can go here
AS $$
    # PL/Perl function body goes here
$$ LANGUAGE plperl;
</programlisting>

   The body of the function is ordinary Perl code. In fact, the PL/Perl
   glue code wraps it inside a Perl subroutine.  A PL/Perl function is
   called in a scalar context, so it can't return a list.  You can return
   non-scalar values (arrays, records, and sets) by returning a reference,
   as discussed below.
  </para>

  <para>
   In a PL/Perl procedure, any return value from the Perl code is ignored.
  </para>

  <para>
   PL/Perl also supports anonymous code blocks called with the
   <xref linkend="sql-do"/> statement:

<programlisting>
DO $$
    # PL/Perl code
$$ LANGUAGE plperl;
</programlisting>

   An anonymous code block receives no arguments, and whatever value it
   might return is discarded.  Otherwise it behaves just like a function.
  </para>

  <note>
   <para>
    The use of named nested subroutines is dangerous in Perl, especially if
    they refer to lexical variables in the enclosing scope. Because a PL/Perl
    function is wrapped in a subroutine, any named subroutine you place inside
    one will be nested. In general, it is far safer to create anonymous
    subroutines which you call via a coderef. For more information, see the
    entries for <literal>Variable "%s" will not stay shared</literal> and
    <literal>Variable "%s" is not available</literal> in the
    <citerefentry><refentrytitle>perldiag</refentrytitle></citerefentry> man page, or
    search the Internet for <quote>perl nested named subroutine</quote>.
   </para>
  </note>

  <para>
   The syntax of the <command>CREATE FUNCTION</command> command requires
   the function body to be written as a string constant.  It is usually
   most convenient to use dollar quoting (see <xref
   linkend="sql-syntax-dollar-quoting"/>) for the string constant.
   If you choose to use escape string syntax <literal>E''</literal>,
   you must double any single quote marks (<literal>'</literal>) and backslashes
   (<literal>\</literal>) used in the body of the function
   (see <xref linkend="sql-syntax-strings"/>).
  </para>

  <para>
   Arguments and results