Удачный Raku'rs

Java аннотации в Raku | Java Annotations in Raku

2021-12-05T15:21:36.382Z

Сегодня немного про то, что новое лучше усваивается через уже известное. Так сложилось, что на $dayjob я пишу на Java, по-этому зайду именно с его стороны. В Java 1.5 появилась интересная синтаксическая форма — аннотации. Выглядит это как-то так:

/**
 * @deprecated use #getId() method instead
 */
@Override
public String getName() {
  return "stub"
}

В примере показана аннотация @Deprecated, которая заставляет среду выполнения выводить предупреждение в консоль каждый раз, когда используется метод getName. Кроме того, в Javadoc добавлена поясняющая информация.

Вообще, аннотации в Java это механизм добавления некоторых метаданных в классы, объекты, типы и прочее, которые можно использовать в последствии на этапе компиляции, исполнения или статического анализа кода. С помощью них, например, можно реализовать стратегию разделения (decouple) кода — чтобы одни компоненты программы работали совместно с другими, не имея жёсткой связи. На этой стратегии построена идея Инверсии Управления и ядро библиотеки Spring.

Но хватит про Java. Что есть в Raku похожего на механизм аннотаций? В Raku есть Traits — синтаксис, которым можно пометить классы и объекты. Эти метки обрабатываются во время компиляции программы. В зависимости от желания программиста, эффект такой обработки может оказывать влияние и на ход выполнения программы.

Например, рассмотрим аналогичную аннотации @Deprecated конструкцию из спецификации Raku:

sub get-name(--> Str) is DEPRECATED('get-id() method') {
  'stub'
}

is DEPRECATED и есть trait. В аргументе можно сообщить альтернативу устаревшему коду. После завершения программы, во время выполнения которой вызывалась функция get-name(), будет выведено сообщение о том, где и сколько раз выполнялся устаревший код:

Saw 1 occurrence of deprecated code.
======================================================================
Sub get-name (from GLOBAL) seen at:
  ~/advent.raku, line 13
Please use get-id() method instead.
----------------------------------------------------------------------
Please contact the author to have these occurrences of deprecated code
adapted, so that this message will disappear!

Устареваем

is DEPRECATED это trait из стандартной библиотеки. Чтобы разобраться в том, как он работает, попробуем написать свой аналог под названием obsolete. Сначала определимся с хранилищем собираемой информации — класс, который хранит и обновляет количество вызовов функции и умеет вывести отчёт:

class ObsoletTraitData {
  has $.routine-name is required;
  has $.user-hint;
  has $!execution-amount = 0;
  method executed() { $!execution-amount++ }
  method report() {
    return unless $!execution-amount;
    note "Obsolete routine $!routine-name is execcuted $!execution-amount times.";
    note $_ with $!user-hint;
  }
}

Теперь объявляем тестовый trait — это обычная multi функция с именем trait_mod:<is> и двумя аргументами: первый — к чему будет применяться trait (в нашем случае это функция Routine), второй — имя:

say 'run-time';
multi trait_mod:<is>(Routine $r, :$obsolete!) {
  say 'compile-time'
}
sub get-name(--> Str) is obsolete {
  'stub'
}
say get-name;

# Output: compile-time
#         run-time 
#         stub

Самое важное, что нужно понять о traits — их функции исполняются во время компиляции, а не выполнения программы. Это наглядно видно из вывода кода выше. Вспомним, чего мы хотим добиться — отчета об исполнении устаревшего кода перед завершением работы программы. Эту информацию мы можем получить только во время исполнения. Чтобы повлиять на исполнение из стадии компиляции, trait должен как-то модифицировать функцию. В нашем случае можно добавить в функцию phaser ENTER. Это специальный блок, который выполняется перед выполнением первой инструкции функции. То есть, мы ходим, чтобы функция get-name выглядела как-то так:

sub get-name(--> Str) {
  ENTER { $obsolet-trait-data.executed }
  'stub'
}

Код самой функции мы трогать не можем, но можем сделать необходимые манипуляции во время компиляции. Берём имя функции, возможную подсказку для пользователя, заводим новый объект типа ObsoletTraitData, кладём его в локальную ассоциативную переменную %obsolet-trait-data и добавляем необходимый phaser:

my ObsoletTraitData %obsolet-trait-data;

multi trait_mod:<is>(Routine $r, :$obsolete!) {
  my $routine-name = $r.name;
  my $user-hint = $obsolete ~~ Str ?? $obsolete !! Any;
  %obsolet-trait-data{$routine-name} =
    ObsoletTraitData.new(:$routine-name, :$user-hint);
  $r.add_phaser('ENTER', -> {
    %obsolet-trait-data{$routine-name}.executed;
  });
}

Теперь, при выполнении функции get-name, объект ObsoletTraitData будет обновлять своё состояние. Таким образом, мы повлияли на ход выполнения программы во время её компиляции. Осталось только вывести отчёт. Для этого мы добавим ещё один phaser END в основной код. Его блок исполняется перед самым завершением программы. Таким образом получим следующую картину:

class ObsoletTraitData { ... }

my ObsoletTraitData %obsolet-trait-data;

END { .report for %obsolet-trait-data.values }

multi trait_mod:<is>(Routine $r, :$obsolete!) { ... }

sub get-name(--> Str) is obsolete('Please use get-id() instead.') {
  'stub'
}
sub anouther-obsolet() is obsolete {}

get-name();
anouther-obsolet();
get-name();

# Output:
# Obsolete routine get-name is execcuted 2 times.
# Please use get-id() instead.
# Obsolete routine anouther-obsolet is execcuted 1 times.

Переопределяем

С @Deprecated закончили. Другая часто используемая аннотация в Java это @Override - ей помечется метод класса. Случай, когда он не переопределяет метод супер-класса, считается ошибкой компиляции. Сделать аналогичный trait будет несложно - нам не придёт выходить за пределы стадии компиляции. Объявляем trait с именем override, применимый только к методам:

