perlhacktut

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• ОПИСАНИЕ
• ПРИМЕР ПРОСТОЙ ОБНОВЛЕНИЯ
  • Создание обновления
  • Тестирование обновления
  • Документирование обновления
  • Отправка
• АВТОР

НАЗВАНИЕ

perlhacktut - Пошаговое руководство по созданию простого обновления кода C

ОПИСАНИЕ

В этом документе показан пример простого обновления.

Если вы еще не читали perlhack, сделайте это сначала! Также вам может быть полезно ознакомиться с perlsource.

После завершения работы с этим документом, переходите к perlhacktips.

ПРИМЕР ПРОСТОЙ ОБНОВЛЕНИЯ

Рассмотрим простой пример обновления от начала до конца.

Вот что предложил Ларри: если U является первым активным форматом во время pack, (например, pack "U3C8", @stuff) то результирующая строка должна рассматриваться как закодированная в UTF-8.

Если вы работаете с копией репозитория Perl с помощью git, вам необходимо создать ветку для ваших изменений. Это значительно упростит создание правильного обновления. Подробности о том, как это сделать, см. в perlgit.

Создание обновления

Как подготовиться к исправлению? Сначала найдем нужный код - pack происходит во время выполнения, поэтому он будет в одном из файлов pp. Действительно, pp_pack находится в файле pp.c. Поскольку мы собираемся изменить этот файл, скопируем его в pp.c~.

[Ну, он был в pp.c, когда этот учебник был написан. Теперь он разделен с pp_unpack в отдельный файл pp_pack.c]

Теперь давайте посмотрим на pp_pack: мы вводим шаблон в pat, а затем перебираем шаблон, взяв каждый символ формата по очереди в datum_type. Затем для каждого возможного символа формата мы поглощаем другие аргументы в шаблоне (ширина поля, символ звездочки и т. д.) и преобразуем следующий фрагмент входных данных в указанный формат, добавляя его к выходу SV cat.

Как узнать, если U является первым форматом в pat? Если у нас есть указатель на начало pat, то, если мы видим U, мы можем проверить, находимся ли мы еще в начале строки. Таким образом, вот где pat настраивается:

STRLEN fromlen;
char *pat = SvPVx(*++MARK, fromlen);
char *patend = pat + fromlen;
I32 len;
I32 datumtype;
SV *fromstr;

У нас будет другой указатель на строку:

   STRLEN fromlen;
   char *pat = SvPVx(*++MARK, fromlen);
   char *patend = pat + fromlen;
+  char *patcopy;
   I32 len;
   I32 datumtype;
   SV *fromstr;

И непосредственно перед началом цикла мы установим patcopy на начало pat:

   items = SP - MARK;
   MARK++;
   SvPVCLEAR(cat);
+  patcopy = pat;
   while (pat < patend) {

Теперь, если мы увидим U, которое находилось в начале строки, мы включим флаг UTF8 для вывода SV, cat:

+  if (datumtype == 'U' && pat==patcopy+1)
+      SvUTF8_on(cat);
   if (datumtype == '#') {
       while (pat < patend && *pat != '\n')
           pat++;

Помните, что это должно быть patcopy+1, так как первый символ строки - это U, который был поглощен datumtype!

О, мы забыли кое-что: что, если в начале шаблона есть пробелы? pack(" U*", @stuff) будет иметь U в качестве первого активного символа, даже если это не первое значение в шаблоне. В этом случае нам нужно продвинуть patcopy вместе с pat, когда мы видим пробелы:

if (isSPACE(datumtype))
    continue;

должно стать

if (isSPACE(datumtype)) {
    patcopy++;
    continue;
}

Хорошо. Часть с C закончена. Теперь нам нужно сделать две дополнительные вещи, прежде чем это обновление будет готово: мы изменили поведение Perl, поэтому нам нужно задокументировать это изменение. Мы также должны предоставить больше регрессионных тестов, чтобы убедиться, что наше обновление работает и не создает ошибок в других частях.

Тестирование обновления

Регрессионные тесты для каждого оператора находятся в папке t/op/, поэтому мы копируем t/op/pack.t в t/op/pack.t~. Теперь мы можем добавить наши тесты в конец. Сначала мы проверим, что U действительно создает строки Unicode.

В t/op/pack.t есть разумная функция ok(), но если бы её не было, мы могли бы использовать функцию из t/test.pl.

require './test.pl';
plan( tests => 159 );

следовательно, вместо этого:

print 'not ' unless "1.20.300.4000" eq sprintf "%vd",
                                              pack("U*",1,20,300,4000);
print "ok $test\n"; $test++;

мы можем написать более разумное (см. Test::More для полного объяснения функций is() и других функций тестирования).

is( "1.20.300.4000", sprintf "%vd", pack("U*",1,20,300,4000),
                                      "U* produces Unicode" );

Теперь мы проверим, что мы правильно обработаем пробелы в начале:

is( "1.20.300.4000", sprintf "%vd", pack("  U*",1,20,300,4000),
                                    "  with spaces at the beginning" );

И, наконец, проверим, что мы не создаём строки Unicode, если U не является первым активным форматом:

isnt( v1.20.300.4000, sprintf "%vd", pack("C0U*",1,20,300,4000),
                                      "U* not first isn't Unicode" );

Нельзя забыть изменить количество тестов, которое отображается вверху, иначе автоматический тестер запутается. Это будет выглядеть так:

print "1..156\n";

или так:

plan( tests => 156 );

Теперь мы компилируем Perl и запускаем набор тестов. Наши новые тесты пройдены, ура!

Документирование обновления

Наконец, документация. Работа никогда не заканчивается, пока не закончены все документы, поэтому опишем внесённые изменения. Соответствующее место — pod/perlfunc.pod; снова создадим копию и вставим этот текст в описание pack:

=item *

If the pattern begins with a C<U>, the resulting string will be treated
as UTF-8-encoded Unicode. You can force UTF-8 encoding on in a string
with an initial C<U0>, and the bytes that follow will be interpreted as
Unicode characters. If you don't want this to happen, you can begin
your pattern with C<C0> (or anything else) to force Perl not to UTF-8
encode your string, and then follow this with a C<U*> somewhere in your
pattern.

Отправка

См. perlhack для получения подробной информации об отправке этого обновления.

АВТОР

Этот документ был первоначально написан Нейтаном Торкингом и поддерживается почтовой рассылкой perl5-porters.