Code Cookbook example custom generator needed and problems

[mingodad]

Trying to understand how to use haxe.macro.Context.onGenerate(types:Array<Type>) to create custom generators I noticed that the types parameter comes with a strange order instead of the declaration order (line number) see the output bellow, this make it's usage a bit more involved than if it came ordered by file/line number, also probably in doing a working example several corner cases will surface and internal changes can be made to make life easy for Haxe users.

Would be nice to have an entry in the Code Cookbook with a simple functional example and I suggest the one bellow as starting point (generate Haxe again for simplicity), any comments/suggestions/improvements are welcome !

• TestOnGenerate.hx:

final _version = "1.0";

/** Get version string. */

function getVersion(): String {
	return _version;
}

enum Color {
	Red;
	Green;
	Blue;
	RGB(r: Int, g: Int, b: Int);
}

class Test {
  static var _count: Int = 0;
  public var name:String;
  public var x:Float;
  public var y:Float;

  public function new(name:String, x:Float, y:Float) {
    this.name = name;
    this.x = x;
    this.y = y;
  }
  public function toString() : String {
	return name + "::" + Std.string(x) + "::" + Std.string(y);
  }
}

class TestOnGenerate {
    static function main() {
        var t = new Test("dad", 1.4, 2.9);
	trace(t.toString() + "::" + getVersion());
    }
}

• MyOnGenerate.hx:

#if macro
import haxe.macro.Type;
import haxe.macro.Context;

using haxe.macro.PositionTools;

/**
 * Callback on generating code from context
 */
private function mygenerate(types:Array<Type>, filterFileName: String):Void {
	var buf = new StringBuf();
	for (atype in types) {
		// trace(atype);
		var aref = atype.getParameters()[0].get();
		var apos = Context.getPosInfos(aref.pos);
		//trace(apos);
		if(filterFileName != null && apos.file != filterFileName) continue;
		switch (atype) {
			case TMono(t):
				trace(t + "::" + aref.pos);
			case TEnum(t, params):
				var t_ref = t.get();
				//trace(t.toString() + "::" + aref.pos + "::" + params.toString());
				buf.add('\nenum ${t_ref.name} {\n');
				var enumFields = [];
				for (efield in t_ref.constructs) {
					//trace(efield);
					var ebuf = new StringBuf();
					ebuf.add('\t${efield.name}');
					switch(efield.type) {
						case TEnum(_, _): ebuf.add(";\n");
						case TFun(args, _):
							ebuf.add("(");
							for (i in 0...args.length) {
								var arg = args[i];
								if (i > 0)
									ebuf.add(", ");
								var type_name = switch(arg.t) {
									case TAbstract(t, params): t.get().name;
									default:
										throw 'Unsupported paramter ${arg.t}';
										null;
								};
								ebuf.add('${arg.name}: ${type_name}');
							}
							ebuf.add(");\n");

						default:
							throw 'Unsupported paramter ${efield.type}';
					}
					enumFields.insert(efield.index, ebuf.toString());
				}
				for(elm in enumFields) buf.add(elm);
				buf.add("}\n");
				//trace(buf.toString());
			case TInst(t, params):
				var t_ref = t.get();
				trace(aref.name + "::" + aref.pos /*.getInfos().min*/ + "::" + params.toString());
				var classFields = t_ref.fields.get();
				buf.add('\nclass ${t_ref.name} {\n');
				//trace(classFields);
				if(t_ref.constructor != null) trace(t_ref.constructor.get());
				for (ifield in classFields) {
					trace(ifield);
					buf.add('\t${ifield.name};\n');
				}
				trace(t_ref.statics.get());
				buf.add("}\n");
				//trace(buf.toString());
			case TType(t, params):
				trace(aref.name + "::" + aref.pos /*.getInfos().min*/ + "::" + params.toString());
			case TFun(args, ret):
				trace(args + "::" + aref.pos + "::" + ret);
			case TAnonymous(a):
				trace(a + "::" + aref.pos);
			case TDynamic(t):
				trace(t + "::" + aref.pos);
			case TLazy(f):
				trace(f + "::" + aref.pos);
			case TAbstract(t, params):
				trace(aref.name + "::" + aref.pos /*.getInfos().min*/ + "::" + params.toString());
		}
	}
	trace(buf.toString());
}

function set_on_generate(?ffname: String) {
	haxe.macro.Context.onGenerate(function(types:Array<Type>){mygenerate(types, ffname);});
}
#end

