Haxe 2 -> Haxe 3迁移指南

官网英文原文：http://haxe.org/manual/haxe3_migration

混合类型数组
症状: 编译错误 Arrays of mixed types are only allowed if the type is forced to Array<Dynamic>
解释：Haxe 2允许这样定义混合数组: [1, "foo"]，编译器会自动推断其类型为Array<Dynamic>。Haxe 3不允许如此定义，除非数组被显式声明为Array<Dynamic>。
修正：使用Array<Dynamic>显式定义混合类型数组。包括以下几种情形：
赋值到类型为Array<Dynamic>的变量: var a:Array<Dynamic> = [1, "foo"];
赋值到类型为Array<Dynamic>的类成员域
将其作为需求Array<Dynamic>类型的函数参数
从声明返回类型为Array<Dynamic>的函数返回值
例程：

// haxe 2
var x = [1, "foo"];

// haxe 3
var x:Array<Dynamic> = [1, "foo"];

Callback关键字
症状：编译错误 callback syntax has changed to func.bind(args)
解释：Haxe 2 had a callback keyword which could be used for partial application. In haxe 3 the special field bind can be invoked on functions.
修正：Replace callback(func,args) with func.bind(args)
例程：

function add(a, b) return a + b;
// haxe 2
callback(add, 1);
// haxe 3
add.bind(1);

系统平台API的整理统一

症状：Class not found errors for the following packages:
cpp, cpp.io, cpp.net
neko, neko.db, neko.io, neko.net, neko.zip
php, php.db, php.io, php.net
解释：Haxe 3 generalized several APIs of sys-platforms in the sys package. The platform-specific versions from haxe 2 were removed.
修正：Use the platform-independent classes in sys, sys.db sys.io and sys.net instead.

Hash和IntHash类已移除

症状：编译错误 Hash has been removed, use Map instead or IntHash has been removed, use Map instead
解释：Haxe 2 provided Hash and IntHash as toplevel classes. In haxe 3 their implementations was moved to the haxe.ds package and a general-purpose Map type remains in the toplevel.
修正：
Replace Hash with Map, possibly adding an explicit String key if required
Replace IntHash with Map, possibly adding an explicit Int key if required
例程：

// haxe 2
var hash = new Hash();
var intHash = new IntHash();

// haxe 3
var hash = new Map();
var intHash = new Map();

hash.set("foo", 1);
intHash.set(1, 2);

haxe.rtti接口

症状：编译错误 Use @:generic instead of implementing haxe.Generic or Use @:rtti instead of implementing haxe.rtti
解释：Haxe 2 used the special interfaces haxe.rtti.Generic and haxe.rtti.Infos to enable particular behavior. In haxe 3 they have been replaced by @:generic and @:rtti metadata respectively.
修正：
Remove implements haxe.rtti.Generic and add @:generic metadata to the class
Remove implements haxe.rtti.Infos and add @:rtti metadata to the class
例程：

// haxe 2
class GenericClass extends haxe.rtti.Generic { }
class RttiClass extends haxe.rtti.Infos { }

// haxe 3
@:generic class GenericClass { }
@:rtti class RttiClass { }

内联变量的初始化

症状：编译错误 Variable initialization must be a constant value
解释：Haxe 2 allowed arbitrary expressions as initialization to inline variables. This could cause unexpected behavior because expressions with potential side-effects were injected to the place of their access. Haxe 3 restricts the allowed expressions to constant ones, i.e. those that have no side-effects.
修正：Use an inline function returning the value instead.
例程：

// haxe 2
static inline var x = [];

// haxe 3
static inline function x() {
    return [];
}

Int32
症状：编译错误 haxe.Int32 has been removed, use normal Int instead or errors related to readUInt30, readInt31, writeUInt30, writeInt31
解释：Haxe 3 provided the haxe.Int32 Api to enable 32-bit integer operations across all targets. This is no longer necessary for haxe 3, so the Api has been removed.
修正：
replace all occurences of Int32 with Int
replace readUInt30 and readInt31 with readInt32
replace writeUInt30 and writeInt32 with writeInt32

接口语法变化

症状：编译错误 Interfaces cannot implements another interface (use extends instead) or Unexpected ,
解释：In haxe 2 interfaces would use implements to extend other interfaces, and multiple extends and implements declaration were separated by a comma. In haxe 3 interfaces use extends instead and the separating comma is no longer allowed.
修正：
replace implements with extends on interface declarations
remove the comma separating multiple implements and extends declarations
例程：

// haxe 2
interface InterfaceSyntax { }
interface InterfaceSyntax2 implements InterfaceSyntax { }
class InterfaceSyntaxClass extends haxe.Template, implements InterfaceSyntax2 { }

