macro.Context
Context
package haxe-macro
Available on macro, nekoContext provides an API for macro programming.
It contains common functions that interact with the macro interpreter to query or set information. Other API functions are available in the tools classes:
Static methods
static addResource (name:String, data:Bytes):Void
Makes resource data
available as name
.
The resource is then available using the haxe.macro.Resource
API.
If a previous resource was bound to name
, it is overwritten.
Compilation server : when using the compilation server, the resource is bound to the Haxe module which calls the macro, so it will be included again if that module is reused. If this resource concerns several modules, prefix its name with a $ sign, this will bind it to the macro module instead.
static currentPos ():Position
Returns the position at which the macro was called.
static defineModule (modulePath:String, types:Array<TypeDefinition>, ?imports:Array<ImportExpr>, ?usings:Array<TypePath>):Void
Defines a new module as modulePath
with several TypeDefinition
types
. This is analogous to defining a .hx file.
The individial types
can reference each other and any identifier respects the imports
and usings
as usual, expect that imports are not allowed to have .*
wildcards or in s
shorthands.
static defineType (t:TypeDefinition):Void
Defines a new type from TypeDefinition
t
.
static defined (s:String):Bool
Tells if compiler directive s
has been set.
Compiler directives are set using the -D
command line parameter, or by calling haxe.macro.Compiler.define
.
static definedValue (key:String):String
Returns the value defined for compiler directive key
.
If no value is defined for key
, null is returned.
Compiler directive values are set using the -D key=value
command line parameter, or by calling haxe.macro.Compiler.define
.
The default value is "1"
.
static error (msg:String, pos:Position):Dynamic
Displays a compilation error msg
at the given Position
pos
and aborts the current macro call.
static fatalError (msg:String, pos:Position):Dynamic
Displays a compilation error msg
at the given Position
pos
and aborts the compilation.
static follow (t:Type, ?once:Bool):Type
Follows a type.
See haxe.macro.TypeTools.follow
for details.
static followWithAbstracts (t:Type, once:Bool = false):Type
Follows a type, including abstracts' underlying implementation
See haxe.macro.TypeTools.followWithAbstracts
for details.
static getBuildFields ():Array<Field>
Returns an Array
of fields of the class which is to be built.
This is only defined for @:build/@:autoBuild
macros.
static getCallArguments ():Null<Array<Expr>>
Returns the call arguments that lead to the invocation of the current @:genericBuild
macro, if available.
Returns null
if the current macro is not a @:genericBuild
macro.
static getClassPath ():Array<String>
Returns an Array
of current class paths in the order of their declaration.
Modifying the returned array has no effect on the compiler. Class paths can be added using haxe.macro.Compiler.addClassPath
.
static getDefines ():Map<String, String>
Returns a map of all compiler directives that have been set.
Compiler directives are set using the -D
command line parameter, or by calling haxe.macro.Compiler.define
.
Modifying the returned map has no effect on the compiler.
static getExpectedType ():Null<Type>
Returns the type which is expected at the place the macro is called.
This affects usages such as var x:Int = macroCall()
, where the expected type will be reported as Int.
Might return null if no specific type is expected or if the calling macro is not an expression-macro.
static getLocalClass ():Null<Ref<ClassType>>
Returns the current class in which the macro was called.
If no such class exists, null is returned.
static getLocalImports ():Array<ImportExpr>
Returns an Array
of all imports in the context the macro was called.
Modifying the returned array has no effect on the compiler.
static getLocalMethod ():Null<String>
Returns the name of the method from which the macro was called.
If no such method exists, null is returned.
static getLocalModule ():String
Returns the current module path in/on which the macro was called.
static getLocalTVars ():Map<String, TVar>
Similar to getLocalVars
, but returns elements of type TVar
instead of Type
.
static getLocalType ():Null<Type>
Returns the current type in/on which the macro was called.
If no such type exists, null is returned.
static getLocalUsing ():Array<Ref<ClassType>>
Returns an Array
of classes which are available for using
usage in the context the macro was called.
Modifying the returned array has no effect on the compiler.
static getLocalVars ():Map<String, Type>
Returns a map of local variables accessible in the context the macro was called.
The keys of the returned map are the variable names, the values are their types.
Modifying the returned map has no effect on the compiler.
static getModule (name:String):Array<Type>
Resolves a module identified by name
and returns an Array
of all its contained types.
The resolution follows the usual class path rules where the last declared class path has priority.
If no module can be found, null is returned.
static getPosInfos (p:Position):{min:Int, max:Int, file:String}
Returns the information stored in Position
p
.
static getResources ():Map<String, Bytes>
Returns a map of all registered resources for this compilation unit.
Modifying the returned map has no effect on the compilation, use haxe.macro.Context.addResource
to add new resources to the compilation unit.
static getType (name:String):Type
Resolves a type identified by name
.
The resolution follows the usual class path rules where the last declared class path has priority.
If no type can be found, an exception of type String
is thrown.
static getTypedExpr (t:TypedExpr):Expr
Returns a syntax-level expression corresponding to typed expression t
.
This process may lose some information.
static makeExpr (v:Dynamic, pos:Position):Expr
Builds an expression from v
.
This method generates AST nodes depending on the macro-runtime value of v
. As such, only basic types and enums are supported and the behavior for other types is undefined.
The provided Position
pos
is used for all generated inner AST nodes.
static makePosition (inf:{min:Int, max:Int, file:String}):Position
Builds a Position
from inf
.
static onAfterGenerate (callback:Void ‑> Void):Void
Adds a callback function callback
which is invoked after the compiler generation phase.
Compilation has completed at this point and cannot be influenced anymore. However, contextual information is still available.
static onAfterTyping (callback:Array<ModuleType> ‑> Void):Void
Adds a callback function callback
which is invoked after the compiler is done typing, but before optimization. The callback receives the types which have been typed.
It is possible to define new types in the callback, in which case it will be called again with the new types as argument.
static onGenerate (callback:Array<Type> ‑> Void):Void
Adds a callback function callback
which is invoked after the compiler's typing phase, just before its generation phase.
The callback receives an Array
containing all types which are about to be generated. Modifications are limited to metadata, it is mainly intended to obtain information.
static onMacroContextReused (callb:Void ‑> Bool):Void
Register a callback function that will be called everytime the macro context cached is reused with a new compilation. This enable to reset some static vars since the code might have been changed. If the callback returns false, the macro context is discarded and another one is created.
static onTypeNotFound (callback:String ‑> TypeDefinition):Void
Adds a callback function callback
which is invoked when a type name cannot be resolved.
The callback may return a type definition, which is then used for the expected type. If it returns null, the type is considered to still not exist.
static parse (expr:String, pos:Position):Expr
Parses expr
as Haxe code, returning the corresponding AST.
String interpolation of single quote strings within expr
is not supported.
The provided Position
pos
is used for all generated inner AST nodes.
static parseInlineString (expr:String, pos:Position):Expr
Similar to parse
, but error positions are reported within the provided String expr
.
static registerModuleDependency (modulePath:String, externFile:String):Void
Evaluates e
as macro code.
Any call to this function takes effect when the macro is executed, not during typing. As a consequence, this function can not introduce new local variables into the macro context and may have other restrictions.
Usage example:
var e = macro function(i) return i * 2;
var f:Int -> Int = haxe.macro.Context.eval(e);
trace(f(2)); // 4
Code passed in from outside the macro cannot reference anything in its context, such as local variables. However, it is possible to reference static methods.
This method should be considered experimental.
If e
is null, the result is unspecified.
static registerModuleReuseCall (modulePath:String, macroCall:String):Void
Register a macro call to be performed everytime the module modulePath
is reused by the compilation cache, meaning that neither the module itself nor its dependencies was changed since last compilation.
The macroCall
should be a String containing valid Haxe expression, similar to --init
macros (see https://haxe.org/manual/macro-initialization.html). Multiple calls with the exact same macroCall
value will only register the callback once.
This also triggers loading of given module and its dependencies, if it's not yet loaded, but given macro call will not be called on the first module load.
If the compilation cache is not used, macroCall
expressions will not be called, but calling this function will still trigger loading of given modulePath
.
static resolvePath (file:String):String
Resolves a file name file
based on the current class paths.
The resolution follows the usual class path rules where the last declared class path has priority.
If a class path was declared relative, this method returns the relative file path. Otherwise it returns the absolute file path.
static resolveType (t:ComplexType, p:Position):Type
Resolve type t
and returns the corresponding Type
.
Resolving the type may result in a compiler error which can be caught using try ... catch
. Resolution is performed based on the current context in which the macro is called.
static signature (v:Dynamic):String
Returns a hashed MD5 signature of value v
.
static storeTypedExpr (t:TypedExpr):Expr
Store typed expression t
internally and give a syntax-level expression that can be returned from a macro and will be replaced by the stored typed expression.
If t
is null or invalid, an exception is thrown.
NOTE: the returned value references an internally stored typed expression that is reset between compilations, so care should be taken when storing the expression returned by this method in a static variable and using the compilation server.
static toComplexType (t:Type):Null<ComplexType>
Returns the ComplexType
corresponding to the given Type
t
.
See haxe.macro.TypeTools.toComplexType
for details.
static typeExpr (e:Expr):TypedExpr
Types expression e
and returns the corresponding TypedExpr
.
Typing the expression may result in a compiler error which can be caught using try ... catch
.
static typeof (e:Expr):Type
Types expression e
and returns its type.
Typing the expression may result in a compiler error which can be caught using try ... catch
.
static unify (t1:Type, t2:Type):Bool
Tries to unify t1
and t2
and returns true
if successful.
static warning (msg:String, pos:Position):Void
Displays a compilation warning msg
at the given Position
pos
.
© 2005–2016 Haxe Foundation
Licensed under a MIT license.
http://api.haxe.org/haxe/macro/Context.html