• TestOnGenerate.hxml:

-main TestOnGenerate
--macro MyOnGenerate.set_on_generate("TestOnGenerate.hx")
#--macro MyOnGenerate.set_on_generate()
#-dce full
#-D analyzer_optimize

Output:

haxe "TestOnGenerate.hxml"
MyOnGenerate.hx:58: Test::#pos(TestOnGenerate.hx:16: lines 16-30)::[]
MyOnGenerate.hx:62: {name: new, isFinal: false, namePos: #pos(TestOnGenerate.hx:22: characters 19-22), isPublic: true, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:22: lines 22-26), kind: FMethod(MethNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TFun([{name: name, t: TInst(<...>,[]), opt: false},{name: x, t: TAbstract(<...>,[]), opt: false},{name: y, t: TAbstract(<...>,[]), opt: false}],TAbstract(Void,[])), expr: #fun}
MyOnGenerate.hx:64: {name: name, isFinal: false, namePos: #pos(TestOnGenerate.hx:18: characters 14-18), isPublic: true, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:18: characters 3-26), kind: FVar(AccNormal,AccNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TInst(String,[]), expr: #fun}
MyOnGenerate.hx:64: {name: x, isFinal: false, namePos: #pos(TestOnGenerate.hx:19: characters 14-15), isPublic: true, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:19: characters 3-22), kind: FVar(AccNormal,AccNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TAbstract(Float,[]), expr: #fun}
MyOnGenerate.hx:64: {name: y, isFinal: false, namePos: #pos(TestOnGenerate.hx:20: characters 14-15), isPublic: true, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:20: characters 3-22), kind: FVar(AccNormal,AccNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TAbstract(Float,[]), expr: #fun}
MyOnGenerate.hx:64: {name: toString, isFinal: false, namePos: #pos(TestOnGenerate.hx:27: characters 19-27), isPublic: true, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:27: lines 27-29), kind: FMethod(MethNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TFun([],TInst(String,[])), expr: #fun}
MyOnGenerate.hx:67: [{name: _count, isFinal: false, namePos: #pos(TestOnGenerate.hx:17: characters 14-20), isPublic: false, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:17: characters 3-30), kind: FVar(AccNormal,AccNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TAbstract(Int,[]), expr: #fun}]
MyOnGenerate.hx:58: TestOnGenerate::#pos(TestOnGenerate.hx:32: lines 32-37)::[]
MyOnGenerate.hx:67: [{name: main, isFinal: false, namePos: #pos(TestOnGenerate.hx:33: characters 21-25), isPublic: false, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:33: lines 33-36), kind: FMethod(MethNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TFun([],TAbstract(Void,[])), expr: #fun}]
MyOnGenerate.hx:58: TestOnGenerate_Fields_::#pos(TestOnGenerate.hx:1: character 1)::[]
MyOnGenerate.hx:67: [{name: _version, isFinal: true, namePos: #pos(TestOnGenerate.hx:1: characters 7-15), isPublic: true, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:1: characters 1-24), kind: FVar(AccNormal,AccNever), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TInst(String,[]), expr: #fun},{name: getVersion, isFinal: false, namePos: #pos(TestOnGenerate.hx:5: characters 10-20), isPublic: true, isAbstract: false, doc:  Get version string. , params: [], pos: #pos(TestOnGenerate.hx:5: lines 5-7), kind: FMethod(MethNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TFun([],TInst(String,[])), expr: #fun}]
MyOnGenerate.hx:84: 
enum Color {
	Red;
	Green;
	Blue;
	RGB(r: Int, g: Int, b: Int);
}

class Test {
	name;
	x;
	y;
	toString;
}

class TestOnGenerate {
}

class TestOnGenerate_Fields_ {
}

[mingodad]

After writing the above I noticed that the types array does come in file/line order except for the global vars/functions that comes at the end in one entry suffixed with _Fields_, would be nice if the var/function global declarations came individually in their file/line order like the other types and maybe move this helper array could be a field like fields.

[mingodad]

Here is an update version of MyOnGenerate.hx that shows how wild it becomes to be able to generate code in declaration order with the actual api:

#if macro
import haxe.macro.Type;
import haxe.macro.Context;

using haxe.macro.PositionTools;
using StringTools;

/**
 * Callback on generating code from context
 */
private function mygenerate(types:Array<Type>, filterFileName: String):Void {
	var buf = new StringBuf();
	var prev_file: String = null;
	var declarations = [];
	var global_declarations: Array<ClassField> = [];
	var last_global_decl_idx = 0;
	var last_global_decl_min = 0;

	function genDocComment(doc: String) {
		if(doc != null) {
			buf.add('\n/**${doc}*/');
		}
	}

	function genCode(this_types:Array<Type>) {
		for (ttype in this_types) {
			var aref = ttype.getParameters()[0].get();
			var apos = Context.getPosInfos(aref.pos);

			/*
				Check if there is any global declaration that preceed this declaration
				and if so gen code for then.
			*/
			if(last_global_decl_min < apos.min) {
				for(i in last_global_decl_idx...global_declarations.length) {
					var vg = global_declarations[i];
					var vg_pos = Context.getPosInfos(vg.pos);
					if(vg_pos.min < apos.min) {
						last_global_decl_idx = i+1;
						//trace(vg);
						genDocComment(vg.doc);
						buf.add('\nglobal ${vg.name};');
					}
					else break;
				}
				last_global_decl_min = apos.min;
			}
			switch (ttype) {
				case TMono(t):
					trace(t + "::" + aref.pos);
				case TEnum(t, params):
					var t_ref = t.get();
					trace(t.toString() + "::" + aref.pos + "::" + params.toString());
					buf.add('\nenum ${t_ref.name} {\n');
					var enumFields = [];
					for (efield in t_ref.constructs) {
						//trace(efield);
						var ebuf = new StringBuf();
						ebuf.add('\t${efield.name}');
						switch(efield.type) {
							case TEnum(_, _): ebuf.add(";\n");
							case TFun(args, _):
								ebuf.add("(");
								for (i in 0...args.length) {
									var arg = args[i];
									if (i > 0)
										ebuf.add(", ");
									var type_name = switch(arg.t) {
										case TAbstract(t, params): t.get().name;
										default:
											throw 'Unsupported paramter ${arg.t}';
											null;
									};
									ebuf.add('${arg.name}: ${type_name}');
								}
								ebuf.add(");\n");
	
							default:
								throw 'Unsupported paramter ${efield.type}';
						}
						enumFields.insert(efield.index, ebuf.toString());
					}
					for(elm in enumFields) buf.add(elm);
					buf.add("}\n");
					//trace(buf.toString());
				case TInst(t, params):
					var t_ref = t.get();
					trace(aref.name + "::" + aref.pos /*.getInfos().min*/ + "::" + params.toString());
					var classFields = t_ref.fields.get();
					buf.add('\nclass ${t_ref.name} {\n');
					//trace(classFields);
					if(t_ref.constructor != null) trace(t_ref.constructor.get());
					for (ifield in classFields) {
						trace(ifield);
						buf.add('\t${ifield.name};\n');
					}
					trace(t_ref.statics.get());
					buf.add("}\n");
					//trace(buf.toString());
				case TType(t, params):
					trace(aref.name + "::" + aref.pos /*.getInfos().min*/ + "::" + params.toString());
				case TFun(args, ret):
					trace(args + "::" + aref.pos + "::" + ret);
				case TAnonymous(a):
					trace(a + "::" + aref.pos);
				case TDynamic(t):
					trace(t + "::" + aref.pos);
				case TLazy(f):
					trace(f + "::" + aref.pos);
				case TAbstract(t, params):
					trace(aref.name + "::" + aref.pos /*.getInfos().min*/ + "::" + params.toString());
			}
		}
	}

	for (atype in types) {
		// trace(atype);
		var aref = atype.getParameters()[0].get();
		var apos = Context.getPosInfos(aref.pos);
		if(filterFileName != null && apos.file != filterFileName) continue;
		//trace(aref.name);
		if(StringTools.endsWith(aref.name, "_Fields_")) {
			switch(atype) {
				case TInst(t, params):
					var t_ref = t.get();
					global_declarations = t_ref.statics.get();
				default:
					throw 'Unsupported paramter ${atype}';
			}
		}
		else declarations.push(atype);

		/*
			After the first pass above to discover if we have global declarations
			we then now do the code generation
		*/
		if(prev_file != null && prev_file != apos.file) {
			genCode(declarations);
			declarations.resize(0); //clear
		}
		//trace(apos);
	}
	/*
		The last file is not managed inside the above loop
		so we do it now if any.
	*/
	if(declarations.length > 0) genCode(declarations);
	trace(buf.toString());
}

function set_on_generate(?ffname: String) {
	haxe.macro.Context.onGenerate(function(types:Array<Type>){mygenerate(types, ffname);});
}
#end

Output:

haxe "TestOnGenerate.hxml"
MyOnGenerate.hx:53: Color::#pos(TestOnGenerate.hx:9: lines 9-14)::[]
MyOnGenerate.hx:88: Test::#pos(TestOnGenerate.hx:16: lines 16-30)::[]
MyOnGenerate.hx:92: {name: new, isFinal: false, namePos: #pos(TestOnGenerate.hx:22: characters 19-22), isPublic: true, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:22: lines 22-26), kind: FMethod(MethNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TFun([{name: name, t: TInst(<...>,[]), opt: false},{name: x, t: TAbstract(<...>,[]), opt: false},{name: y, t: TAbstract(<...>,[]), opt: false}],TAbstract(Void,[])), expr: #fun}
MyOnGenerate.hx:94: {name: name, isFinal: false, namePos: #pos(TestOnGenerate.hx:18: characters 14-18), isPublic: true, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:18: characters 3-26), kind: FVar(AccNormal,AccNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TInst(String,[]), expr: #fun}
MyOnGenerate.hx:94: {name: x, isFinal: false, namePos: #pos(TestOnGenerate.hx:19: characters 14-15), isPublic: true, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:19: characters 3-22), kind: FVar(AccNormal,AccNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TAbstract(Float,[]), expr: #fun}
MyOnGenerate.hx:94: {name: y, isFinal: false, namePos: #pos(TestOnGenerate.hx:20: characters 14-15), isPublic: true, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:20: characters 3-22), kind: FVar(AccNormal,AccNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TAbstract(Float,[]), expr: #fun}
MyOnGenerate.hx:94: {name: toString, isFinal: false, namePos: #pos(TestOnGenerate.hx:27: characters 19-27), isPublic: true, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:27: lines 27-29), kind: FMethod(MethNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TFun([],TInst(String,[])), expr: #fun}
MyOnGenerate.hx:97: [{name: _count, isFinal: false, namePos: #pos(TestOnGenerate.hx:17: characters 14-20), isPublic: false, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:17: characters 3-30), kind: FVar(AccNormal,AccNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TAbstract(Int,[]), expr: #fun}]
MyOnGenerate.hx:88: TestOnGenerate::#pos(TestOnGenerate.hx:32: lines 32-37)::[]
MyOnGenerate.hx:97: [{name: main, isFinal: false, namePos: #pos(TestOnGenerate.hx:33: characters 21-25), isPublic: false, isAbstract: false, doc: null, params: [], pos: #pos(TestOnGenerate.hx:33: lines 33-36), kind: FMethod(MethNormal), meta: {get: #fun, remove: #fun, has: #fun, extract: #fun, add: #fun}, overloads: overloads, isExtern: false, type: TFun([],TAbstract(Void,[])), expr: #fun}]
MyOnGenerate.hx:148: 
global _version;
/** Get version string. */
global getVersion;
enum Color {
	Red;
	Green;
	Blue;
	RGB(r: Int, g: Int, b: Int);
}

class Test {
	name;
	x;
	y;
	toString;
}

class TestOnGenerate {
}

[mingodad]

And looking at the last output I can see that for class static fields and constructor we'll also will need two pass to properly generate code in declaration order.

If somehow we also manage to add the comments to the ast we could write several tools for Haxe code manipulation in Haxe itself, like code formatting, refactoring, documentation extraction, ...

In my opinion ideally we should be able to regenerate the original Haxe code through this api, onGenerate (not always the exact code because of possible optimizations) and with an afterParsing callback definitely we should be able to regenerate the identical source.

[mingodad]

So now I have a clear view of what this api should allow to do:

• Regenerate identically the original source code.

And the Code Cookbook should show a sample that does that.

The sample should also be a test to detect any possible regression.

[markknol]

Hey there! Thanks for figuring this out, it can be a nice to have an example generator in the cookbook as starting point for other people. It would be great if you create a pull request for the article. These are basically markdown pages. More about contributing articles can be found here https://github.com/HaxeFoundation/code-cookbook#creating-articles

Other than that, to me it is not very clear if you have technical questions or just thinking out loud here? (which for me is fine too 😜 )