Трейт scala.reflect.macros.blackbox.Context

Сокращенная запись для создания выражения.

В отличие от стандартного фабричного метода для создания выражений, который требует scala.reflect.api.TreeCreator, данный метод принимает обычное дерево, но полученные выражения не могут быть перенесены в другие вселенные/зеркала (эта функциональность обычно не нужна для макросов, так как существует только одна вселенная во время компиляции и только одно зеркало во время компиляции).

Указывает, что аргумент c.typecheck должен быть проверен как шаблон.

Указывает, что аргумент c.typecheck должен быть проверен как терм. Это режим проверки по умолчанию в Scala 2.11 и единственный поддерживаемый режим в Scala 2.10.

Указывает, что аргумент c.typecheck должен быть проверен как тип.

Сокращенная запись для создания тега типа.

В отличие от стандартного фабричного метода для создания тегов типа, который требует scala.reflect.api.TypeCreator, данный метод принимает обычный тип, но полученные теги типа не могут быть перенесены в другие вселенные/зеркала (эта функциональность обычно не нужна для макросов, так как существует только одна вселенная во время компиляции и только одно зеркало во время компиляции).

Сокращенная запись для создания слабого тега типа.

В отличие от стандартного фабричного метода для создания тегов типа, который требует scala.reflect.api.TypeCreator, данный метод принимает обычный тип, но полученные теги типа не могут быть перенесены в другие вселенные/зеркала (эта функциональность обычно не нужна для макросов, так как существует только одна вселенная во время компиляции и только одно зеркало во время компиляции).

Прерывает текущую макрорасшифровку, оставив заметку о случившемся. Используйте enclosingPosition, если вы сомневаетесь, какую позицию передать в pos.

Возвращает текущий путь к классам.

Возвращает текущие настройки компилятора как список опций. Используйте scalac -help, scalac -X и scalac -Y, чтобы узнать о поддерживаемых опциях.

Отправляет сообщение, которое не должно быть помечено как предупреждение/ошибка, но также не должно требовать -verbose для отображения. Используйте enclosingPosition, если вы сомневаетесь, какую позицию передать в pos.

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

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

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

Пытается угадать позицию для окружающего применения. Но это просто, верно? Просто разыменовать pos macroApplication? Не совсем. Если мы находимся в синтетическом расширении макроса (без позиций), мы должны сделать все возможное, чтобы вывести позицию того, что спровоцировало это расширение. Удивительно, но довольно часто мы можем сделать это, просматривая стек enclosingMacros.

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

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

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

Известные проблемы: из-за https://github.com/scala/bug/issues/5748 деревья, которые оцениваются в первую очередь, должны пройти untypecheck. Переустановка символов и типов изменяет дерево на месте, поэтому стандартный подход заключается в duplicate дерева сначала.

scala> def impl(c: Context)(x: c.Expr[String]) = {
     | val x1 = c.Expr[String](c.untypecheck(x.tree.duplicate))
     | println(s"compile-time value is: ${c.eval(x1)}")
     | x
     | }
impl: (c: Context)(x: c.Expr[String])c.Expr[String]

scala> def test(x: String) = macro impl
test: (x: String)String

scala> test("x")
compile-time value is: x
res0: String = x

scala> test("x" + "y")
compile-time value is: xy
res1: String = xy

scala> val x = "x"
x: String = x

scala> test(x + "y")
compile-time value is: xy
res2: String = xy

scala> { val x = "x"; test(x + "y") }
error: exception during macro expansion:
scala.tools.reflect.ToolBoxError: reflective compilation failed

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

Создает более или менее уникальное имя, имеющее указанное имя в качестве префикса и имеющее тот же тип (имя термина или имя типа), что и данное имя. См. scala.reflect.macros.Names для получения дополнительной информации об уникальности таких имен.

Создает строку, представляющую более или менее уникальное имя, имеющее указанный префикс. См. scala.reflect.macros.Names для получения дополнительной информации об уникальности таких имен.

Создает строку, представляющую более или менее уникальное имя. См. scala.reflect.macros.Names для получения дополнительной информации об уникальности таких имен.

В сессии компиляции есть ошибки?

В сессии компиляции есть какие-либо предупреждения?

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

Если silent равно false, TypecheckException будет вызвано в случае ошибки вывода. Если silent равно true, проверка типов будет беззвучной и вернет EmptyTree в случае ошибки. Такие ошибки не исчезают и могут быть проверены, включив -Xlog-implicits. В отличие от typecheck, silent по умолчанию равно true.

Определяет неявное представление (implicit view) из предоставленного дерева tree типа from к типу to в контексте вызова макроса. Необязательный параметр pos задаёт позицию, которая будет ассоциирована с поиском неявного представления.

Если silent равно false, TypecheckException будет выброшено в случае ошибки вывода. Если silent равно true, проверка типов будет выполнена в бесшумном режиме, и будет возвращено значение EmptyTree в случае возникновения ошибки. Такие ошибки не исчезают и могут быть просмотрены, если включить -Xlog-implicits. В отличие от typecheck, значение silent по умолчанию равно true.