multi trait_mod:<is>(Method $m, :$override!) {

Проверяем, что метод является членом класса, иначе заканчиваем работу:

return unless $m.package.HOW ~~ Metamodel::ClassHOW;

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

my $class = $m.package;
my $method-point = $class.^name ~ '::' ~ $m.name;
my @parents = $class.^mro[1 ..^ *-2];
die "is override trait cannot be used without parent class $method-point." unless @parents;

Проходим по всем родителям и их методам в поисках одного, который совпадает по имени и сигнатуре. Сравнения сигнатур методов на одинаковость это не очень тривиальная задача, и здесь мы скроем её реализацию за функциейcheck-signature-eq:

for @parents -> $parent {
  for $parent.^methods -> $parent-method {
    return if $parent-method.name eq $m.name &&
      check-signature-eq($parent-method.signature, $m.signature)
  }
}

В случае, если искомого метода у родителей не нашлось, придётся выдавать ошибку:

die "$method-point does not override any parent methods.";

В результате получаем следующее:

multi trait_mod:<is>(Method $m, :$override!) { ... }

class A {
  method from-a(:$r) {}
}

class B is A {
  method from-a($r) is override {
    say 'from-b'
  }
}

# Output: B::from-a does not override any parent methods.
# Exit code: 1

Подавляем

Нам уже удалось реализовать логику работы Java аннотаций @Deprecated и @Override. Попробуем реализовать логику @SuppressWarnings. Эта аннотация применяется к функции и подавляет её предупредительные сообщения. Так же, можно указать какие именно предупреждения будут подавляться.

В Raku предупреждения можно вывести с помощью функции warn. Она порождает специальное исключение, которое выводится в поток ошибок, а процесс выполнения возобновляется с прежнего места. Перехватить такое исключение можно с помощью специального phaser CONTROL. То есть, как и в случае с @Deprecated, нам нужно модифицировать функцию, добавив нужный phaser. Давайте попробуем что-то новое и вместо add_phaser используем обёртку функции. Как это работает? Мы заменяем одну функцию другой, которая может по своему усмотрению вызвать оригинал (методом callsame). Внутрь этой функции мы и вставим phaser CONTROL, который будет имитировать стандартное поведение, но только не для подавляемых предупреждений:

multi trait_mod:<is>(Routine $b, :$suppress-warnings) {
  my $regex = $suppress-warnings ~~ Str ?? / <$suppress-warnings> / !! Any;
  $b.wrap(sub with-control(|c) {
    callsame;
    CONTROL {
      when CX::Warn {
        .note if $regex.defined && $_.message !~~ $regex;
        .resume
      }
    }
  });
}

sub work-in-progress() is suppress-warnings('todo') {
  warn 'important warn';
  warn 'todo warn';
  say 'WIP';
}

work-in-progress()

# Output:
# important warn
#  in sub work-in-progress at ~/trait-supress.raku line 15
# WIP

Сериализуем

Осталось только обсудить аннотации, определяемые пользователем. Как я уже сказал выше, аннотации Java это способ прикрепить некоторую мета-информацию к классу или объекту. После этого, во время компиляции или чаще всего исполнения, аннотированные объекты проверяются на предмет обладания нужной информацией. В Raku для этого отлично подойдут роли. Рассмотрим задачу добавления в класс простейшей системы сериализации. Напишем класс и разметим нашим будущим trait:

class Person is serialize-name('Passport') {
  has $.first;
  has $.second is serialize-name('Second name');
  has $.third is serialize-name('Honorific');
}

Видно, что trait serialize-name применяется и к самому классу и к его атрибутам.

Trait для атрибута выглядит так:

role SerializableAttribute {
  has $.serialize-name;
}

multi trait_mod:<is>(Attribute $a, :$serialize-name) {
  $a does SerializableAttribute(:$serialize-name);
}

Тут trait добавляет в атрибут новую роль SerializableAttribute. Эта роль сама привносит новый атрибут в атрибут :) Значение нового атрибута trait передаёт через свой аргумент.

Trait для класса выглядит следующим образом:

role SerializableClass[$name] {
  method serialize() {
    say $name, ' | ', self.^name;
    say .serialize-name, ' <- ', .get_value(self)
      for self.^attributes(:local).grep(*.^can('serialize-name'));
  }
}

multi trait_mod:<is>(Mu:U $c, :$serialize-name!) {
  return unless $c.HOW ~~ Metamodel::ClassHOW;
  $c.^add_role(SerializableClass[$serialize-name]);
}

Тут trait проверяет, что применяется именно к классу и добавляет специальную роль SerializableClass. Эта роль добавляет в класс новый метод serialize, который реализует всю логику по сериализации. В частности, он фильтрует список всех атрибутов класса по признаку наличия метода serialize-name.

Если всё это запустить, то получим:

Person.new(:first<John>, :second<Hancock>, :third<Mr>).serialize();

# Output:
# Passport | Person
# second-name <- Hancock
# honorific <- Mr

Заключение

Как мы видим, traits это довольно мощный инструмент, но, как и всё в мире Raku, его можно использовать очень по-разному. Например, в Java, при объявлении своей аннотации, программист должен указать, до какой стадии распространяется её действие (только на уровне кода, до конца компиляции или до завершения приложения). Ещё можно указать, будет ли аннотация наследоваться дочерними классами, и можно ли её указывать несколько раз. С другой стороны, traits в Raku предоставляют программисту полную свободу действий. Теперь вы обладаете знаниями, достаточными, чтобы написать свою IoC/DI систему наподобие Java Spring Core с помощью Raku traits.

English version

#rakulang

#traits

#java

#annotation

#аннотации

#deprecated

#override

#suppresswarnings

#serialization

Библиотека модулей Raku: Зеркалируем репозитории | Raku Module Library: Mirroring repositories

2021-11-30T08:19:56.951Z

Популярность языка программирования зависит не только (и не столько) от его дизайна и реализации, но и от огромного числа сторонних вещей. Таких, как качество и количество документации, удобная среда разработки, отзывчивое сообщество единомышленников, библиотека модулей на все случаи жизни и прочее. Сегодня как раз про библиотеку модулей языка Raku. А точнее, про систему их хранения и распространения.

Что есть в природе

Если посмотреть в миры Java, Python, JavaScript, Perl — всё примерно одинаково. Есть де-факто центральный публичный репозиторий (Nexus, PyPI, npm-registry, CPAN), есть сколько-то альтернатив и зеркал, есть возможность поднять свой.

Что есть в мире Raku

Основной менеджер пакетов для Raku называется zef. Сейчас он работает следующим образом: берёт с какого-то сервера индекс, анализирует его и скачивает необходимые перечисленные в нём модули. Так можно делать с несколькими серверами.

Изначально, в качестве сервера для распространения модулей служил GitHub. Это дешёвое и сердитое решение. Индексы считают на сторонней машине про cron и выкладывают в отдельный git репозиторий. Сейчас в этом ‘сервере’ хранятся индексы о более чем восьмистах версий различных модулей. Эта схема получила название p6с. Минусы её очевидны — завязывание на одну проприетарную платформу, которая изначально спроектирована для других целей.

Второй попыткой стала проба использовать CPAN для нужд Raku. Если без подробностей, то модули в Perl и Raku немного отличаются по структуре, и CPAN пришлось грубо допиливать. В конечном итоге он стал просто хранилищем, неким FTP сервером. Индексы так же считают на сторонней машине про cron и выкладывают в отдельный git репозиторий. На данный момент это самая большая библиотека модулей — их там больше 2700 версий.

Третьей попыткой, почти год назад, стал проект fez. Если CPAN предоставлял только возможности FTP сервера, то fez решил идти дальше и добавил несколько полезных вещей. Таких, как улучшенная система авторизации, правильная работа с номерами версий модулей, мгновенная индексация на стороне репозитория. Плюс, так как это специальный проект, созданный именно для нужд Raku, то он имеет отличные возможности для качественного развития.

Первое время я с настороженностью относился к fez, но в последствии изменил своё мнение. Проект достаточно стабильный и отлично выполняет свои функции.

Что хочется ещё

Для успокоения души мне не хватает зеркал сервера fez. Для чего нужно зеркало вообще?

Дело в том, что мы живём во время, когда информационные сети стали неимоверно сложными, а желания их контролировать слишком высокими. Где-то специально, где-то случайно закрывается доступ к очень большим, важным и привычным ресурсам. Нет уверенности в том, что завтра утром ты сможешь получить доступ к своим данным, хранящимся где-то там. Благо это или нет, но это стало нашей сегодняшней реальностью. От сюда есть вполне естественное желание диверсифицировать риски. Один из способов — иметь зеркало библиотеки модулей.

Хочешь сделать что-то хорошо - сделай сам

Хорошо сделать не обещаю, но так как альтернатив никаких, то сойдёт любое решение. Ниже я покажу как можно локально развернуть зеркало для модулей, хранящихся в CPAN и fez (p6c используется малоактивно, и зеркалировать git хостинг это отдельная задача). Нам понадобится curl, grep, awk, sed, sh и docker.

