Haxe Metadata

发表评论

Table of Contents

1 Compiler Metadata

1.1 General metadata

1.1.1 @:require(xxx)

will only allow access to the given field if the xxx compiler condition variable is set (for instance with -D xxx). Can also be set on a whole class, in that case the class can still be referenced but all its statics and its constructor accesses are forbidden if the xxx var is not set. You can also specify a custom error message with @:require(xxx,"Requires XXX")

1.1.2 @:final

the given class cannot be subclassed anymore

1.1.3 @:hack

allows a class marked as final to be subclassed (use at your own risk)

1.1.4 @:native("my.real.Path")

the given class (and all its accesses) will be compiled as if its real class path was the one given in parameter. This makes it more easy to bind "extern" classes that might have a different name.

1.1.5 @:coreApi

identifies this class as a "core api class". Its API will get checked against the abstract one declared in the Haxe standard library.

1.1.6 @:fakeEnum(Type)

tells the Haxe compiler that this enum is just a collection of properties of the given Type. The compiler will not use enum switch for these, but instead uses the classic switch. The Type can be used by the code generator backend to know the actual field type (in general either String or Int)

1.1.7 @:macro and @:build

see Macros

1.1.8 @:keep

the given class or field will be preserved in the generated output even if never directly referenced. Use it in conjunction with –dead-code-elimination.

1.1.9 @:keepSub

extends @:keep to all child classes (which can be ideal for e.g. a common base class of a unit testing framework). Use it in conjunction with –dead-code-elimination.

1.1.10 @:overload

can be used when interfacing an external class method with arguments of different types. You can have several overload declarations, the return type of the first one that is matched will be used. Overload metadata is only useful for extern classes, it is most likely not usable for user-written Haxe classes. A simple example:

@:overload(function(i:String):Bool{})
function foo( i : Int ) : Void;

1.1.11 @:extern static inline function foo() { … }

this function will always be inlined but will not be generated as part of the resulting code. (since 2.09)

1.1.12 @:optional

declares optional fields in typedefs. (since 2.09)

1.1.13 @:feature("value")

attributed to fields that are required for specific features, such as typed casts or reflection. (since 2.10)

1.1.14 @:noCompletion

does not list the field as part of compiler completion results (since 3.0)

1.1.15 @:noUsing

don't allow this static field to be used as part of the "using" mixin (since 3.0)

1.1.16 @:allow(my.pack)

This will give access to all private fields of a class to all the classes in the package my.pack (and its sub-packages). See Access Control for more info. (since 3.0)

1.1.17 @:access(my.pack.MyClass)

Used together with an external library or other code which for some reason you can't modify to add the necessary @:allow declarations. See Access Control for more info. (since 3.0)

1.1.18 @:generic

To be used instead of 'implements haxe.rtti.Generic' to declare generic classes. (since 3.0)

1.1.19 @:publicFields

To be used instead of 'implements haxe.Public', which changes the default fields' visibility from private to public. This also applies to sub classes. (since 3.0)

1.2 JavaScript Specific metadata

In order to improve support for interacting with JavaScript, the following compiler metadata are available for the JavaScript platform only :

1.2.1 @:expose or @:expose("name")

this class will be available from the window object (since 2.10)

1.2.2 @:defineFeature

will set a feature when typed (even if inlined) (since 2.10)

1.3 Flash Specific metadata

In order to improve support for interacting with AS3 and Flash IDE, the following compiler metadata are available for Flash9+ platform only :

1.3.1 @:bind

when a class declared in Haxe without extern is already present in a SWF library, an error will be displayed. You can use @:bind before your class declaration to have it override the original SWF class declaration.

1.3.2 @:bitmap("myfile.png|jpg|gif") class MyBitmapData extends flash.display.BitmapData {}

include a given bitmap file into the target SWF and associate it to MyBitmapData class. The file is looked-up using the classpath. use with `new MyBitmapData(0,0)`

1.3.3 @:file("a.dat") class MyByteArray extends flash.utils.ByteArray

include a given binary file into the target SWF and associate it to MyByteArray class

1.3.4 @:font("path.ttf", range="") class MyFont extends flash.text.Font

embed the specified TrueType font into the swf. The second argument can be used limit the range of embedded characters, e.g. to "a-z0-9{}HW" (since 3.0)

1.3.5 @:sound("file.wav|mp3") class MySound extends flash.media.Sound

