Ещё одна статья про макросы. Часть 119.09.2024 14:15

Про макросы в Dart написали уже кучу статей, в этой — минимум теории и максимум практики и рассуждений. Вместе с Серёжей, Flutter Developer Surf, мы пройдём путём разработчика, который только начал изучать макросы, и будем:

• придумывать способы упростить свою жизнь с помощью макросов;

• формировать гипотезы (описывать то, что хотим получить);

• писать код и проверять гипотезы;

• радоваться результатам или разбираться, что пошло не так.

Знакомство с макросами

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

Здесь же мы слегка пробежимся по основным моментам, которые нам понадобятся дальше.

Действующие лица

Макрос:

• непосредственно то, что пишет разработчик;

• класс,   с точки зрения Dart;

• должен иметь константный конструктор (как и любой класс, который можно использовать в качестве аннотации);

• имеет доступ к информации о цели;

• генерирует код на основании этой информации.

Цель:

• то, к чему применяется макрос;

• может быть классом, методом, полем, top-level переменной, top-level функцией, библиотекой, конструктором, миксином, расширением, перечислением, полем перечисления, type alias’ом;

• может быть целью нескольких макросов сразу.

Сгенерированный код:

• появляется в режиме редактирования кода по мере изменения кода макроса/цели;

• readonly;

• форматирование кода — прерогатива разработчика, поэтому обычно на него без слёз не взглянешь.

Устройство макроса

Итак, макрос — это класс. Помимо этого:

• этот класс должен иметь ключевое слово macro в объявлении;

• реализовывать один (или несколько) из интерфейсов макросов. Каждый из интерфейсов определяет, к какой цели и в какой фазе макрос будет применён.

Фазы макросов

Фаза определения типов

• выполняется первой;

• только в этой фазе доступно объявление новых типов (классов, typedef, перечислений и других);

• позволяет добавлять интерфейсы и расширения классов к цели (если цель — это  класс);

• практически не имеет доступа к уже имеющимся типам;

• По сути, на этом всё.

Фаза объявления

• выполняется после фазы типов;

• в этой фазе можно объявлять новые поля, методы (но не классы и прочие типы);

• имеет доступ к уже объявленным типам — если они указаны явно;

• самая полезная и свободная фаза — можно писать практически любой код — как в класс, так и в файл.

Фаза определения

• выполняется последней;

• в этой фазе можно дополнять (augment) уже объявленные поля, методы, конструкторы;

• можно узнать типы полей, методов и другое (даже если они не указаны явно).

Как выбрать интерфейс макроса?

1. Выбираем цель.

2. Определяем, что мы хотим сделать с этой целью — то есть, выбираем фазу.

3. Путём несложной комбинации получаем название интерфейса (за исключением части Macro в конце).

4. 

5. Список доступных интерфейсов можно найти в репозитории с пакетом macros (пока он находится тут).

Таблица интерфейсов

Важно!

Рубрика «Эксперименты»

Да начнётся практика! Но сперва определим то, как она будет проходить.

Каждый пункт этого раздела будет основываться на ответах на следующие вопросы:

• зачем — обоснование полезности;

• как это должно выглядеть — ожидаемый результат в виде кода;

• как это реализовать — реализация);

• работает ли это? Если нет, то почему — разбор особенностей и ограничений.

Авто-конструктор

Зачем?

Будем честны, даже с помощью IDE создание конструктора класса с большим количеством полей — это не лучший вариант времяпрепровождения. Да и довольно утомительно бывает дополнять уже существующий конструктор новыми полями. Кроме того, конструктор для класса с большим количеством полей может занимать много строк кода, что не всегда положительно сказывается на читаемости.

Как это должно выглядеть?

Важно

Поля класса могут инициализироваться:

• позиционными параметрами конструктора;

• именованными параметрами конструктора;

• константными значениями по умолчанию;

• обязательными;

• необязательными;

• не в конструкторе.

Надо предусмотреть все эти случаи. Для этого используем аннотирование полей класса:

@AutoConstructor()
class SomeComplicatedClass {
  final int a;

  @NamedParam()
  final String b;

  @NamedParam(defaultValue: 3.14)
  final double c;

  @NamedParam(isRequired: false)
  final bool? d;

  @NamedParam(isRequired: true)
  final bool? e;

  final List f;
}

augment class SomeComplicatedClass {
  SomeComplicatedClass(this.a, this.f, {required this.b, this.c = 3.14, this.d, required this.e});
}

Как это реализовать?

Начнём с самого простого — в отдельном файле создадим класс NamedParam для аннотирования полей класса:

class NamedParam {
  final bool isRequired;
  final Object? defaultValue;
  const NamedParam({this.defaultValue, this.isRequired = true});
}

Теперь создадим макрос, который сделает всю работу за нас. Заодно порассуждаем, какая фаза макроса нам подходит:

• мы не собираемся определять новые типы, поэтому фаза типов точно не подходит;

• фаза объявления позволяет писать код внутри класса, а также оперировать полями класса, что нам и нужно;

• фаза определения позволяет дополнять конструктор класса, но не даёт возможность писать конструктор с нуля (то есть, конструктор уже должен присутствовать в классе) — не наш вариант.

Мы выбираем фазу объявления. Создаём макрос AutoConstructor, получаем список полей и начинаем складывать код конструктора и параметры:

import 'dart:async';

import 'package:macros/macros.dart';

macro class AutoConstructor implements ClassDeclarationsMacro {
  @override
  FutureOr buildDeclarationsForClass(ClassDeclaration clazz, MemberDeclarationBuilder builder) async {
    final fields = await builder.fieldsOf(clazz);

    /// Сюда мы будем собирать код.
    /// Начнём с объявления конструктора.
    /// Например:
    /// ClassName(
    ///
    final code =