Исходя из логики работы zef, принципиально нужно:

Скачать индексный файл;
Скачать все перечисленные в нём архивы с модулями;
Повторить 1 и 2 для каждого репозитория;
Поднять и настроить nginx, чтобы он умел отдавать скачанные индексы и архивы;
Сказать zef по какому адресу лежит зеркало.

Скачиваем индексный файл

Все настройки zef лежат в файле config.json. В документации к zef сказано, чтобы узнать с каким дефолтным конфигом запускается zef, нужно выполнить zef --help:

> zef --help
[..]
CONFIGURATION ~/.rakubrew/versions/moar-2021.10/install/share/perl6/site/
resources/250C9FFF9756350CAA0F60C1873CDD80F2EB7A77.json
[..]

> cat ~/.rakubrew/versions/moar-2021.10/install/share/perl6/site/
resources/250C9FFF9756350CAA0F60C1873CDD80F2EB7A77.json
[..]
{
  "short-name": "fez",
  "enabled": 1,
  "module": "Zef::Repository::Ecosystems",
  "options": {
    "name": "fez",
    "auto-update": 1,
    "uses-path": true,
    "mirrors": [
      "http://360.zef.pm/"
    ]
  }
},

В разделе mirrors конфигурации для fez видим URI — то что нам нужно.

> mkdir -p ~/local-zef/local-fez && cd ~/local-zef/local-fez
local-fez> curl https://360.zef.pm -o index.json

Скачиваем архивы модулей

В индексе fez относительный путь архиву модуля лежит в поле path. Например:

{
[..]
	"name": "fez",
	"path": "F/EZ/FEZ/259a4732c97520938ce7310b3a1330db75bf91d0.tar.gz",
	"perl": "6.c",
[..]
	"source-url": "https://github.com/tony-o/raku-fez.git",
	"version": "17"
}

Сейчас нужно вытащить все значения path и составить один большой curl запрос. Немного sed-awk-магии:

local-fez> grep -o '"path":"[^"]*"' index.json | \
awk -F\" '{print $4}' | \
sed 's|\(.*\)| -o \1 https://360.zef.pm/\1|g' | \
awk -v d="" '{s=(NR==1?s:s d)$0}END{print s}' | \
sed 's/\(.*\)/curl -Z --create-dirs \1/' | \
sh

DL% UL%  Dled  Uled  Xfers  Live   Qd Total     Current  Left    Speed
100 --  36.6M     0   623     0     0  0:00:06  0:00:11 --:--:-- 5440k

local-fez> ls

A  D  G  J  M  P  T  W
B  E  H  K  N  R  U  Y
C  F  I  L  O  S  V  index.json

Повторяем для CPAN

Таким же образом можно скачать индекс и весь архив для CPAN:

> mdkir -p ~/local-zef/local-cpan && cd ~/local-zef/local-cpan
local-cpan> curl https://raw.githubusercontent.com/ugexe/Perl6-ecosystems/master/cpan1.json -o index.json
local-cpan> grep -o '"source-url": "[^"]*"' index.json | \
awk -F\" '{print $4}' | \
sed 's|http://www.cpan.org/authors/id/\(.*\)|\1|g' | \
sed 's|\(.*\)| -o \1 http://www.cpan.org/authors/id/\1|g' | \
awk -v d="" '{s=(NR==1?s:s d)$0}END{print s}' | \
sed 's|\(.*\)|curl -Z --create-dirs \1|' | \
sh

DL% UL%  Dled  Uled  Xfers  Live   Qd Total     Current  Left    Speed
100 --   337M     0  2767     0     0  0:00:54  0:00:41 --:--:-- 6308k

local-cpan> rm -rf ./git:

local-cpan> sed 's|"source-url": "http://www.cpan.org/authors/id|"source-url": "http://localhost/local-cpan|g' index.json > index-fix-uri.json

local-cpan> ls

A    G    N    V
B    H    P    W
C    J    R    Y
D    K    S    index-fix-uri.json
E    L    T    index.json
F    M    U

Различия в ситуации со CPAN следующие:

Путь к архиву абсолютный и лежит в поле source-url. Соответственно, нам нужно подправить индексный файл, чтобы путь вёл не на cpan.org, а на наш localhost;
В индексе упоминаются несколько (около шести) устаревших модуля с неверными source-url. Они порождают папку git:, которая нам совершенно не нужна.

Поднимаем и настраиваем nginx

Для начала нужно написать конфигурационный файл для nginx:

cd ~/local-zef
local-zef> vim nginx.conf
[..]
local-zef> cat nginx.conf
events { worker_connections 1024; }
http {
  server {
    listen 80;
    root	/usr/share/nginx/html;
    location /local-fez { index /local-fez/index.json; }
    location /local-cpan { index /local-cpan/index-fix-uri.json; }
  }
}

Затем поднимаем nginx в docker, монтируем папку с архивами и индексами, и подкладываем нашу конфигурацию:

cd ~/local-zef
local-zef> docker run -it -p 80:80 \
-v /$PWD://usr/share/nginx/html:ro \
-v /$PWD/nginx.conf://etc/nginx/nginx.conf:ro \
--name=local-zef \
nginx:alpine

После этих манипуляций у нас имеется поднятый web-сервер, который отдаст индексы для fez и cpan по адресам http://localhost/local-zef и http://localhost/local-cpan соответственно. Кроме того, с сервера можно скачать архивы по ссылкам из индекса.

Настраиваем zef

Я предпочитаю завести отдельный конфиг для zef. Относительно оригинального в нём нужно поменять пути до хранилища и временной папки, а так же имена и uri в разделах про fez и cpan репозитории:

cd ~/local-zef
local-zef> cp ~/.rakubrew/versions/moar-2021.10/install/share/perl6/site/resources/250C9FFF9756350CAA0F60C1873CDD80F2EB7A77.json zef.json
local-zef> vim zef.json
[..]
local-zef> cat zef.json
[..]
"StoreDir" : "$*HOME/.zef/store_local",
"TempDir"  : "$*HOME/.zef/tmp_local",
[..]
{
  "short-name": "local-fez",
  "enabled": 1,
  "module": "Zef::Repository::Ecosystems",
  "options": {
    "name": "local-fez",
    "auto-update": 1,
    "uses-path": true,
    "mirrors": [
      "http://127.0.0.1/local-fez/"
    ]
  }
}
[..]
{
  "short-name" : "local-cpan",
  "enabled" : 1,
  "module" : "Zef::Repository::Ecosystems",
  "options" : {
    "name" : "local-cpan",
    "auto-update" : 1,
    "mirrors" : [
      "http://127.0.0.1/local-cpan/"
    ]
  }
}

Теперь мы можем установить модуль из локального зеркала таким образом:

zef --config=~/local-zef/zef.json install LogP6

Централизованный архив всех модулей Raku

Существует проект REA (The Raku Programming Language Ecosystem Archive), в который регулярно собираются все когда-либо опубликованные модули. Кроме того, есть специальный модуль Raku, который позволяет иметь похожий архив самостоятельно. Пока что zef не умеет работать с этим архивом как источником данных, но есть смысл написать отдельный плагин.

Заключение

Я очень надеюсь, что проект fez будет продолжать активно развиваться. По словам автора, сейчас fez это набор из AWS-ламбда, S3 и Сloudfront, но никак не код. Думаю, есть смысл написать реализацию fez в коде. Тогда можно будет легко разворачивать реальные альтернативные сервера, например для корпоративных целей. Пожелаем удачи!

English version

#rakulang

