=head1 TITLE

Виртуальные таблицы Паррота

=head1 Реализация типов переменных при помощи Виртуальных таблиц

Это руководство по созданию ващих собственных PMC (Parrot Magic Cookie) классов.
Оно рассказывает, что необходимо нописать надлежащим образом, что бы добавить новые 
переменный типы переменных в Паррот.

=head2 Обзор

Внутренности Паррот интерпритатора, в упошенной схеме (или, если ты
хочешь меннее принебрежительно, скептически), - это лабиринт поведения 
типов переменных. Стандартный пример - различия между скалярами Перла и
скалярами Питона. В Перле, если ты имеешь

    $a = "a9";
    $a++;

ты получишь, что C<$a> равно C<b0>. Это благодаря магии оперетора 
инкрементирования в Перле. В Питоне, с другой стороны, ты получишь
ошибку выполнения.

=over 3

=item *

Чтобы быть совершенно честными, это немного некоректный пример, так как
маловероятно что будет отдельный "Python scalar" PMC класс. Компилятор 
Питона мог бы догадатся что C<a> является C<PythonString>, а C<b> - это
C<PythonNumber>. Но загвоздка остатется - инкрементирование C<PythonString> 
очень отличается от инкрементирования C<PerlScalar>

=back

Такое поведение является функцией PMC "типа", естественно рассматиривать
различные типы PMC как классы в объектно-ориентированных системах.
Паррот интерпритатор вызывает методы индивидуальных PMC объектов 
чтобы манипулировать ими. Так что привер, приведенный выше, 
выгледял бы подобно этому:

=over 3

=item 1.

Создание нового PMC класса PerlScalar.

=item 2.

Вызов метода, устанавливающего его строковое значение в C<"a9">.

=item 3.

Вызов метода, чтобы сказать ему инкрементировать себя.

=back

И если ты заменишь PerlScalar на PythonString, ты получишь различное
поведение, но для основных внутренностей интерпритатора,
инструкции будет такими же самыми. PMC являются абстрактными виртуальными классами;
Интрепритатор вызывает методы, PMC объект делает требуемый вещи, и 
интепритатор не заботится особенно, что это требуемая вешь случается чтобы быть.

Hence, добавление новых типов данный в Паррот -это вопрос об обеспечении методов,
ктороые выполняют ожидаемые от типов данных действия.
Давайте взлянем, как сделать это.

=head2 Поехали

Если ты добавляешь тип данных в ядро Паррота, (и ты сверяешься 
с Dan и/или Simon, что вы, как предполагается, делаете)
ты должен создать файл в F<classes/> подкаталоге; это там встроенные
PMC классы живут. (И хороший источник примеров, чтобы разграбить,
даже если Вы не пишете основной тип данных.)

You should almost always start by running F<genclass.pl> found in the
F<classes/> subdirectory to generate a skeleton for the class. Let's
generate a number type for the beautifully non-existant Fooby language:

    perl -I../lib genclass.pl FoobyNumber > foobynumber.pmc

This will produce a skeleton C file (to be preprocessed by the
F<pmc2c.pl> program) with stubs for all the methods you need to fill in.
The function C<init> allows you to set up anything you need to set up.

Now you'll have to do something a little different depending on whether
you're writing a built-in class or an extension class. If you're writing
a built-in class, then you'll see a reference to
C<enum_class_FoobyNumber> in the C<init> function. For built-in classes,
this is automatically defined in F<pmc.h> when you run Configure.pl.
If you're not writing a built-in class, you need to indicate this by
using the 'extension' keyword after the 'pmclass YOURCLASS' declaration
in classes/YOURCLASS.pmc. Then, change the
type of the C<init> function to return C<struct _vtable>, and then
return C<temp_base_vtable> instead of assigning to the
C<Parrot_base_vtables> array.

To finish up adding a built-in class:

=over 4

=item 1.

Add classes/YOURCLASS.pmc to MANIFEST.

=item 2.

Rerun Configure.pl to add your new PMC to the set of built-in PMCs.

=back

=head2 What You Can and Cannot Do

The usual way to continue from the F<genclass.pl>-generated skeleton
is to define a structure that will hook onto the C<data>, if your data
type needs to use that, and then also define some user-defined flags.

Flags are accessed by C<< pmc->flags >>. Most of the bits in the flag word
are reserved for use by parrot itself, but a number of them have been
assigned for general use by individual classes. These are referred to as
C<Pobj_private0_FLAG> .. C<Pobj_private7_FLAG>. (The '7' may change during the
early development of parrot, but will become pretty fixed at some point.)

