Perl 6 Pod: Псевдонимы

С помощью директивы =aliases можно определить ограниченный лексической областью видимости псевдоним для: части Pod текста, определения (мета) объекта в коде или даже куска программного кода. Данные псевдонимы используются в тексте Pod благодаря коду форматирования A<>.

Директива =alias является такой же фундаментальной, как =begin или =for. Она не может быть представлена в виде разграниченного (delimited) или параграфного (paragraph) блока.

Существует два вида псевдонимов: псевдонимы для макросов и контекстуальные (contextual) псевдонимы. Для обоих этих видов существует лексическая область видимости, ограниченная текущим Pod блоком.

Псевдонимы для макросов

Данная форма определения псевдонима наиболее простая: требуются только два аргумента. Первый - идентификатор, который обычно состоит из символов в верхнем регистре ( хотя данное условие необязательно ). Следующий аргумент состоит из одной или нескольких строк текста для подстановки.

В результате создается макрос Perl 6 с лексической областью видимости, который может быть вызван в процессе обработки документации. Для этого идентификатор макроса помещается в код форматирования A<>. В результате код форматирования заменяется на результат вызова макроса,а проще говоря, на текст, указанный при определении псевдонима.

Замещаемый текст начинается с первого непробельного (non-whitespace) символа, следующего за идентификатором псевдонима и продолжается до конца строки. Возможно определение замещаемого текста виде нескольких строк. Для этого в начале каждой следующей замещаемой строки ставиться знак = (с тем же отступом от начала строки как и =alias) и затем по крайней мере один пробел. Каждая из дополнительный строк использует отступ слева такой же как и первая строка ( с директивой =alias) замещаемого текста.

Например, для текста:

    =alias PROGNAME    Earl Irradiatem Evermore
    =alias VENDOR      4D Kingdoms
    =alias TERMS_URLS  =item L<http://www.4dk.com/eie>
    =                  =item L<http://www.4dk.co.uk/eie.io/>
    =                  =item L<http://www.fordecay.ch/canttouchthis>

    The use of A<PROGNAME> is subject to the terms and conditions
    laid out by A<VENDOR>, as specified at:

        A<TERMS_URL>

будет получен следующий результат:

The use of Earl Irradiatem Evermore is subject to the terms and
    conditions laid out by 4D Kingdoms Inc, as specified at:

• http://www.4dk.com/eie

• http://www.4dk.co.uk/eie.io/

• http://www.fordecay.ch/canttouchthis

Преимущества использования псевдонимов очевидны. Они могут быть использованы многократно в документации и достаточно отредактировать текст в определении псевдонима, чтобы эти изменения стали актуальными во всех частях документа.

    =alias PROGNAME    Count Krunchem Constantly
    =alias VENDOR      Last Chance Receivers Intl
    =alias TERMS_URLS  L<http://www.c11.com/generic_conditions>

Контекстуальные псевдонимы

Если директива =alias указана только с одним аргументом ( идентификатором ),то создается контекстуальный псевдоним. В данной форме за директивой =alias должен следовать программный код Perl 6 ( а не Pod блок ).

Единственный аргумент директивы используется в качестве имени псевдонима и следующая за ним часть программного кода Perl 6 сохраняется в качестве замещаемого текста (как результат вызова макроса).

Программный код, следующий за =alias, является исполняемым реальным кодом программы. Парсер Perl 6 позволяет использовать эту часть кода в качестве замещаемого текста для псевдонима. Таким образом разработчик может цитировать в документации необходимую часть программного кода без копирования.

Если код программы, следующий за одноаргументной формой директивы =alias, представляет собой блок кода, ограниченный скобками, то качестве текста для подстановки используется содержимое блока без скобок.

Например, для следующего кода :

    # This is actual code...

    sub hash_function ($key)
    =alias HASHCODE
    {
        my $hash = 0;
        for $key.split("") -> $char {
            $hash = $hash*33 + $char.ord;
        }
        return $hash;
    }

    =begin pod
    An ancient (but fast) hashing algorithm is used:

        =begin code :allow<A>
        A<HASHCODE>
        =end code

    =end pod

Результат будет следующим:

 An ancient (but fast) hashing algorithm is used:

    my $hash = 0;
    for $key.split("") -> $char {
        $hash *= 33;
        $hash += $char.ord;
    }
    return $hash;

Если за директивой =alias не следует открывающая скобки, то ожидается декларатор ( например: my, class, sub и т.д.). Определенный с помощью одного из деклараторов объект становиться значением (raead-only) псевдонима. Например:

    =alias CLASSNAME
    class Database::Handle {
        =alias ATTR
        has IO $!handle;

        =alias OPEN
        my Bool method open ($filename?) {...}

        =alias DEFNAME
        constant Str DEFAULT_FILENAME = 'db.log';

        =for para
            Note that the A<OPEN.name> method of class A<CLASSNAME>
            stores the resulting low-level database handle
            in its private A<ATTR.name> attribute. By default,
            handles are opened to the file "A<DEFNAME>".

    }

Результат :

Note that the open method of class Database::Handle stores the resulting low-level database handle in its private $!handle attribute. By default, handles are opened to the file "db.log".