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.