40.1. PL/Perl関数と引数

PL/Perl言語で関数を作成するには、以下の標準的なCREATE FUNCTION構文を使用してください。

CREATE FUNCTION funcname (argument-types) RETURNS return-type AS $$
    # PL/Perl関数本体
$$ LANGUAGE plperl;

関数本体は通常のPerlのコードです。 実際、PL/Perlの糊付けコードは、これをPerlのサブルーチンの内部に格納します。 PL/Perl関数は常にスカラ値を返さなければなりません。 後述の通り、参照を使用して複雑な構造（配列、レコード、集合）を返すことができます。 リストを返してはなりません。

CREATE FUNCTIONコマンドの構文では、関数本体は文字列定数として記述されることを必須としています。 通常、文字列定数にはドル引用符付け（項4.1.2.2を参照）を使用することが最も便利です。 エスケープ文字列構文E''を使用することを選択した場合、 関数本体で使用される単一引用符（'）とバックスラッシュ（\）を二重にしなければなりません。（項4.1.2.1を参照）。

引数と結果は他のPerlサブルーチンと同様に扱われます。 引数は@_の中に渡され、結果値はreturn、または、その関数で最後に評価された式として返されます。

例えば、2つの整数のうち大きな方を返す関数は以下のように定義できます。

CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS $$
    if ($_[0] > $_[1]) { return $_[0]; }
    return $_[1];
$$ LANGUAGE plperl;

SQLのNULL値が関数に渡された場合、その引数値はPerlにおける"未定義"として現れます。 上の関数定義では、NULL値が入力された場合うまく動作しないでしょう（実際はそれがゼロであるかのように動作するでしょう）。 STRICTを関数定義に加えることで、PostgreSQLの動作をより合理的にすることができます。 NULL値が渡された場合、関数はまったく呼び出されず、単にNULLという結果が自動的に返されます。 他の方法として、関数本体で未定義な入力をチェックすることもできます。 例えば、perl_maxの引数の片方がNULL、もう片方が非NULLの場合に、NULL値ではなく非NULLの引数を返すようにするとします。

CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS $$
    my ($x,$y) = @_;
    if (! defined $x) {
        if (! defined $y) { return undef; }
        return $y;
    }
    if (! defined $y) { return $x; }
    if ($x > $y) { return $x; }
    return $y;
$$ LANGUAGE plperl;

上で示した通り、PL/Perl関数からSQLのNULL値を返すためには、未定義値を返すようにしてください。 これは、関数が厳密かどうかに関係なく、実行することができます。

関数引数の内参照でないものは文字列で、対応するデータ型向けのPostgreSQLの標準的な外部テキスト表現を表します。 通常の数値やテキスト型では、perlは正確に処理を行いますので、プラグラマは心配することはありません。 しかし、この他の場合では、引数をPerlでより使用しやすいように変換する必要があります。 たとえば、bytea型の引数をエスケープしないバイナリデータに変換する方法を以下に示します。

    my $arg = shift;
    $arg =~ s!\\(?:\\|(\d{3}))!$1 ? chr(oct($1)) : "\\"!ge;

同様に、PostgreSQLに戻される値を外部テキスト表現書式で表さなければなりません。 たとえば、bytea型の戻り値のためのバイナリデータのエスケープ方法を以下に示します。

    $retval =~ s!(\\|[^ -~])!sprintf("\\%03o",ord($1))!ge;
    return $retval;

Perlは、PostgreSQLの配列をPerl配列への参照として返すことができます。 以下に例を示します。

CREATE OR REPLACE function returns_array()
RETURNS text[][] AS $$
    return [['a"b','c,d'],['e\\f','g']];
$$ LANGUAGE plperl;

select returns_array();

複合型の引数はハッシュへの参照として関数に渡されます。 ハッシュのキーは複合型の属性名です。 以下に例を示します。

CREATE TABLE employee (
    name text,
    basesalary integer,
    bonus integer
);

CREATE FUNCTION empcomp(employee) RETURNS integer AS $$
    my ($emp) = @_;
    return $emp->{basesalary} + $emp->{bonus};
$$ LANGUAGE plperl;

SELECT name, empcomp(employee.*) FROM employee;

必要な属性を持つハッシュの参照を返すという同じ方法で、PL/Perl関数は複合型の結果を返すことができます。 以下に例を示します。

CREATE TYPE testrowperl AS (f1 integer, f2 text, f3 text);

CREATE OR REPLACE FUNCTION perl_row() RETURNS testrowperl AS $$
    return {f2 => 'hello', f1 => 1, f3 => 'world'};
$$ LANGUAGE plperl;

SELECT * FROM perl_row();

宣言された結果データ型の任意の列のうち、ハッシュ内に存在しないものはNULL値として返されます。

また、PL/Perl関数はスカラ型の配列や複合型の配列を返すこともできます。 通常ならば、起動処理の高速化とメモリ内の結果セット全体を待ち行列に保持できることから、1度に1行を返す方がよいでしょう。 以下に示すreturn_nextを使用して、これを行うことができます。 最後のreturn_nextの後で、returnまたはreturn undef（推奨）を記述しなければならないことに注意してください。

CREATE OR REPLACE FUNCTION perl_set_int(int)
RETURNS SETOF INTEGER AS $$
    foreach (0..$_[0]) {
        return_next($_);
    }
    return undef;
$$ LANGUAGE plperl;

SELECT * FROM perl_set_int(5);

CREATE OR REPLACE FUNCTION perl_set()
RETURNS SETOF testrowperl AS $$
    return_next({ f1 => 1, f2 => 'Hello', f3 => 'World' });
    return_next({ f1 => 2, f2 => 'Hello', f3 => 'PostgreSQL' });
    return_next({ f1 => 3, f2 => 'Hello', f3 => 'PL/Perl' });
    return undef;
$$ LANGUAGE plperl;

小規模な結果セットでは、それぞれ単純な型、配列型、複合型に対応する、スカラ、配列への参照、ハッシュへの参照を含む配列への参照を返すことができます。 以下に、配列への参照として結果セット全体を返す単純な例をいくつか示します。

CREATE OR REPLACE FUNCTION perl_set_int(int) RETURNS SETOF INTEGER AS $$
    return [0..$_[0]];
$$ LANGUAGE plperl;

SELECT * FROM perl_set_int(5);

CREATE OR REPLACE FUNCTION perl_set() RETURNS SETOF testrowperl AS $$
    return [
        { f1 => 1, f2 => 'Hello', f3 => 'World' },
        { f1 => 2, f2 => 'Hello', f3 => 'PostgreSQL' },
        { f1 => 3, f2 => 'Hello', f3 => 'PL/Perl' }
    ];
$$ LANGUAGE plperl;

SELECT * FROM perl_set();

コード内でstrictプラグマを使用したいのであれば、SET plperl.use_strictを真とすることがもっとも簡単な方法です。 このパラメータは、その後のPL/Perl関数のコンパイルに影響します。 現在のセッションでコンパイル済みの関数には影響しません。 PL/Perlをロードする前にこのパラメータを設定するには、postgresql.conf内のcustom_variable_classes一覧に"plperl"を追加しなければなりません。

strictプラグマを使用するための他の方法は、以下を関数本体に記載することです。

use strict;

しかし、これはPL/PerlU関数でしか動作しません。 useが信頼できる操作ではないからです。 PL/Perl関数では代わりに以下のようにしてください。

BEGIN { strict->import(); }