Crystal Programming. Введение на основе проекта в создание эффективных, безопасных и читаемых веб-приложений и приложений CLI

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

property

class Example

 property age : Int32

 def initialize(@age : Int32); end

end

Предыдущий код эквивалентен следующему:

class Example

 @age : Int32

 def initialize(@age : Int32); end

 def age : Int32

  @age

 end

 def age=(@age : Int32)

 end

end

Как мы упоминали ранее, макросы принимают узлы AST во время компиляции и выводят код Crystal, который добавляется в программу, как если бы он был введен вручную. По этой причине

property age: Int32

• Переменные среды.

• Константы

• Жестко запрограммированные значения.

• Жестко закодированные значения, созданные с помощью другого макроса.

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

macro print_value(value)

 {{pp value}}

 pp {{value}}

end

name = "George"

print_value name

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

name

"George"

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

Var

{{pp value.class_name}}

"Var”

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

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

macro def_method(name)

 def {{name.id}}

  puts "Hi"

 end

end

 def_method foo

foo

В этом примере мы определили макрос с именем

def_method

• Аргументы макроса не могут иметь ограничений типа.

• Макросы не могут иметь ограничений по типу возвращаемого значения.

• Аргументы макроса не существуют во время выполнения, поэтому на них можно ссылаться только в синтаксисе макроса.

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

Синтаксис макроса состоит из двух форм:

{{ ... }} и {% ... %}

foo

Hi

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

macro def_methods(*numbers, only_odd = false)

 {% for num, idx in numbers %}

  {% if !only_odd || (num % 2)	!= 0 %}

   # Returns the number at index {{idx}}.

   def {{"number_#{idx}".id}}

    {{num}}

   end

   {% end %}

 {% end %}

 {{debug}}

end

def_methods 1, 3, 6, only_odd: true

pp number_0

pp number_1

В этом примере происходит нечто большее, чем мы видим! Давайте разберемся. Сначала мы определили макрос под названием

def_methods

false

Цель использования аргументов

splat

#each

for item, index in collection

Hash/NamedTuple

for i in (0.. 10)

hash_or_named_tuple

Основная причина, по которой

#each

#each

{% begin %}

 {% hash = {"foo" => "bar", "biz" => "baz"} %}

 {% for key, value in hash %}

  puts "#{{{key}}}=#{{{value}}}"

 {% end %}

{% end %}

{% begin %}

 {% arr =	[1, 2, 3]	%}

 {% hash = {} of Nil => Nil %}

 {% arr.each {	|v| hash[v] = v * 2 } %}

 puts({{hash}})

{% end %}

В этом примере мы перебирали ключи и значения хеша, генерируя вызов метода

puts

ArrayLiteral#each

for in

#each

#each

for in

#each

Следующее, что делает наш макрос

def_methods

if

if/unless

Далее обратите внимание, что у этого метода есть комментарий, включающий

{{idx}}

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

#id

#id

MacroId

#id

“foo”

:foo

foo

foo

В самом конце определения макроса вы могли заметить строку

{{debug}}

# Returns the number at index 0.

def number_0

1

end

# Returns the number at index 1.

def number_1

3

end

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

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

macro def_macros(*numbers)

 {% for num, idx in numbers %}

  macro def_num_{{idx}}_methods(n)

   def num_\{{n}}

    \{{n}}

   end

   def num_\{{n}}_index

    {{idx}}

   end

  end

  def_num_{{idx}}_methods({{num}})

 {% end %}

end

def_macros 2, 1

pp num_1_index # => 1

pp num_2_index # => 0

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