#удачныйракурс

#zef

#fez

#repository

#modules

#docker

#nginx

Измерение уровня покрытия кода тестами в Raku | Code coverage level measurement in Raku

2021-11-27T17:05:06.850Z

Легко заметить одну особенность в культуре написания модулей на Raku и Perl — почти всегда присутствует папка t с авто тестами. Даже в маленьких проектах. Конечно, количество и качество тестов может варьироваться, но чаще всего они есть.

Когда мы говорим об авто тестировании, возникает желание как-то оценить «качество» написанных тестов. Одним из критериев может являться процент исполненных строк (веток) кода во время успешного прохождения тестов. На данный момент для Raku это можно сделать двумя способами.

Первый — с помощью CommaIDE (https://commaide.com), IDE для разработки на языке Raku. CommaIDE это отличная вещь, особенно, после последних релизов. Я настоятельно рекомендую её попробовать. В платной версии IDE есть возможность запустить тесты, и посчитать процент покрытия кода. Кроме того, для наглядности, код раскрасится в соответствующие цвета.

Второй — использовать модуль App::RaCoCo (Raku Code Coverage). Он поставляет консольное приложение racoco, которое запускает тесты, и подсчитывает процент покрытия. Сегодня хочется рассказать об этом модуле подробнее.

Как это работает в теории

Чтобы посчитать покрытие, нам нужно знать две вещи: какие именно строки кода потенциально могут выполниться, и фактически выполненные во время прохождения тестов.

NB: существуют несколько бекендов для компилятора Raku (например, jvm, js, moarvm). На данный момент предоставить всю необходимую информацию может только MoarVM. Кроме того, более информативно считать не выполненные строки кода, а ветви. Например, в одной строке
say 'second' if $first;две ветви. К сожалению, сейчас даже MoarVM не предоставляет информации о выполненных ветвях. По-этому, далее будет говориться только о выполненных строках.

Как это работает на практике

Чтобы получить список потенциально исполняемых строк кода некоторого файла, нужно:

получить байт-код этого файла. Его можно или найти в папке lib/.precomp, или скомпилировать самостоятельно. Например,
raku -Ilib --target=mbc --output=result lib/source-file.rakumod;
снять дамп с этого файла командой moar --dump result. Вхождения, начинающиеся со слова annotation, заканчиваются номером строки, которая может быть исполнена в соответствующем модуле. Например:

[...]
00013      bindlex            lex_Frame_9_self_obj, loc_19_obj
00014      param_sn           loc_4_obj
     annotation: lib/source-file.rakumod (MyModuleName):9
00015      getcode            loc_1_obj, Frame_10
00016      getcode            loc_2_obj, Frame_11
[...]

Чтобы получить данные о том, какие строки выполнились, нужно:

положить в переменные окружения специальный флаг MVM_COVERAGE_LOG. Его значением должен являться путь к файлу с будущими логами исполнения кода;
запустить тесты;
разобрать файл с логами. Нас интересуют только строки с файлами из тестируемой библиотеки. Например:

HIT  src/vm/moar/ModuleLoader.nqp  133
HIT  src/vm/moar/ModuleLoader.nqp  5
HIT  lib/source-file.rakumod (MyModuleName)  1
HIT  lib/source-file.rakumod (MyModuleName)  9
HIT  gen/moar/World.nqp  5240
HIT  gen/moar/World.nqp  5240

Имея эти данные и немного знаний об арифметике можно посчитать результат.

Как это использовать

Рассмотрим несколько типичных вариантов использования racoco.

MyModyle> racoco
t/00-simple.t ................... ok 
t/01-difficult.t ................ ok  
All tests successful.
Files=2, Tests=54,  3 wallclock secs
Result: PASS                        # prove6 result 
Coverage: 70.6%                     # code coverage percentage

MyModule> racoco --exec='prove --exec=raku'
t/00-simple.t ................... ok 
t/01-difficult.t ................ ok
All tests successful.
Files=2, Tests=54, 3 wallclock secs
Result: PASS                        # prove result
Coverage: 70.8%

MyModule> racoco --exec='prove6 -l' # this is for who do not write
                                    # ｢use lib 'lib';｣ in tests
[...]

MyModule> racoco --silent
Coverage: 70.8%          # just what it was all about

MyModule> racoco --html  # HTML with statistics and colored code
Visualisation: file://.racoco/report.html
Coverage: 70.8%

Список файлов модуля со статистикой

MyModule> racoco --/exec --html --color-blind
            # don't run tests, use the latest data
            # and color code for colorblind people

Раскрашеный код для дальтоников

MyModule> racoco --fail-level=93   # the launch should fail
[...]                              # in case of low coverage
Coverage: 70.8%      # exit code: 23 (93 - 70 = 23)

MyModule> racoco --silent
Coverage: 70.8%
MyModule> racoco --silent --append --exec='prove6 xt'
Coverage: 95.2%  # combined coverage of both launches
                 # similarly --exec='prove6 t xt'

/root/  > racoco --lib='/home/user/raku/MyModule/lib' \
                 --exec='prove6 /home/user/raku/MyModule/t'
                 # launch not from the module folder

MyModule> racoco --raku-bin-dir='/home/user/hack-rakudo/install/bin'
               # explicit indication of the path to raku and moar

Неочевидный момент

racoco может выбросить сообщение об ошибке про неочевидное содержимое папки .precomp. Это происходит из-за того, что папка содержит подпапки для каждой использованной версии компилятора. В общем случае, пользователь может выбрать любую версию компилятора для запуска тестов. При этом, если нет необходимости, скомпилированные ранее файлы могут быть не обновлены. Таким образом, racoco не может угадать какую папку анализировать. Для подобных случаев существует флаг --fix-compunit, который удалит всё содержимое папки .precomp самостоятельно (если вам дорого время компиляции, то можно уничтожить неактуальные версии скомпилированных файлов вручную).

Немного про CI

Невозможно говорить про авто тесты и покрытие кода и не заговорить про CI. В этом контексте измерение покрытия кода может использоваться для нескольких вещей:

Падение сборки в случае снижения покрытия ниже определённого уровня;
Падение сборки в случае снижения покрытия относительно предыдущих значений;
Простое измерение покрытия кода как характеристики.

Для примера, рассмотрим то, как можно добавить шилдик об уровне покрытия кода в README файл на GitHub.

Есть замечательная статья о том, как настроить автоматическую проверку кода тестами с помощью GitHub Actions для проектов на Raku. Первый YAML из этой статьи отлично работает. Нужно заменить последний шаг (Run Tests), на следующую последовательность:

Установить App::RaCoCo. Этот модуль намеренно не содержит никаких зависимостей, чтобы его установка занимала как можно меньше времени;
- name: Install App::RaCoCO run: zef install --/test App::RaCoCo
Запустить racoco;
- name: Run App::RaCoCo run: racoco
Вытащить результат работы racoco из файла .racoco/report.txt. Нам нужна только первая строчка — процент покрытия. Убирается дробную часть и знак процента. Результат складываем во временную переменную окружения сборки COVERAGE;
- name: Discover Code Coverage Level run: | coverage=head -1 .racoco/report.txt | sed 's/\.*//'echo "COVERAGE=$coverage%" >> $GITHUB_ENV shell: bash
Для построения шилдика используем плагин schneegans/dynamic-badges-action;
- name: Create Code Coverage Badge uses: schneegans/dynamic-badges-action@v1.1.0 with: auth: $\{\{ secrets.<YOUR_TOCKEN> }} gistID: <gist-ID> filename: <you-gist-file>.json label: Coverage message: $\{\{ env.COVERAGE }}5. Добавляем строчку со ссылкой на шилдик в README.md.
![badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/<user>/<gist-id>/raw/<you-gist-file>.json)

Пример почти такого YAML и итоговый шилдик можно посмотреть в репозитории App::RaCoCo.

Наглядный уровень покрытия

English version

#rakulang

#удачныйракурс

#codecoverage

#racoco

#покрытиекода

#тестирование

Контрибутинг в Raku для самых маленьких | Raku contributing for the little ones

2021-11-27T14:09:40.430Z

В последние пару недель я несколько раз натыкался на статьи и видео о том, как это здорово — контрибутить в открытое ПО. По этому поводу я вспомнил о другой старой статье «Raku это моя MMORPG». В ней говорится, что приносить пользу открытому ПО можно несколькими способами. Например, можно быть Воином и писать программы, основанные на каком-то открытом ПО. Можно быть Лучником — и писать блоги, твиты и подобное, возбуждая интерес с выбранному ПО. Ещё, можно быть Магом — реализовывать новые фичи и фиксить баги. Сегодня я возьму Лучника и расскажу, как можно стать Магом для языка программирования Raku.

Выбираем квест

Давайте выберем какой-нибудь баг компилятора и пофиксим его. Идём в трекер компилятора Rakudo и выбираем подходящую багу. Я полистал список меток и наткнулся на parsing — удача, я какое-то время назад разбирался в грамматике компилятора и штудировал отличную книжку по этой теме. Есть четыре задачки:

Список открытых задач с меткой parsing

С меткой LTA (Less Than Awesome — чуть менее, чем потрясающе — когда настоящее поведение отличается от интуитивно ожидаемого) — пока вычёркиваем;
С меткой «нужен консенсус» — мы хотим просто пофиксить несложную багу — точно вычёркиваем;
С меткой «grammar and actions» про возможно мёртвый код — хороший кандидат для первой задачки;
Просто «parsing» и что-то про метаоператор R — идеально, берём.

С квестом определились, теперь нужно настроить рабочую среду. В Windows, Linux и macOS всё должно быть примерно одинаково. Я буду показывать на macOS.

Настройка рабочей среды

Создаём папки для исходных кодов и для собранного компилятора:

mkdir ~/dev-rakudo && mkdir ~/dev-rakudo-install

Компилятор Rakudo состоит из трёх компонентов:

Виртуальная машина. Сейчас их есть три — JVM, JS и MoarVM. Мы берём MoarVM, как самую стабильную;
Реализация низкоуровневого (промежуточного) языка NQP (Not Quite Perl) — это некоторое «подмножество» языка Raku. Виртуальная машина как раз позволяет исполнять код, написанный на NQP;
Сам компилятор Rakudo, написанный на NQP и Raku.

Скачиваем и компилируем все три компонента. Их сборка заняла у меня полторы, пол и две с половиной минуты соответственно:

cd ~/dev-rakudo && git clone git@github.com:MoarVM/MoarVM.git && cd MoarVM
perl Configure.pl --prefix ~/dev-rakudo-install && make -j 4 && make install

cd ~/dev-rakudo && git clone git@github.com:Raku/nqp.git && cd nqp
perl Configure.pl --backend=moar --prefix ~/dev-rakudo-install && make -j 4 && make install

cd ~/dev-rakudo && git clone git@github.com:rakudo/rakudo.git && cd rakudo
perl Configure.pl --backend=moar --prefix ~/dev-rakudo-install && make -j 4 && make install

Обратите внимание на параметры: --prefix — показывает, куда будут скопированы исполняемые файлы после команды make install, --backend=moar указывает на используемую виртуальную машину, а -j 4 просит распараллеливать работу на несколько потоков (вдруг ускорит). Теперь у нас есть собранный компилятор Rakudo ~/dev-rakudo-install/bin/raku. Так же нам понадобится официальный сборник тестов для компилятора. Их нужно положить в папку с его кодом:

cd ~/dev-rakudo/rakudo && git clone https://github.com/Raku/roast.git t/spec

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

Здесь и дальше я буду работать в папке ~/dev-rakudo/rakudo, если не указано иное.

> make spectest
[...]
Test Summary Report
-------------------
t/spec/S32-str/utf8-c8.t    (Wstat: 65280 Tests: 54 Failed: 0)
  Non-zero exit status: 255
  Parse errors: Bad plan.  You planned 66 tests but ran 54.
Files=1346, Tests=117144, 829 wallclock secs (27.70 usr  6.04 sys + 2638.79 cusr 210.98 csys = 2883.51 CPU)
Result: FAIL
make: *** [m-spectest5] Error 1

Прошло 117,144 теста в 1,346 файлах за 14 минут. Несколько тестов, относящихся к utf8 по какой-то причине не исполнились, всё остальное работает как надо. Мы готовы к работе!

Разбираемся в постановке задачи

В задаче написано, что какой-то метаоператор R что-то делает не так с colonpair. Открываю документацию и ищу по слову R — метаоператоров с таким именем в выпадающем списке нет. Пробую набрать metaop и вижу reverse metaoperator (R). Оказывается, если вам хочется написать операнды бинарной операции в обратном порядке, то можно использовать префикс R перед её символом:

say 3 R- 2 == -1; # Output: True

Colonpair это синтаксис для обозначения именованной пары. Выглядит он как имя, следующее перед двоеточием и предшествующее круглым скобкам со значением. Например :foo(42) это пара с именем foo и значением 42. Такой синтаксис часто используется, чтобы передать значение в именованный параметр функции при её вызове:

sub sub-with-named-parameter(:$foo) {
  say $foo;
}

sub-with-named-parameter(:foo(42)); # Output: 42

Если параметр функции будет не именованным, а позиционным, то при вызове его с именованной парой случится ошибка компиляции:

sub sub-without-named-parameter($foo) { # <- нет двоеточия
  say $foo;
}

sub-without-named-parameter(:foo(42)); # Unexpected named argument 'foo' passed

Если при вызове такой функции окружить аргумент скобками, то в позиционный параметр уйдёт вся пара целиком:

sub sub-without-named-parameter($foo) {
  say $foo;
}

sub-without-named-parameter((:foo(42))); # Output: foo => 42

В Raku можно написать функцию, перехватывающую все аргументы, которые в неё передали и проанализировать. Делается это с помощью вертикальной черты перед единственным параметром — Capture:

sub sub-with-capture(|foo) { # <- параметр Capture
  say foo;
}

sub-with-capture(:foo(42));     # Output: \(:foo(42))
sub-with-capture(42);           # Output: \(42)
sub-with-capture(:foo(3 Z- 2)); # Output: \(:foo((1,).Seq))
sub-with-capture(:foo(3 R- 2)); # Output: \(-1)

В предпоследней строке используется метаоператор Z — zip-оператор. Он воспринимает правую и левую часть как список, последовательно берёт из них по элементу и применяет операцию, в результате получая последовательность.

В последней строке используется как раз нужный нам метаоператор R. В этом случае в функцию передалась не пара, а константа. Можно было бы предположить, что это некая особенность работы метаоператоров, но пример с Z показывает, что это не так. Собственно, в этом и заключается баг — при передаче в функцию colonpair, использующую метаоператор R, пара превращается её значение.

Нужен новый тест

Чтобы убедиться в том, что будущие изменения исправят неверное поведение, нужно написать новый тест. В тестовых файлах несложно найти тест (S03-metaops/reverse.t) метаоператора R. Добавлю внизу следующий тест:

# https://github.com/rakudo/rakudo/issues/1632
{
  my $got;
  sub with-named(:$value) { $got = $value };
  lives-ok { with-named(:value(3 R- 2)) }, "call doesn't throw";
  is $got, -1, "named is good";
}

В тесте есть функция with-named c именованным параметром. Его значение сохраняется во временную переменную $got и в конце теста сравнивается с ожидаемым значением. Кроме того, проверяем, не падает ли вызов функции вообще. Запустить отдельный тест для только что собранного компилятора можно с помощью make:

> make t/spec/S03-metaops/reverse.t
[...]
ok 69 - [R~]=
not ok 70 - Colonpair exists
# Failed test 'Colonpair exists'
# at t/spec/S03-metaops/reverse.t line 191
# expected: '\(:foo(-1))'
#      got: '\(-1)'
# You planned 69 tests, but ran 70
# You failed 1 test of 70

Видно, что тест упал (как и ожидалось). Ещё есть отдельное замечание, что система ожидала 69 тестов, а получила 70. Это особенность тестовой системы, основанной на TAP — нужно поправить число, передаваемое в функцию plan вверху файла. Теперь тест падает, но на количество не ругается. Можно приступать к исправлениям.

Метод пристального взгляда

Сначала я доверился меткам на задачке — если это parsing, значит проблема где-то на стадии разбора исходного кода. Мои знания на данный момент следующие:

Код основного парсера находится в файле rakudo/src/Perl6/Grammar.nqp;
Этот парсер наследуется от базового парсера из файла nqp/src/HLL/Grammar.nqp;
Метаоператоры парсятся и работают похожим образом и можно методом пристального взгляда найти различия.

В коде основного парсера я нашёл упоминания метаоператоров:

token infix_prefix_meta_operator:sym<R> {
  <sym> <infixish('R')> {}
  <.can_meta($<infixish>, "reverse the args of")>
  <O=.revO($<infixish>)>
}

token infix_prefix_meta_operator:sym<Z> {
  <sym> <infixish('Z')> {}
  <.can_meta($<infixish>, "zip with")>
  <O(|%list_infix)>
}

Тут нужны некоторые знания по грамматикам в Raku. Из моих знаний выходило, что принципиальной разницы в парсинге этих двух метаоператоров нет. Через какое-то время, вдоволь накопавшись в исходных кодах парсера, я начал подозревать, что парсинг работает правильно. Мысль, что код
my $r = :foo(3 R- 2); say $r; # Output: foo => -1
работает корректно подсказывала — проблема возникает именно при вызове функции. Видимо, я зря доверился метке на задачке.

Компилятор нам поможет

Довольно запоздало я вспомнил, что должен был сделать с самого начала. У компилятора Rakudo есть отладочный ключ --target. Он принимает название стадии работы компилятора, результат которой нужно вывести на консоль и выйти. Пробую посмотреть на --target=parse (так как, только о нём и знаю):

Я использую rakumo-m из папки ~/dev-rakudo/rakudo, чтобы не ждать, пока нужные файлы скопируются в ~/dev-rakudo-install командой make install. Простые скрипты можно запускать так. Более сложные — придётся запускать из -install после make install.

> cat ~/test.raku
sub s(|c) { say c }
s(:foo(3 R- 2));
s(:foo(3 Z- 2));

> ./rakudo-m --target=parse ~/test.raku
[...]
- args: (:foo(3 R- 2))
  - semiarglist: :foo(3 R- 2)
    - arglist: 1 matches
      - EXPR: :foo(3 R- 2)
        - colonpair: :foo(3 R- 2)
          - identifier: foo
          - coloncircumfix: (3 R- 2)
            - circumfix: (3 R- 2)
              - semilist: 3 R- 2
                - statement: 1 matches
                  - EXPR: R- 2
[...]
- args: (:foo(3 Z- 2))
  - semiarglist: :foo(3 Z- 2)
    - arglist: 1 matches
      - EXPR: :foo(3 Z- 2)
        - colonpair: :foo(3 Z- 2)
          - identifier: foo
          - coloncircumfix: (3 Z- 2)
            - circumfix: (3 Z- 2)
              - semilist: 3 Z- 2
                - statement: 1 matches
                  - EXPR: Z- 2
[...]

Вывод: парсинг проходит одинаково и для R, и для Z.

Это был не парсинг

Всё, что распарсилось, передаётся в так называемые Actions для превращения литералов в синтаксическое дерево. В нашем случае Actions лежат в файлах rakudo/src/Perl6/Actions.nqp и nqp/src/HLL/Actions.nqp. Тут немного проще разобраться — всё-таки это код, а не грамматика.

В основных Actions я нашёл следующих код:

[...]
elsif $<infix_prefix_meta_operator> {
[...]
  if    $metasym eq 'R' { $helper := '&METAOP_REVERSE'; $t := nqp::flip($t) if $t; }
  elsif $metasym eq 'X' { $helper := '&METAOP_CROSS'; $t := nqp::uc($t); }
  elsif $metasym eq 'Z' { $helper := '&METAOP_ZIP'; $t := nqp::uc($t); }
  
  my $metapast := QAST::Op.new( :op<call>, :name($helper), WANTED($basepast,'infixish') );
  $metapast.push(QAST::Var.new(:name(baseop_reduce($base<OPER><O>.made)), :scope<lexical>))
    if $metasym eq 'X' || $metasym eq 'Z';
[...]

Тут говорится, что если в коде распарсился метаоператор R, Z или X, то нужно добавить в синтаксическое дерево вызов неких METAOP_ функций. В случае Z и X, у них будет ещё один аргумент — некая reduce функция. Все эти функции нашлись в rakudo/src/core.c/metaops.pm6:

sub METAOP_REVERSE(\op) is implementation-detail {
  -> |args { op.(|args.reverse) }
}

sub METAOP_ZIP(\op, &reduce) is implementation-detail {
 nqp::if(op.prec('thunky').starts-with('.'),
  -> +lol {
    my $arity = lol.elems;
    [...]
  },
  -> +lol {
    Seq.new(Rakudo::Iterator.ZipIterablesOp(lol,op))
  }
  )
}

Здесь:

\op это операция, перед которой стоит наш метаоператор, то есть -;
Trait implementation-detail просто указывает на то, что это не публичный код и является частью реализации компилятора;
У операции - нет характеристики thunky, значит функция &reduce не будет участвовать в вычислениях и результатом Z является Seq.new(...);
Результатом R является вызов операции - с аргументами в обратном порядке.

В этот момент я вспомнил, что есть ещё один --target, а именно — ast. Он покажет результат работы Actions:

> ./rakudo-m --target=ast ~/test.raku
[...]
- QAST::Op(call &s) <sunk> :statement_id<4> s(:foo(3 R- 2))
  - QAST::Op+{QAST::SpecialArg}(call :named<foo>) <wanted> :statement_id<5> :before_promotion<?> R-
    - QAST::Op(call &METAOP_REVERSE) <wanted> :is_pure<?>
      - QAST::Var(lexical &infix:< - >) <wanted>
    - QAST::Want <wanted> 3
      - QAST::WVal(Int)
      - Ii
      - QAST::IVal(3)  3
    - QAST::Want <wanted> 2
      - QAST::WVal(Int)
      - Ii
      - QAST::IVal(2)  2
[...]
- QAST::Op(call &s) <sunk> :statement_id<7> s(:foo(3 Z- 2))
  - QAST::Op+{QAST::SpecialArg}(:named<foo>) <wanted> :statement_id<8> :before_promotion<?> Z-
    - QAST::Op(call &METAOP_ZIP) <wanted> :is_pure<?>
      - QAST::Var(lexical &infix:< - >) <wanted>
      - QAST::Var(lexical &METAOP_REDUCE_LEFT)
    - QAST::Want <wanted> 3
      - QAST::WVal(Int)
      - Ii
      - QAST::IVal(3)  3
    - QAST::Want <wanted> 2
      - QAST::WVal(Int)
      - Ii
      - QAST::IVal(2)  2
[...]

Как и ожидалось. Всё почти одинаково, за исключением того, что вызываются разные METAOP_ функции. Как мы знаем из их кода, принципиально эти функции различаются типом возвращаемого значение — Int и Seq, соответственно. Известно, что Raku довольно чувствительный к контекстам, к объектам разных типов… Вдруг дело именно в возвращаемом значении, подумал я. Пробую изменить код следующим образом:

sub METAOP_REVERSE(\op) is implementation-detail {
  -> |args { Seq.new(op.(|args.reverse)) }
}

Компилирую, запускаю:

> make
[...]
Stage start      :   0.000
Stage parse      :  61.026
Stage syntaxcheck:   0.000
Stage ast        :   0.000
Stage optimize   :   7.076
Stage mast       :  14.120
Stage mbc        :   3.941
[...]
> ./rakudo-m ~/test.raku
\(-1)
\(:foo((1,).Seq))

Ничего не изменилось. Значит, дело не в возвращаемом значении… После некоторых раздумий я насторожился — почему результат опять получился -1, а не (-1,).Seq? Более того, судя по коду Seq вообще не имеет подходящего конструктора. Следующая попытка, в качестве бреда — делаю так, чтобы вызов результата METAOP_REVERSE просто падал:

sub METAOP_REVERSE(\op) is implementation-detail {
  -> |args { die }
}

Компилирую, запускаю:

> make
[...]
> ./rakudo-m ~/test.raku
\(-1)
\(:foo((1,).Seq))

Как так?! В синтаксическом дереве присутствует вызов METAOP_REVERSE, её код должен рухнуть, но вычисления всё равно происходят и получается -1.

Это были не Actions

Тут мой взгляд падает на лог сборки компилятора. Там как раз перечислены какие-то Stage. Наобум пробую --target=mast:

> ./rakudo-m --target=mast ~/test.raku
[...]
MAST::Frame name<s>, cuuid<1>
  Local types: 0<obj>, 1<obj>, 2<obj>, 3<obj>, 4<int>, 5<str>, 6<obj>, 7<obj>, 8<obj>,
  Lexical types: 0<obj>, 1<obj>, 2<obj>, 3<obj>, 4<obj>,
  Lexical names: 0<c>, 1<$¢>, 2<$!>, 3<$/>, 4<$*DISPATCHER>,
  Lexical map: $!<2>, c<0>, $*DISPATCHER<4>, $¢<1>, $/<3>,
  Outer: name<<unit>>, cuuid<2>
[...]

Какая-то нечитаемая матрица. Между ast и mast есть Stage optimize:

> ./rakudo-m --target=optimize ~/test.raku
[...]
- QAST::Op(callstatic &s) <sunk> :statement_id<4> s(:foo(3 R- 2))
  - QAST::Op(call &infix:< - >)  :METAOP_opt_result<?>
    - QAST::Want <wanted> 2
      - QAST::WVal(Int)
      - Ii
      - QAST::IVal(2)  2
    - QAST::Want <wanted> 3
      - QAST::WVal(Int)
      - Ii
      - QAST::IVal(3)  3
[...]
- QAST::Op(callstatic &s) <sunk> :statement_id<7> s(:foo(3 Z- 2))
  - QAST::Op+{QAST::SpecialArg}(call :named<foo>) <wanted> :statement_id<8> :before_promotion<?> Z-
    - QAST::Op(callstatic &METAOP_ZIP) <wanted> :is_pure<?>
      - QAST::Var(lexical &infix:< - >) <wanted>
      - QAST::Var(lexical &METAOP_REDUCE_LEFT)
    - QAST::Want <wanted> 3
      - QAST::WVal(Int)
      - Ii
      - QAST::IVal(3)  3
    - QAST::Want <wanted> 2
      - QAST::WVal(Int)
      - Ii
      - QAST::IVal(2)  2
[...]

Ха! Вот оно. После стадии оптимизации пропала строчка:
- QAST::Op+{QAST::SpecialArg}(call :named<foo>) <wanted> :statement_id<5> :before_promotion<?> R-и весь вызов METAOP_REVERSE заменился на обычную операцию -(&infix: < - >). Значит, проблема где-то в оптимизаторе.

Упоминания о &METAOP_REVERSE есть только в методе optimize_nameless_call, в которую приходит QAST::Op+{QAST::SpecialArg}(call :named<foo>). Видимо, именно эта операция ответственна за формирование именованной пары — имя (параметр named) у неё уже есть, ей нужно вычислить значение. Поверхностно осмотрев пути исполнения метода optimize_nameless_call, можно сделать вывод, что нас интересует самый последний блок:

[...]
  elsif self.op_eq_core($metaop, '&METAOP_REVERSE') {
    return NQPMu unless nqp::istype($metaop[0], QAST::Var)
      && nqp::elems($op) == 3;
    return QAST::Op.new(:op<call>, :name($metaop[0].name),
      $op[2], $op[1]).annotate_self: 'METAOP_opt_result', 1;
  }
[...]

Напомню, что до оптимизации дерево выглядело так:

[...]
- QAST::Op(call &s) <sunk> :statement_id<4> s(:foo(3 R- 2))
  - QAST::Op+{QAST::SpecialArg}(call :named<foo>) <wanted> :statement_id<5> :before_promotion<?> R-
    - QAST::Op(call &METAOP_REVERSE) <wanted> :is_pure<?>
      - QAST::Var(lexical &infix:< - >) <wanted>
    - QAST::Want <wanted> 3
    - QAST::Want <wanted> 2

А после оптимизации — так:

[...]
- QAST::Op(callstatic &s) <sunk> :statement_id<4> s(:foo(3 R- 2))
  - QAST::Op(call &infix:< - >)  :METAOP_opt_result<?>
    - QAST::Want <wanted> 2
    - QAST::Want <wanted> 3
[...]

То есть, optimize_nameless_call делает следующее:

Если у нашей операции QAST::Op+{QAST::SpecialArg} не три аргумента, а у вызова METAOP_REVERSE — первый не нужного типа, то возвращаем пусто. Это не наш случай;
Иначе, вместо нашей операции QAST::Op+{QAST::SpecialArg} возвращаем новую, которая вызовет &infix:< - > аргументами в обратном порядке. То есть, упаковка результата в пару исчезла.

Немного поигравшись с тем, как это можно поправить и почитав реализации QAST::SpecialArg и QAST::Node, я пришёл к следующему коду:

[...]
  elsif self.op_eq_core($metaop, '&METAOP_REVERSE') {
    return NQPMu unless nqp::istype($metaop[0], QAST::Var)
      && nqp::elems($op) == 3;
    my $opt_result := QAST::Op.new(:op<call>, :name($metaop[0].name),
      $op[2], $op[1]).annotate_self: 'METAOP_opt_result', 1;
    if $op.named { $opt_result.named($op.named) } # добавить параметр named 
    if $op.flat { $opt_result.flat($op.flat) }    # добавить параметр flat
    return $opt_result;
  }
[...]

И дереву:

[...]
- QAST::Op(callstatic &s) <sunk> :statement_id<4> s(:foo(3 R- 2))
  - QAST::Op+{QAST::SpecialArg}(call &infix:< - > :named<foo>)  :METAOP_opt_result<?>
    - QAST::Want <wanted> 2
    - QAST::Want <wanted> 3
[...]

Параметр named вернулся на место. Тест тоже начал проходить:

> make t/spec/S03-metaops/reverse.t
[...]
All tests successful.
Files=1, Tests=70,  3 wallclock secs ( 0.03 usr  0.01 sys +  3.61 cusr  0.17 csys =  3.82 CPU)
Result: PASS

На этом можно было бы остановиться, но это же код оптимизатора компилятора, а в итоге его работы получился вызов метода - с двумя целочисленными аргументами. Как-то это неоптимально, на мой взгляд. Если изменить возвращаемое выражение на return self.visit_op: $opt_result;, чтобы вызвать оптимизатор на получившейся неоптимальной операции, то итоговое дерево будет выглядеть так:

[...]
- QAST::Op(callstatic &s) <sunk> :statement_id<4> s(:foo(3 R- 2))
  - QAST::Want+{QAST::SpecialArg}(:named<foo>)
    - QAST::WVal+{QAST::SpecialArg}(Int :named<foo>)
    - QAST::IVal(-1)
[...]

Теперь всё оптимально.

Делимся результатами

Мы на финишной прямой. Теперь дело за малым — поделиться наработками:

ВАЖНО: Прогнать все тесты make spectest и убедиться, что ничего нового не падает;
Сделать fork репозиториев с компилятором Rakudo и тестами на GitHub;
Добавить fork-репозитории как новые git remote:
cd ~/dev-rakudo/rakudo && git remote add fork <url-of-your-rakudo-fork> cd ~/dev-rakudo/rakudo/t/spec && git remote add fork <url-of-your-roast-fork>
ВАЖНО: Убедиться, что в обоих репозиториях правильно выставлены user.name и user.email в git;
Сделать коммиты в оба репозитория с подробным описание зачем и какие были сделаны изменения, добавить ссылки на оригинальную задачку трекере;
Запушить коммиты:
cd ~/dev-rakudo/rakudo && git push fork cd ~/dev-rakudo/rakudo/t/spec && git push fork
Сделать pull request в оба репозитория. В описаниях к ним лучше добавить перекрёстные ссылки друг на друга и на оригинальную задачку.

Заключение

Контрибутить в открытое ПО это:

весело и интересно;
даёт чувство, что ты делаешь что-то полезное, и это действительно так;
позволяет познакомиться с новыми интересными и профессиональными людьми (на любые вопросы относительно Raku вам ответят в IRC канале #raku;
замечательный опыт решения нестандартных задач без стресса в виде дедлайна.

Выбирайте класс героя, который вам сейчас более близок и вперёд навстречу новым квестам!

English version

#rakulang

#удачныйракурс

#opensource

#mmorpg

Когда полезны строковые веса | When string weights are useful

2021-11-26T19:27:49.905Z

Часто бывают случаи, когда нам нужно задать порядок на множестве объектов, у которых нет имманентного им приоритета. Например, список покупок — у абстрактного молока нет какой-то характеристики, по которой мы можем судить, что оно менее приоритетно хлеба. В таком случае объекты наделяются приоритетом снаружи, то есть, он условный. Обычно, программисты назначают тривиальный целочисленный приоритет: молоко — 1, хлеб — 2 и так далее.

Не стоит путать приоритет (вес) объекта с его идентификатором, который может быть инкрементальным целочисленным или, например, случайным UUID.

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

Ситуация стандартная, поведение тоже — переназначаем новые приоритеты: молоко-1, колбаса — 2, хлеб — 3. Такое переназначение может быть достаточно трудоёмким.

Часто встречаются предусмотрительные программисты, которые ожидая новых элементов, назначают приоритеты с запасом: молоко — 1, колбаса- 5, хлеб — 10. Это решение не очень элегантное, и запаса может не всегда хватить.

Другое стандартное поведение — ввести рациональные приоритеты: молоко — 1, колбаса — 1.5, хлеб — 2. Плюс такого подхода в том, что между двумя любыми элементами можно вставить сколько угодно новых. Минусы тоже есть — если заранее не подумать о рациональных приоритетах, то придётся менять тип данных столбца в базе. Ещё один плохой момент — нецелое число представляется в компьютере с округлением, что может привести к неточным расчётам.

Кстати, почему между любыми двумя рациональными числами можно вставить ещё одно? Потому что, дробная часть числа сравнивается не в числовом порядке (101>11), а в лексикографическом (0.101<0.11). Таким образом, если перейти от чисел к строкам, которые сравниваются лексикографически, то можно избавиться от проблем с возможным округлением.

Слово А меньше B в лексикографическом смысле, если либо А целиком является префиксом В, либо первый слева неравный символ у А меньше, чем у В.

Вторая часть определения даёт нам возможность сделать так, что между любыми двумя нашими словами можно было вставить третье. Для этого, последний символ любого слова должен быть таким, чтобы в алфавите присутствовали значения и больше, и меньше его. Рассмотрим небольшой алфавит из трёх элементов: =, < и >. В таком алфавите = как раз сгодится на роль последнего символа любого слова.

Представим, что у нас есть три объекта. Дадим им приоритеты:

Здесь, первая буква добавлена и для наглядности, и для практического удобства — например, это три разные категории товаров: мясное, мучное и молочное. Теперь начинаем добавлять новые объекты: менее приоритетная, чем хлеб булка — b<= (уменьшили последний символ, он получился крайний в алфавите, следовательно, добавили равно, чтобы не нарушать правило составления слов). Далее, пирожок между булкой и хлебом: берём хлеб, вычисляем приоритет меньший, получаем b<=, но такой уже присвоен булке, тогда вычисляем приоритет больше нее — b<>=. То есть алгоритм следующий: нужно вычислить приоритет больше, чем исходный — увеличиваем последний символ и добавляем средний символ алфавита, если увеличеный был крайним. Если полученный приоритет уже существует, то вычисляем приоритет меньший этого и так далее. Алгоритм для вычисления приоритета меньшего исходного аналогичен. Получаем такую картину:

Минусы этого подхода очевидны — чуть больше памяти на хранение и времени на сравнение. Минусы эти исключительно аппаратного рода, но есть мнение, что преждевременная оптимизация это корень всех зол, а удобство разработчика — благо.

На языке Raku такую генерацию можно написать следующим образом:

Объявляется функция next с тремя аргументами: изначальным словом $w и сетом уже имеющихся $set типа Set и параметром-ключом $prev, который используется, чтобы генерировать не следующее значение, а предыдущее (см. строку 12). Самые интересные строки это 4 и 5. Тут используется оператор замены s///. Берется изначальная $w, в ней ищется подстрока, которая удовлетворяет регулярному выражению между первыми косыми чертами (.$ — один символ перед концом текста) и заменяется за строку, между вторыми косыми чертами (вместо неё мы используем вычислимый блок, в котором берем нужную замену из массива). Стоит заменить, что оператор меняет исходную строку $w, вместо возвращения новой. Это позволяет использовать переменную $w в условии цикла в строке 5 (проверка, присутствует ли уже новое слово). Строки с 9 по 12 иллюстрируют использование функции.

English version

#rakulang

#удачныйракурс

#алгоритмы

#сортировка