Выводит информационное сообщение, которое подавляется, если -verbose или force=true. Используйте enclosingPosition в случае сомнений, какую позицию передать в pos.

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

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

Также очень ценно для вывода осмысленных сообщений об ошибках для макросов, которые вызываются другими макросами над синтетическими (т.е. без позиций) деревьями. В таком случае просмотрите стек openMacros, и он, скорее всего, будет содержать как минимум один макрос с позицией в дереве макро-применения. См. enclosingPosition для реализации по умолчанию этой логики.

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

Разбирает строку со скала-выражением в дерево абстрактного синтаксиса. Работает только с выражениями, т.е. разбор объявления пакета завершится ошибкой.

Префиксное дерево, из которого выбран макрос.

Например, для макроса filter определённого как метод экземпляра на коллекции Coll, prefix представляет эквивалент this для обычных методов экземпляра:

scala> class Coll[T] {
     | def filter(p: T => Boolean): Coll[T] = macro M.filter[T]
     | }; object M {
     | def filter[T](c: Context { type PrefixType = Coll[T] })
     |              (p: c.Expr[T => Boolean]): c.Expr[Coll[T]] =
     |   {
     |     println(c.prefix.tree)
     |     c.prefix
     |   }
     | }
defined class Coll
defined module Macros

scala> new Coll[Int]().filter(_ % 2 == 0)
new Coll[Int]()
res0: Coll[Int] = ...

scala> val x = new Coll[String]()
x: Coll[String] = ...

scala> x.filter(_ != "")
$line11.$read.$iw.$iw.$iw.$iw.$iw.$iw.$iw.$iw.$iw.$iw.$iw.$iw.x
res1 @ 35563b4b: x.type = ...

Обратите внимание, как значение prefix меняется в зависимости от квалификатора вызова макроса (т.е. выражения, которое находится слева от точки).

Ещё одна примечательная вещь в приведённом фрагменте — тип Context { type PrefixType = Coll[T] }, который используется для того, чтобы подчеркнуть, что реализация макроса работает с префиксами типа Coll[T].

Для данного типа генерируется дерево, которое при компиляции и выполнении создаёт класс времени выполнения окружающего класса или модуля. Возвращает EmptyTree если не существует окружающего класса или модуля.

Для данного типа генерируется дерево, которое при компиляции и выполнении создаёт класс времени выполнения исходного типа. Если concrete равно true, эта функция будет прерываться для типов, которые ссылаются на абстрактные типы (как это делает ClassTag).

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

Сгенерированное дерево будет связано со специфицированными universe и mirror. Возможные значения для universe включают universe.internal.gen.mkRuntimeUniverseRef. Возможные значения для mirror включают EmptyTree (в этом случае реификтор автоматически выберет подходящее зеркало).

Эта функция тесно связана с Universe.reify, макросом, который преобразует произвольные выражения в деревья во время выполнения. Они выполняют очень похожие действия (Universe.reify вызывает Context.reifyTree для реализации себя), но работают на разных метауровнях (см. ниже).

Давайте изучим различия между Context.reifyTree и Universe.reify на примере их использования внутри макроса fooMacro:

* Поскольку сам reify является макросом, он будет выполнен при компиляции fooMacro (метауровень -1) и сгенерирует дерево, которое при вычислении во время расширения макроса fooMacro (метауровень 0) воссоздаст входное дерево.

Это обеспечивает возможность, аналогичную квазицитированию. Написание "reify{ expr }" сгенерирует AST, представляющий expr. После этого этот AST (или его части) можно использовать для построения возвращаемого значения fooMacro.

* reifyTree вычисляется во время расширения макроса (метауровень 0) и сгенерирует дерево, которое при вычислении во время выполнения программы (метауровень 1) воссоздаст входное дерево.

Это предоставляет способ сохранения определенных деревьев со времени расширения макроса для последующего просмотра во время выполнения. Например, авторам DSL может быть полезно захватывать фрагменты DSL в AST, которые затем обрабатываются во время выполнения специальным образом.

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

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

* Результат компиляции и выполнения результата reifyTree будет prefix, который необходимо явно передать. Это происходит, потому что Вселенная результата вычисления находится на другом метауровне, чем контекст, вызвавший reify.

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

В заданном типе, сгенерировать дерево, которое при компиляции и выполнении произведёт исходный тип. Сгенерированное дерево будет связано со специфицированными universe и mirror. Для получения дополнительной информации и примеров, обратитесь к документации для Context.reifyTree и Universe.reify.

Выводит специфичные для макроса настройки в виде списка строк. Эти настройки передаются компилятору через командную строку "-Xmacro-settings:setting1,setting2...,settingN".

Проверяет заданное дерево на соответствие ожидаемому типу pt в контексте макро-вызова во время проверки типов с режимом проверки, указанном в mode по умолчанию в режиме TERMmode. Это заполняет символы и типы дерева и, возможно, преобразует его для отражения определенных десугаринг-преобразований.