Normally, you will want to alias these generic bit names to something
more meaningful within your class:

    enum {
        Foobynumber_is_bignum = Pobj_private0_FLAG,
        Foobynumber_is_bigint = Pobj_private1_FLAG,
        ....
    };

You're quite at liberty to declare these in a separate header file, but I
find it more convenient to keep everything together in F<foobynumber.c>.

You may also use the C<cache> union in the PMC structure to remove
some extraneous dereferences in your code if that would help.

=head2 Multimethods

One slightly (potentially) tricky element of implementing vtables
is that several of the vtable functions have variant forms depending on
the type of data that they're being called with.

For instance, the C<set_integer> method has multiple forms; the
default C<set_integer> means that you are being called with a PMC,
and you should probably use the C<get_integer> method of the PMC to
find its integer value; C<set_integer_native> means you're being passed
an C<INTVAL>. The final form is slightly special; if the
interpreter calls C<set_integer_same>, you know that the PMC that you
are being passed is of the same type as you. Hence, you can break the
class abstraction to save a couple of dereferences - if you want to.

Similar shortcuts exist for strings, (C<native> and C<same>) and
floating point numbers.

=head2 Methods you need to implement

The master list of vtable methods can be found in F<vtable.tbl> in
the root directory of the Parrot source; since that's not exactly
verbose, here's a better description of the methods that you need to
implement:

=over 3

=item C<type>

Return the enumeration value of your class.

=item C<name>

Return a string containing your class name.

=item C<init>

Do any data set-up you need to do.

=item C<is_equal>

True if the passed-in PMC has the same B<value> as you. For instance,
a Perl integer and a Python integer could have the same value, but
could not be the same thing as defined by C<is_same>.

=back

=head2 Methods, you might need, depending on your class

=over 3

=item C<clone>

Copy your data and state into the passed-in destination PMC.

=item C<morph>

Turn yourself into the specified type.

=item C<destroy>

Do any data shut-down and finalization you need to do. To have this
method called, you must set the C<Pobj_active_destroy_FLAG>.

=item C<get_integer>

Return an integer representation of yourself.

=item C<get_number>

Return a floating-point representation of yourself.

=item C<get_string>

Return a string representation of yourself (a STRING* object), this
should be a B<copy> of whatever string you are holding, not just a
pointer to your own string so that anything that calls this method can
happily modify this value without making a mess of your guts.

=item C<get_bool>

Return a boolean representation of yourself.

=item C<get_value>

Return your private data as a raw pointer.

=item C<is_same>

True if the passed-in PMC refers to exactly the same B<data> as
you. (Contrast C<is_equal>)

=item C<set_integer>

Set yourself to the passed-in integer value. This is an integer
multimethod.

=item C<set_number>

Set yourself to the passed-in float value. This is an floating-point
multimethod.

=item C<set_string>

Set yourself to the passed-in string. This is a string multimethod.

=item C<set_value>

Set your private data to the raw pointer passed in. This will only
be used in exceptional circumstances.

=item C<add>

Fetch the number part of C<value> and add your numeric value to it,
storing the result in C<dest>. (Probably by calling its C<set_integer>
or C<set_number> method) This is a numeric multimethod.

=item C<subtract>

Fetch the number part of C<value> and subtract your numeric value from it,
storing the result in C<dest>. (Probably by calling its C<set_integer>
or C<set_number> method) This is a numeric multimethod.

=item C<multiply>

=item C<divide>

=item C<modulus>

You get the picture.

=item C<concatenate>

Fetch the string part of C<value> and catenate it to yourself,
storing the result in C<dest>. (Probably by calling its C<set_string>
method) This is a string multimethod.

=item C<logical_or>

=item C<logical_and>

Perform the given short-circuiting logical operations between your boolean
value and the value passed in, storing the result in C<dest>.

=item C<logical_not>

Set yourself to be a logical negation of the value passed in.

=item C<match>

Execute the given regular expression on C<value> and store the result.

=item C<repeat>

Repeat your string representation C<value> times and store the result
in C<dest>.

=back

If any method doesn't fit into your class, just don't implement it
and don't provide an empty function body. The default class, which all
classes inherit from, will through an exception, if this method would
be called.

If your class is a modification of an existing class, you may wish to
use inheritance. At the beginning of your vtable specification in
classes/YOURCLASS.pmc, add the C<extends SUPERCLASS> phrase. For
example:

  pmclass PackedArray extends Array { ...

See the POD documentation in classes/pmc2c.pl for a list of useful
keywords that you may use in the .pmc file. (Run
C<perldoc -F pmc2c.pl> to view the POD.)