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

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

В этой главе мы рассмотрим следующие темы:

• Что такое аннотации?

• Хранение данных в аннотациях.

• Чтение аннотаций

К концу этой главы вы должны иметь четкое представление о том, что такое аннотации и как их использовать.

Технические требования

Требования к этой главе следующие:

• Рабочая установка Crystal.

Инструкции по настройке Crystal можно найти в Главе 1 «Введение в Crystal».

Все примеры кода, использованные в этой главе, можно найти в папке Chapter 11 на GitHub: https://github.com/PacktPublishing/Crystal-Programming/tree/main/Chapter11.

Что такое аннотации?

Проще говоря, аннотация — это способ прикрепить метаданные к определенным функциям кода, к которым впоследствии можно получить доступ во время компиляции внутри макроса. Crystal поставляется в комплекте с некоторыми встроенными аннотациями, с которыми вы, возможно, уже работали, например @[JSON::Field] или аннотацией @[Link], которая была рассмотрена в Главе 7, «Взаимодействие C». Хотя обе эти аннотации включены по умолчанию, они различаются по своему поведению. Например, аннотация JSON::Field существует в стандартной библиотеке Crystal и реализована/используется таким образом, что вы можете воспроизвести ее в своем собственном коде с помощью собственной аннотации. С другой стороны, аннотация Link имеет особые отношения с компилятором Crystal, и часть ее поведения не может быть воспроизведена в пользовательском коде.

Пользовательские аннотации можно определить с помощью ключевого слова annotation:

annotation MyAnnotation; end

Вот и все. Затем аннотацию можно было применить к различным элементам, включая следующие:

• Методы экземпляра и класса.

• Переменные экземпляра

• Классы, структуры, перечисления и модули.

Аннотацию можно применять к различным объектам, помещая имя аннотации в квадратные скобки синтаксиса @[], как в следующем примере:

@[MyAnnotation]

def foo

  "foo"

end

@[MyAnnotation]

class Klass

end

@[MyAnnotation]

module MyModule

end

К одному и тому же элементу также можно применить несколько аннотаций:

annotation Ann1; end

annotation Ann2; end

@[Ann1]

@[Ann2]

@[Ann2]

def foo

end

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

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

Примером этого может быть, скажем, у вас есть модель ORM, которую вы хотите проверить. Например, если одна из установленных вами библиотек использует собственный макрос, такой как column id : Int64, это может сделать другие библиотеки нефункциональными, поскольку аннотация может быть неправильно применена к переменной экземпляра или методу. Однако если все библиотеки используют аннотации, то все они работают со стандартными переменными экземпляра Crystal, поэтому у библиотек нет возможности конфликтовать, и это делает все более естественным.

Кроме того, аннотации более ориентированы на будущее и более гибки по сравнению с определениями макросов для этого конкретного варианта использования. Далее давайте поговорим о том, как хранить данные в аннотации.

Хранение данных в аннотациях

Подобно методу, аннотация поддерживает как позиционные, так и именованные аргументы:

annotation MyAnnotation

end

@[MyAnnotation(name: "value", id: 123)]

def foo; end

@[MyAnnotation("foo", 123, false)]

def bar; end

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

annotation MyAnnotation; end

@[MyAnnotation(1, enabled: false)]

@[MyAnnotation(2)]

def foo

end

Поскольку значения в каждой аннотации могут быть разными, связанная библиотека может создать несколько методов или переменных, например, на основе каждой аннотации и данных в ней. Однако эти данные бесполезны, если вы не можете получить к ним доступ! Давайте посмотрим, как это сделать дальше.

Чтение аннотаций

В Crystal вы обычно вызываете метод объекта, чтобы получить доступ к некоторым данным, хранящимся внутри. Аннотации ничем не отличаются. Тип Annotation предоставляет три метода, которые можно использовать для доступа к данным, определенным в аннотации, различными способами. Однако прежде чем вы сможете получить доступ к данным в аннотации, вам необходимо получить ссылку на экземпляр Annotation. Это можно сделать, передав тип Annotation методу #annotation, определенному для типов, поддерживающих аннотации, включая TypeNode, Def и MetaVar. Например, мы можем использовать этот метод для печати аннотации, примененной к определенному классу или методу, если таковой имеется:

annotation MyAnnotation; end

@[MyAnnotation]

class MyClass

  def foo

    {{pp @type.annotation MyAnnotation}}

    {{pp @def.annotation MyAnnotation}}

  end

end

MyClass.new.foo

Метод #annotation вернет NilLiteral, если аннотация указанного типа не применена. Теперь, когда у нас есть доступ к примененной аннотации, мы готовы начать чтение из нее данных!

Первый, наиболее простой способ — использование метода #[], который может показаться знакомым, поскольку он также используется, среди прочего, как часть типов Array и Hash. Этот метод имеет две формы: первая принимает NumberLiteral и возвращает позиционное значение по предоставленному индексу. Другая форма принимает StringLiteral, SymbolLiteral или MacroId и возвращает значение с предоставленным ключом. Оба этих метода вернут NilLiteral, если по указанному индексу или указанному ключу не существует значения.

Два других метода, #args и #named_args, не возвращают конкретное значение, а вместо этого возвращают коллекцию всех позиционных или именованных аргументов в аннотации в виде TupleLiteral и NamedTupleLiteral соответственно.

Прежде всего, давайте посмотрим, как мы можем работать с