Если silent ложно, TypecheckException будет брошен в случае ошибки проверки типов. Если silent истинно, проверка типов будет тихой и вернёт EmptyTree в случае ошибки. Такие ошибки не исчезают и могут быть проверены, включив -Ymacro-debug-verbose. В отличие от inferImplicitValue и inferImplicitView, silent по умолчанию ложно.

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

Отменяет реификацию дерева.

Это обращение не просто восстанавливает исходное дерево (это потеряло бы контекст реификации), а делает что-то более сложное, что соответствует следующим законам:

1) unreifyTree(reifyTree(tree)) != tree // деифицированное дерево — это дерево + сохранённый контекст // в текущей реализации результат unreify является непрозрачным // т. е. нет возможности просмотреть базовое дерево/контекст

2) reifyTree(unreifyTree(reifyTree(tree))) == reifyTree(tree) // результат реификации дерева в его исходном контексте равен // результату реификации дерева вместе с его сохранённым контекстом

3) compileAndEval(unreifyTree(reifyTree(tree))) ~ compileAndEval(tree) // во время выполнения исходное и деифицированное деревья поведенчески эквивалентны

В текущей реализации API отражения Scala, нетипизированные деревья (также известные как деревья-парсеры или деревья без атрибутов) наблюдательно отличаются от типизированных деревьев (также известные как деревья-тайперы, проверенные на тип деревья или деревья с атрибутами),

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

Обратите внимание, что untypecheck в настоящее время страдает от проблемы https://github.com/scala/bug/issues/5464, из-за которой иногда деревья повреждаются, так что они больше не имеют смысла. К сожалению, обходного пути для этого нет. Мы планируем исправить эту проблему в ближайшее время, но пока, пожалуйста, имейте это в виду.

Выводит предупреждение. Используйте enclosingPosition если вы сомневаетесь, какую позицию передать в pos.

Дерево, соответствующее окружающему классу, или EmptyTree, если это не применимо.

Дерево, соответствующее окружающему дереву DefDef. Выбрасывает EnclosureException если нет такого окружающего дерева.

Дерево, соответствующее окружающему дереву ImplDef (т.е. либо ClassDef, либо ModuleDef). Выбрасывает EnclosureException если нет такого окружающего дерева.

Дерево, соответствующее окружающему методу, или EmptyTree, если это не применимо.

Дерево, соответствующее окружающему дереву PackageDef. Выбрасывает EnclosureException если нет такого окружающего дерева.

Сеанс компиляции, содержащий это применение макроса.

Дерево, соответствующее дереву Шаблона, содержащему эту функцию. Возвращает EnclosureException, если такого дерева нет.

Единица компиляции, содержащая это применение макроса.

Создаёт более или менее уникальное имя, имеющее заданное имя в качестве префикса и тот же тип (имя переменной или имя типа), что и заданное имя. Обратитесь к scala.reflect.macros.Names для получения дополнительной информации об уникальности таких имён.

Создаёт строку, представляющую более или менее уникальное имя, имеющее заданный префикс. Обратитесь к scala.reflect.macros.Names для получения дополнительной информации об уникальности таких имён.

Создаёт строку, представляющую более или менее уникальное имя. Обратитесь к scala.reflect.macros.Names для получения дополнительной информации об уникальности таких имён.

Краткая запись для Literal(Constant(x: Char)) в базовом universe.

Краткая запись для Literal(Constant(x: String)) в базовом universe.

Краткая запись для Literal(Constant(x: Double)) в базовом universe.

Краткая запись для Literal(Constant(x: Float)) в базовом universe.

Сокращенная запись для Literal(Constant(x: Long)) в базовом universe.

Сокращенная запись для Literal(Constant(x: Int)) в базовом universe.

Сокращенная запись для Literal(Constant(x: Short)) в базовом universe.

Сокращенная запись для Literal(Constant(x: Byte)) в базовом universe.

Сокращенная запись для Literal(Constant(x: Boolean)) в базовом universe.

Сокращенная запись для Literal(Constant(false)) в базовом universe.

Сокращенная запись для Literal(Constant(null)) в базовом universe.

Сокращенная запись для Literal(Constant(true)) в базовом universe.

Сокращенная запись для Literal(Constant(())) в базовом universe.

Рекурсивно сбрасывает локально определенные символы и типы в заданном дереве. ВНИМАНИЕ: Не используйте этот API, используйте untypecheck вместо этого.

Конструктор/экстрактор для Expr.

Конструктор/экстрактор для TypeTag.

Конструктор/экстрактор для WeakTypeTag.

Символ типа x, полученный из тега типа.

Сокращение для implicitly[TypeTag[T]].tpe

Сокращение для implicitly[TypeTag[T]]

Сокращение для implicitly[WeakTypeTag[T]].tpe

Сокращение для implicitly[WeakTypeTag[T]]