\{{

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

macro def_num_{{idx}}_methods(n)

 {% verbatim do %}

  def num_{{n}}

   {{n}}

  end

  def num_{{n}}_index

   {{idx}}

  end

 {% end %}

end

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

verbatim

idx

Чтобы иметь возможность доступа к этой переменной, нам нужно определить другую экранированную макропеременную за пределами блока

verbatim

idx

\{% idx = {{idx}} %}

{% verbatim do %}

{% idx = 1 %}

Поскольку макросы расширяются до кода Crystal, код, сгенерированный макросом, может создать конфликт с кодом, определенным в расширении макроса. Наиболее распространенной проблемой является переопределение локальных переменных. Решением этой проблемы является использование новых переменных как средства создания уникальных переменных.

Свежие переменные

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

macro update_x

 x = 1

end

x = 0

update_x

puts x

Макрос

update_x

x = 1

x

1

macro dont_update_x

 %x = 1

 puts %x

end

x = 0

dont_update_x

puts x

В отличие от предыдущего примера, здесь будет выведено значение

1

0

x

%

macro fresh_vars_sample(*names)

 {% for name, index in names %}

  %name{index} = {{index}}

 {% end %}

 {{debug}}

end

fresh_vars_sample a, b, c

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

__temp_24 = 0

__temp_25 = 1

__temp_26 = 2

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

Макросы определения, не являющиеся макросами

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

{% if flag? :release %}

 puts "Release mode!"

{% else %}

 puts "Non-release mode!"

{% end %}

Метод

flag?

{% if flag?(:linux) && flag?(:x86_64) %}

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

--define

-D

flag? :foo

crystal run -Dfoo main.cr

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

BUILD_SHA_HASH

COMMIT_SHA = {{ env("BUILD_SHA_HASH") ||	"" }}

pp COMMIT_SHA

При запуске этого кода обычно печатается пустая строка, а при установке связанной переменной

env

env

Одним из ограничений макросов является то, что сгенерированный из макроса код также должен быть действительным кодом Crystal, как показано здесь:

def {{"foo".id}}

 "foo"

end

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

{% begin %}/{% end %}

{% begin %}

 def {{"foo".id}}

  "foo"

 end

{% end %}

На этом этапе вы должны иметь четкое начальное представление о том, что такое макросы, как их определять и для каких случаев использования они предназначены, что позволит вам сохранить ваш код СУХИМ (DRY). Далее мы рассмотрим API макросов, чтобы можно было создавать более сложные макросы.

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

Number

String

Bool

NumberLiteral

StringLiteral

BoolLiteral

Все типы макросов находятся в пространстве имен

Crystal::Macros

•

 Def

•

 TypeNode

•

 MetaVar

•

 Arg

•

Annotation

Crystal предоставляет удобный способ получить экземпляр первых двух типов в виде макропеременных

@def

@type

@def

Def

@type

TypeNode

"Метод hello внутри Foo"

class Foo

 def hello

  {{"The #{@def.name} method within #{@type.name}"}}

 end

end

pp Foo.new.hello

Другой, более продвинутый способ получения

TypeNode

parse_type

StringLiteral

Как мы упоминали ранее, API макросов позволяет нам вызывать фиксированное подмножество обычных методов API для литеральных типов. Другими словами, это позволяет нам вызывать

ArrayLiteral#select

ArrayLiteral#each_repeated_permutation

StringLiteral#gsub

StringLiteral#scan

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

• Тип возвращаемого значения, его видимость или аргументы метода.

• Тип/значение по умолчанию аргумента метода.

• Какие аргументы объединения/обобщения имеет тип, если таковые имеются.

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

class Foo

 def hello(one : Int32, two, there, four : Bool, five :

  String?)

  {% begin %}

   {{"#{@def.name} has #{@def.args.size} arguments"}}

   {% typed_arguments = @def.args.select(&.restriction) %}

   {{"with #{typed_arguments.size} typed

    arguments"}}

   {{"and is a #{@def.visibility.id} method"}}

  {% end %}

 end

end

Foo.new.hello 1, 2, 3, false, nil

Эта программа выведет следующее:

"hello has 5 arguments"

"with 3 typed arguments"

"and is a public method"

Первая строка выводит имя метода и количество его аргументов через

ArrayLiteral#size

Def#args

ArrayLiteral(Arg)

ArrayLiteral#select

Arg#restriction

TypeNode

Nop

Def#visibility

#id

Существует еще одна специальная макропеременная

@top_level

TypeNode

@type

A_CONSTANT = 0

module Foo; end

{% if @top_level.has_constant?("A_CONSTANT") && @top_level

 .has_constant?("Foo") %}

 puts "this is printed"

{% else %}

 puts "this is not printed"

{% end %}

В этом примере мы использовали

TypeNode#has_constant?

BoolLiteral

TypeNode

StringLiteral

SymbolLiteral

MacroId

#id

Понимание API макросов имеет решающее значение для написания макросов, использующих информацию, полученную из типа и/или метода. Я настоятельно рекомендую прочитать документацию по API для некоторых типов макросов, о которых мы говорили в этом разделе, чтобы полностью понять, какие методы доступны.

Прежде чем мы перейдем к следующему разделу, давайте применим все, что мы узнали, для воссоздания макроса

property

Воссоздание макроса property

Обычно макрос

property

TypeDeclaration

Макрос

property

macro def_getter_setter(decl)

 @{{decl}}

 def {{decl.var}} : {{decl.type}}

  @{{decl.var}}

 end

 def {{decl.var}}=(@{{decl.var}} : {{decl.type}})

 end

end

Мы можем определить переменную экземпляра, используя

@{{decl}}

@{{decl.var}} : {{decl. type}}

if

Остальная часть нашего макроса

def_getter_setter

class Foo

 def_getter_setter name : String?

 def getter setter number : Int32 = 123

 property float : Float64 = 3.14

end

obj = Foo.new

pp obj.name

obj.name = "Bob"

pp obj.name

pp obj.number

pp obj.float

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

nil

"Bob"

123

3.14

И вот оно! Успешная повторная реализация наиболее распространенной формы макроса

property

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

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

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

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

1. По всем или прямым подклассам родительского типа.

2. Типы, включающие определенный модуль.

3. Типы, к которым применяются определенные аннотации*

4. Некоторая комбинация предыдущих трех способов.

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

Самый распространенный способ перебора типов — через подклассы родительского типа. Это могут быть либо все подклассы этого типа, либо только прямые подклассы. Давайте посмотрим, как бы вы это сделали.

Итерация подклассов типа

Прежде чем мы перейдем к более сложным примерам, давайте сосредоточимся на более простом варианте использования перебора подклассов типа с использованием следующего дерева наследования:

abstract class Vehicle; end

abstract class Car < Vehicle; end

class SUV < Vehicle; end

class Sedan < Car; end

class Van < Car; end

Первое, что нам нужно, это

TypeNode

Vehicle

Car

Если вы помните первую главу этой части, мы смогли получить

TypeNode

@type

Vehicle

Когда у нас есть

TypeNode

TypeNode#subclasses

TypeNode#all_subclasses

{{pp Vehicle.subclasses}}

{{pp Vehicle.all_subclasses}}

В результате компиляции программы на консоль будут выведены две строки: первая —

[Car, SUV]

[Car, Sedan, Van, SUV]

Car

Van

Sedan

Vehicle

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

Car

ArrayLiteral(TypeNode)

ArrayLiteral#reject

{% for type in Vehicle.all_subclasses.reject &.abstract? %}

  pp {{type}}.new

{% end %}

Запуск этого в конечном итоге приведет к печати нового экземпляра типов

Sedan

Van

SUV

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

annotation MyAnnotation; end

abstract class Parent; end

@[MyAnnotation(id: 456)]

class Child < Parent; end

@[MyAnnotation]

class Foo; end

@[MyAnnotation(id: 123)]

class Bar; end

class Baz; end

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

id

id

ID

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

Итерация типов с определенной аннотацией

В Crystal

Object

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

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

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

{% for type in Object.all_subclasses.select {|t| (ann =

 t.annotation(MyAnnotation)) && (ann[:id] == nil || ann[:id]

  % 2 == 0) } %}

 {{pp type}}

{% end %}

В этом случае мы используем

ArrayLiteral#select

true

id

id

Child

Foo

Итерационные типы, включающие определенный модуль

Третий способ, которым мы можем перебирать типы, - это запросить те типы, которые включают определенный модуль. Это может быть достигнуто с помощью метода

TypeNode#includers

TypeNode

module SomeInterface; end

class Bar

  include SomeInterface

end

class Foo; end

class Baz

  include SomeInterface

end

class Biz < Baz; end

{{pp SomeInterface.includers}}

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

[Bar, Baz]

При использовании метода

#includers

#all_subclasses

#includers

#includers

ArrayLiteral(TypeNode)

Во всех этих примерах мы начали с базового родительского типа и прошли через все подклассы этого типа. Также возможно сделать обратное; начните с дочернего типа и перебирайте его предков. Например, давайте посмотрим на предков класса

Biz

{{pp Biz.ancestors}}

Это должно вывести следующее:

[Baz, SomeInterface, Reference, Object]

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

Object

#ancestors

ArrayLiteral(TypeNode)

Следующая особенность метапрограммирования, которую мы собираемся рассмотреть, — это перебор методов типа.

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

Если структура, представляющая данные аннотации, имеет обязательные параметры, которые, как ожидается, будут предоставлены через аннотацию, программа не будет компилироваться, если эти значения не будут предоставлены. Он также обрабатывает случай, когда параметры имеют значение по умолчанию. Кроме того, если в аннотации есть неожиданное поле или аргумент неправильного типа, она также не будет скомпилирована. Это значительно упрощает добавление / удаление свойств из структуры, поскольку все они не должны быть явно заданы в

StringLiteral

В настоящее время существует Crystal RFC, который предлагает сделать этот шаблон более встроенной функцией, сделав аннотацию и структуру одним и тем же. См. https://github.com/crystal-lang/crystal/issues/9802 для получения дополнительной информации.

Есть несколько способов фактически раскрыть структуры:

• Определите метод, который возвращает их массив.

• Определите метод, который возвращает хэш, который предоставляет их по имени переменной экземпляра.

• Определите метод, который принимает имя переменной экземпляра и возвращает его.

У каждого из этих подходов есть свои плюсы и минусы, но все они имеют что-то общее. В самом экземпляре/типе должна быть какая-то точка входа, которая предоставляет данные. Основная причина этого заключается в том, что переменные экземпляра можно повторять только в контексте метода.

Кроме того, существует два основных способа обработки самих структур. Один из вариантов — сделать метод методом экземпляра и включить значение каждой переменной экземпляра в структуру. У этого подхода есть несколько недостатков, например, его сложнее запомнить и он не очень хорошо обрабатывает обновления. Например, вы вызываете метод и получаете структуру для данной переменной экземпляра, но затем значение этой переменной экземпляра изменяется до того, как будет выполнена фактическая логика. Значение в структуре может представлять только значение на момент вызова метода.

Другой подход — сделать метод лениво инициализируемым запоминаемым методом класса. Этот подход идеален, потому что:

1. Он создает хэш/массив только для типов, которые используются вместо каждого типа/экземпляра.

2. Он кэширует структуры, поэтому их нужно создать только один раз.

3. Это имеет больше смысла, поскольку большая часть данных будет относиться к данному типу, а не к экземпляру этого типа.

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

1.

name

2.

type

3.

class

4.

priority

5.

id

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

Мы можем использовать макрос

record

abstract struct MetadataBase; end

record PropertyMetadata(ClassType, PropertyType, Propertyldx)

 < MetadataBase,

 name : String,

 id : Int32,

 priority : Int32 = 0 do

 def class_name : ClassType.class

  ClassType

 end

 def type : PropertyType.class

  PropertyType

 end

end

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

У каждой записи будет имя, и мы также добавили к ней два дополнительных свойства. Поскольку значение

priority

0

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

annotation Metadata; end

module Metadatable

 macro included

  class_property metadata : Hash(String, MetadataBase) do

   {% verbatim do %}

    {% begin %}

     {

      {% for ivar, idx in @type.instance_vars.select &.

       annotation Metadata %}

       {{ivar.name.stringify}} => (PropertyMetadata(

        {{@type}}, {{ivar.type.resolve}},{{idx}}

        ).new({{ivar.name.stringify}},

         {{ivar.annotation(Metadata).named_args

         .double_splat}}

       )),

      {% end %}

     } of String => MetadataBase

    {% end %}

   {% end %}

  end

 end

end

Мы также используем блочную версию макроса

class_getter

Фактическая логика макроса довольно проста и делает многое из того, что мы делали в предыдущем разделе. Однако в этом примере мы также передаем некоторые общие значения при создании экземпляра нашего экземпляра

PropertyMetadata

На этом этапе наша логика готова к испытанию. Создайте класс, включающий модуль и некоторые свойства, использующие аннотацию, например:

class MyClass

include Metadatable

 @[Metadata(id: 1)]

 property name : String = "Jim"

 @[Metadata(id: 2, priority: 7)]

 property created_at : Time = Time.utc

 property weight : Float32 = 56.789

end

pp MyClass.metadata["created_at"]

Если бы вы запустили эту программу, вы бы увидели, что она выводит экземпляр

PropertyMetadata

Доступ к значению

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

StaticArray

StaticArray(Int32, 3)

Int32

Как упоминалось ранее, наш тип

PropertyMetadata

Если вам интересно, нет, нет способа волшебным образом получить значение из воздуха только потому, что у нас есть индекс переменной экземпляра и

TypeNode

MyClass

PropertyMetadata

def value(obj : ClassType)

 {% begin %}

   obj.@{{ClassType.instance_vars[PropertyIdx].name.id}}

 {% end %}

end

def value(obj) i : NoReturn

  raise "BUG: Invoked default value method."

end

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

obj.@ivar_name

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

def value(obj : ClassType)

  obj.@name

end

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

Metadatable

Мы можем пойти дальше и опробовать это, добавив в нашу программу следующее и запустив ее:

my_class = MyClass.new

pp MyClass.metadata["name"].value my_class

Вы должны увидеть значение свойства name, напечатанное на вашем терминале, которое в данном случае будет

"Jim"

#value

typeof(name_value)

(String | Time)

Этот шаблон отлично подходит для реализации мощных внутренних API, но его следует использовать с осторожностью, не использовать в «горячем» пути приложения и даже не публиковать публично.

Если вы помните Главу 9 «Создание веб-приложения с помощью Athena», где вы применяли аннотации ограничений проверки, компонент Validator Athena реализован с использованием этого шаблона, хотя и с несколько большей сложностью.

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

Моделирование всего класса

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

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

self

TypeNode

Поскольку макросы имеют доступ к общей информации, даже в контексте метода мы можем заставить этот тип

ClassMetadata

TypeNode

Например, используя тот же тип

PropertyMetadata

annotation Metadata; end

annotation ClassConfig; end

class ClassMetadata(T)

 def initialize

  {{@type}}

  {% begin %}

   @property_metadata = {

    {% for ivar, idx in T.instance_vars.select &.

     annotation Metadata %}

     {{ivar.name.stringify}} => (

      PropertyMetadata({{@type}}, {{ivar.type.resolve}},

       {{idx}}).new({{ivar.name.stringify}},

        {{ivar.annotation(Metadata).named_args

         .double_splat}})

     ),

    {% end %}

   } of String => MetadataBase

   @name = {{(ann = T.annotation(ClassConfig)) ?

    ann[:name] : T.name.stringify}}

  {% end %}

 end

 getter property_metadata : Hash(String, MetadataBase)

 getter name : String

end

Модуль

Metadatatable

module Metadatable

 macro included

 class_getter metadata : ClassMetadata(self)

   { ClassMetadata(self).new }

 end

end

Большая часть логики такая же, как и в предыдущем примере, за исключением того, что вместо прямого возврата хеша метод

.metadata

ClassMetadata

@[ClassConfig(name: "MySpecialName")]

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

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

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

.exclude_type

В последних нескольких главах мы использовали различные макрометоды верхнего уровня, такие как

#env

#flag

#debug

#raise

Path

macro exclude_type(type)

 {% raise %(Expected argument to 'exclude_type' to be

  'Path', got '#{type.class_name.id}'.) unless type.is_a?

   Path %}

 {% EXCLUDED_TYPES << type.resolve %}

end

Теперь, если бы мы вызвали макрос с

"Time"

In mutable_constants.cr:43:1

43 | exclude_type "Time"

   ^-----------

Error: Expected argument to 'exclude_type' to be 'Path', got 'StringLiteral'.

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

Все типы макросов, с которыми мы работали, произошли от базового типа макроса

ASTNode

#id

#raise

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

type.raise

Ограничение универсальных типов

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

Array(T)

Hash(K, V)

abstract class Animal

end

class Cat < Animal

end

class Dog < Animal

end

class Food(T)

end

Food(Cat).new

Food(Dog).new

Food(Int32).new

В этом примере имеется общий тип еды, который должен принимать только подкласс

Animal

Food

Animal

Int32

Food

T

Animal

class Food(T)

 def self.new

  {% raise "Non animal '#{t}' cannot be fed." unless T <=

   Animal %}

 end

end

В этом новом коде попытка выполнить

Food(Int32).new

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