// haxe 3
interface InterfaceSyntax { }
interface InterfaceSyntax2 extends InterfaceSyntax { }
class InterfaceSyntaxClass extends haxe.Template implements InterfaceSyntax2 { }

Macro reification changes

症状：Various compiler errors when using macro reification
解释：The reification syntax of haxe 2 has been changed for haxe 3. While now being more flexible and readable, it likely breaks haxe 2 reification code.
修正：
replace $(value) with $v{value}
例程：

// haxe 2
var v = macro $(1);

// haxe 3
var v = macro $v{1};
Order of import and using
症状：The compiler infers identifiers to the wrong type.
解释：Haxe 2 resolved unknown identifiers by checking the list of imported modules from top to bottom. Haxe 3 checks this list from bottom to top.
修正：Reverse the declarations of import and using in a file that causes problems.

属性的访问器
症状：编译错误 Custom property accessor is no longer supported, please use get/set
解释：In haxe 2 it was possible to use custom names for the getter and setter of a property. Haxe 3 enforces the naming scheme of get_propertyName and set_propertyName for the getter and setter respectively.
修正：Fixing this involves two steps per property:
use get and set in the property declaration, e.g. var prop(get,set):Int;
rename the accessor function to get_propertyName and set_propertyName for the getter and setter respectively
例程：

// haxe 2
var property(getProperty, setProperty):Int;
function getProperty() return 1
function setProperty(i) return 1

// haxe 3
var property(get, set):Int;
function get_property() { return 1; }
function set_property(i) {return 2; }

属性域的创建

症状：编译错误 This field cannot be accessed because it is not a real variable
解释：In haxe 2 properties always had a real field representation, even if they did not need one. In particular, this applied to pure getter/setter properties. Haxe 3 treats properties as real variables only if they have a default or null access.
修正：Add @:isVar to the property in question.
例程：

// haxe 2
var property(get, set):Int;
function get_property() { return property; }
function set_property(i) {return property = i; }

// haxe 3
@:isVar var property(get, set):Int;
function get_property() { return property; }
function set_property(i) {return property = i; }

字符串插值 interpolation

症状：编译错误 Std.format has been removed, use single quote 'string ${escape}' syntax instead
解释：Haxe 2 was using a haxe macro accessible as Std.format() for String interpolation. In haxe 3 single quotes syntax can be used instead.
修正：Remove the call to Std.format and enclose the String by ' instead of ".
例程：

var x = 12;
// haxe 2
var s = Std.format("x equals $x");
// haxe 3
var s = '$x * $x equals ${x * x}';
trace(s); // 12 * 12 equals 144

Switch的变化

症状：Various compiler errors or warnings in a switch expression
解释：By default Haxe 3 uses pattern matching. While this enables a concise and expressive way for many cases, it may introduce a few incompatibilities to the switch expression used in Haxe 2.
修正：Adding -D no-pattern-matching to the command line will disable pattern matching and retain the haxe 2 behavior. Otherwise it might be worthwhile to adjust the case expressions to conform with the new switch specification. This includes:
null patterns are not allowed and should be replaced by a guard-expression: case CTor("foo",x) if (x == null):
Unused variables will generate a warning because they might have a negative impact on the code output. They can be replaced with _ or an identifier starting with _ in case they are still refered to in documentation.
The | operator is used as or-operator and cannot be used to do in-case integer calculation anymore. These should be moved to e.g. an inline variable.
Some rare case-patterns may no longer be supported, in which case they can be replaced with a if .. else if ... else chain.
A compiler error Capture variables must be lower-case may indicate that a type name or enum constructor could not be found. Make sure that the intended type can be resolved.

若干Api变化

General:
haxe.BaseCode -> haxe.crypto.BaseCode
haxe.Md5 -> haxe.crypto.Md5
haxe.SHA1 -> haxe.crypto.Sha1
EReg.customReplace -> EReg.map
StringTools.isEOF -> StringTools.isEof
IntIter -> IntIterator
haxe.Stack -> haxe.CallStack
neko:
neko.zip.Reader -> haxe.zip.Reader
neko.zip.Writer -> haxe.zip.Writer

新的关键字

In order to support abstract types, an abstract keyword has been added to the language. If you use this as an identifier or a package name, the compiler will reject it in haxe3.

Tools for conversion of haxe2 code to haxe3 code.
Simon's library for getting a haxe2 code base running in haxe3 hx2compat, obviously this is always changing until haxe3 is released, this link is just added for developers working with haxe svn nightlies and can be useful as further guide to changes.