Convert Postgres arrays to Perl arrays on PL/perl input arguments

More generally, arrays are turned in Perl array references, and row and
composite types are turned into Perl hash references.  This is done
recursively, in a way that's natural to every Perl programmer.

To avoid a backwards compatibility hit, the string representation of
each structure is also available if the function requests it.

Authors: Alexey Klyukin and Alex Hunsaker.
Some code cleanups by me.

doc/src/sgml/plperl.sgml

@@ -198,6 +198,42 @@ select returns_array();
 </programlisting>
   </para>
 
+  <para>
+   Perl passes <productname>PostgreSQL</productname> arrays as a blessed
+   PostgreSQL::InServer::ARRAY object. This object may be treated as an array
+   reference or a string, allowing for backwards compatibility with Perl
+   code written for <productname>PostgreSQL</productname> versions below 9.1 to
+   run.  For example:
+
+<programlisting>
+CREATE OR REPLACE FUNCTION concat_array_elements(text[]) RETURNS TEXT AS $$
+    my $arg = shift;
+    my $result = "";
+    return undef if (!defined $arg);
+
+    # as an array reference
+    for (@$arg) {
+        $result .= $_;
+    }
+
+    # also works as a string
+    $result .= $arg;
+
+    return $result;
+$$ LANGUAGE plperl;
+
+SELECT concat_array_elements(ARRAY['PL','/','Perl']);
+</programlisting>
+
+  <note>
+   <para>
+    Multi-dimensional arrays are represented as references to
+    lower-dimensional arrays of references in a way common to every Perl
+    programmer.
+   </para>
+  </note>
+  </para>
+
   <para>
    Composite-type arguments are passed to the function as references
    to hashes.  The keys of the hash are the attribute names of the
@@ -740,6 +776,22 @@ SELECT release_hosts_query();
      </listitem>
     </varlistentry>
 
+    <varlistentry>
+     <indexterm>
+      <primary>encode_typed_literal</primary>
+      <secondary>in PL/Perl</secondary>
+     </indexterm>
+
+     <term><literal><function>encode_typed_literal(<replaceable>value</replaceable>, <replaceable>typename</replaceable>)</function></literal></term>
+      <listitem>
+       <para>
+         Converts a Perl variable to the value of the datatype passed as a
+         second argument and returns a string representation of this value.
+         Correctly handles nested arrays and values of composite types.
+       </para>
+      </listitem>
+    </varlistentry>
+
     <varlistentry>
      <indexterm>
       <primary>encode_array_constructor</primary>
@@ -775,8 +827,24 @@ SELECT release_hosts_query();
      </listitem>
     </varlistentry>
 
+    <varlistentry>
+     <indexterm>
+      <primary>is_array_ref</primary>
+      <secondary>in PL/Perl</secondary>
+     </indexterm>
+
+     <term><literal><function>is_array_ref(<replaceable>argument</replaceable>)</function></literal></term>
+     <listitem>
+      <para>
+        Returns a true value if the given argument may be treated as an
+        array reference, that is, if ref of the argument is <literal>ARRAY</> or
+        <literal>PostgreSQL::InServer::ARRAY</>.  Returns false otherwise.
+      </para>
+     </listitem>
+    </varlistentry>
+
    </variablelist>
- </sect2>
+  </sect2>
  </sect1>
 
  <sect1 id="plperl-global">