include a given sound file into the target SWF and associate it to MySound class

1.3.6 @:ns("namespace")

the specified field or method will be given this namespace

1.3.7 @:protected

the specified field or method is marked as protected (used when overriding protected methods for instance)

1.3.8 @:getter(x) function returnGetX() return 5

will generate a native getter on the x property. Please note that the method returnGetX no longer exists, so do not call it directly. This feature is mainly used to override superclass getters. (To expose the x property to the rest of your haxe code, add @:extern public var x(default,never) : Int; (since 2.10)

1.3.9 @:setter(x) function setX( v : Float ) : Void { … }

same as @:getter, but for setting the property.

1.3.10 @:meta(Event(name="test",type="Foo"))

generates the corresponding Flash metadata

1.3.11 @:debug function foo() { …. }

force debug information to be generated for this method (even when compiled without -debug) (since 2.09)

1.3.12 @:noDebug function foo() { …. }

disable debug information for this method or the whole class (even when compiled with -debug) (was nodebug in 2.10-)

1.4 CPP Specific metadata

In order to improve support for interacting with CPP, the following compiler metadata are available from the latest HXCPP repository and Haxe repository (all since 2.09) :

1.4.1 @:headerCode("#include <stdio.h>")

Inject code into class header file - eg for types of injected members.

1.4.2 @:headerClassCode("code")

Inject code into header class definition - eg member variables/functions.

1.4.3 @:cppFileCode("code")

Inject code into top of cpp file - eg local includes, local functions, static variables.

1.4.4 @:functionCode("code")

Inject code into top of function - eg, whole implementation.

1.4.5 @:functionTailCode("code")

Inject code into end of function - eg, close functionCode, or continue processing.

1.4.6 @:buildXml("xml fragment")

Inject code into the bottom of the build.xml code.

1.4.7 @:depend("code")

Add a dependency in the build.xml file.

1.4.8 @:include("ClassName")

Generate "#include …" to .h/.cpp where the class is being imported.

1.5 Java Specific metadata

In order to improve interaction with native Java code, there were created some java-specific metadata:

1.5.1 @:protected

the specified field or method is marked as protected (used when overriding protected methods for instance)

1.5.2 @:internal

the specified field or method is marked as internal (used when overriding protected methods for instance)

1.5.3 @:final

the specified field or method is marked as final

1.5.4 @:volatile

the specified field or method is marked as volatile

1.5.5 @:transient

the specified field or method is marked as transient

1.5.6 @:functionBody("Code")

will replace the contents of the target function with "code"

1.5.7 @:classCode("Code")

Inject "code" to the contents of the class

1.6 Undocumented metadata

Metadata the compiler accepts, but do not have any documentation.

1.6.1 @:remove

Works in JavaScript target. Classes and Interfaces marked with this meta data will not generate any output.

2 Building Types with Macros

给类加上@:build即可在宏编译阶段对该类进行处理

@:build(MyMacro.build()) 
class C {
}

// MyMacro.hx
import haxe.macro.Expr;
class MyMacro {
    macro public static function build() : Array<Field> {        
        var pos = haxe.macro.Context.currentPos();
        var fields = haxe.macro.Context.getBuildFields();
        // add a new public class field named "hello" with type "Int"
        var tint = TPath({ pack : [], name : "Int", params : [], sub : null });
        fields.push({ name : "hello", doc : null, meta : [], access : [APublic], kind : FVar(tint,null), pos : pos });
        return fields;
    }
}

2.1 AutoBuild

如果在类或者接口定义前加上 @:autoBuild(buildMacro())，则所有继承该类或实现该接口的类都会自动加上@:build 可用haxe.macro.Context.getLocalClass()访问当前类

3 自定义Metadata

可与宏结合，判断宏编译阶段需要处理的方法

import haxe.rtti.Meta;
@author("hoothin")
@debug
class MyClass {
  @range(1, 8)
  var value:Int;
  @broken
  @:noCompletion
  static function method() { }
}

class Main {
  static public function main() {
    // { author : ["hoothin"], debug : null }
    trace(Meta.getType(MyClass));
    // [1,8]
    trace(Meta.getFields(MyClass).value.range);
    // { broken: null }
    trace(Meta.getStatics(MyClass).method);
  }
}

发表回复

您的电子邮箱地址不会被公开。 必填项已用 * 标注