added haxe.Template specification

std/haxe/Template.hx

@@ -42,6 +42,13 @@ private typedef ExprToken = {
 	var p : String;
 }
 
+/**
+	Template provides a basic templating mechanism to replace values in a source
+	String, and to have some basic logic.
+	
+	A complete documentation of the supported syntax is available at:
+	http://haxe.org/doc/cross/template
+**/
 class Template {
 
 	static var splitter = ~/(::[A-Za-z0-9_ ()&|!+=\/><*."-]+::|\$\$([A-Za-z0-9_-]+)\()/;
@@ -50,6 +57,10 @@ class Template {
 	static var expr_int = ~/^[0-9]+$/;
 	static var expr_float = ~/^([+-]?)(?=\d|,\d)\d*(,\d*)?([Ee]([+-]?\d+))?$/;
 
+	/**
+		Global replacements which are used across all Template instances. This
+		has lower priority than the context argument of execute().
+	**/
 	public static var globals : Dynamic = {};
 
 	var expr : TemplateExpr;
@@ -58,6 +69,16 @@ class Template {
 	var stack : List<Dynamic>;
 	var buf : StringBuf;
 
+	/**
+		Creates a new Template instance from [str].
+		
+		[str] is parsed into tokens, which are stored for internal use. This
+		means that multiple execute() operations on a single Template instance
+		are more efficient than one execute() operations on multiple Template
+		instances.
+		
+		If [str] is null, the result is unspecified.
+	**/
 	public function new( str : String ) {
 		var tokens = parseTokens(str);
 		expr = parseBlock(tokens);
@@ -65,7 +86,23 @@ class Template {
 			throw "Unexpected '"+tokens.first().s+"'";
 	}
 
-	public function execute( context : Dynamic, ?macros : Dynamic ) {
+	/**
+		Executes [this] Template, taking into account [context] for
+		replacements and [macros] for callback functions.
+		
+		If [context] has a field 'name', its value replaces all occurrences of
+		::name:: in the Template. Otherwise Template.globals is checked instead,
+		If 'name' is not a field of that either, ::name:: is replaced with null.
+		
+		If [macros] has a field 'name', all occurrences of $$name(args) are
+		replaced with the result of calling that field. The first argument is
+		always the the resolve() method, followed by the given arguments.
+		If [macros] has no such field, the result is unspecified.
+		
+		If [context] is null, the result is unspecified. If [macros] is null,
+		no macros are used.
+	**/
+	public function execute( context : Dynamic, ?macros : Dynamic ):String {
 		this.macros = if( macros == null ) {} else macros;
 		this.context = context;
 		stack = new List();

tests/unit/unitstd/haxe/Template.unit.hx

@@ -0,0 +1,21 @@
+// normal
+var tpl = new haxe.Template("My name is <strong>::name::</strong> and I'm <em>::age::</em> years old.");
+var output = tpl.execute( { name : "John", age : 33 } );
+output == "My name is <strong>John</strong> and I'm <em>33</em> years old.";
+
+// not existent
+var output2 = tpl.execute( { } );
+output2 == "My name is <strong>null</strong> and I'm <em>null</em> years old.";
+
+// globals
+haxe.Template.globals = { name : "John", age : 33 };
+var output2 = tpl.execute( { } );
+output2 == "My name is <strong>John</strong> and I'm <em>33</em> years old.";
+
+// macros
+function myfun( resolve : String -> Dynamic, title : String, p : Int ) {
+	return "["+title+"="+(p * resolve("mult"))+"]";
+}
+var t1 = new haxe.Template("Call macro : $$myfun(Hello,::param::)");
+var str = t1.execute({ param : 55, mult : 2 },{ myfun : myfun });
+str == "Call macro : [Hello=110]";