Add continuation function support during element creation

Introduced the Element.Create function and CreateContinuation
type.

etree.go

@@ -751,13 +751,38 @@ func (e *Element) findTermCharDataIndex(start int) int {
 }
 
 // CreateElement creates a new element with the specified tag (i.e., name) and
-// adds it as the last child token of this element. The tag may include a
+// adds it as the last child token of the element e. The tag may include a
 // prefix followed by a colon.
 func (e *Element) CreateElement(tag string) *Element {
 	space, stag := spaceDecompose(tag)
 	return newElement(space, stag, e)
 }
 
+// CreateContinuation is a continuation-passing interface for building
+// XML documents in a more nested manner. See the description of its
+// use in the Element Create function.
+type CreateContinuation func(e *Element)
+
+// Create creates a new element with the specified tag (i.e., name) and adds
+// it as the last child token of the element e. The tag may include a prefix
+// followed by a colon. After creating the element, Create calls the
+// continuation function to perform additional actions on the created child
+// element.
+//
+// This method of creating elements is useful when building nested XML
+// document from code. For example:
+//
+//	doc.Create("organization", func(e *Element) {
+//		e.Create("person", func(e *Element) {
+//			e.CreateAttr("name", "Mary")
+//			e.CreateAttr("age", "30")
+//			e.CreateAttr("hair", "brown")
+//		})
+//	})
+func (e *Element) Create(tag string, f CreateContinuation) {
+	f(e.CreateElement(tag))
+}
+
 // AddChild adds the token 't' as the last child of the element. If token 't'
 // was already the child of another element, it is first removed from its
 // parent element.

etree_test.go

@@ -1629,3 +1629,51 @@ func TestSiblingElement(t *testing.T) {
 		}
 	}
 }
+
+func TestContinuations(t *testing.T) {
+	doc := NewDocument()
+	doc.Create("root", func(e *Element) {
+		e.Create("child1", func(e *Element) {
+			e.Create("grandchild1", func(e *Element) {
+				e.CreateAttr("attr1", "1")
+				e.CreateAttr("attr2", "2")
+			})
+			e.Create("grandchild2", func(e *Element) {
+				e.CreateAttr("attr1", "3")
+				e.CreateAttr("attr2", "4")
+			})
+		})
+		e.Create("child2", func(e *Element) {
+			e.Create("grandchild1", func(e *Element) {
+				e.CreateAttr("attr1", "5")
+				e.CreateAttr("attr2", "6")
+			})
+			e.Create("grandchild2", func(e *Element) {
+				e.CreateAttr("attr1", "7")
+				e.CreateAttr("attr2", "8")
+			})
+		})
+	})
+	doc.IndentTabs()
+
+	// Serialize the document to a string
+	s, err := doc.WriteToString()
+	if err != nil {
+		t.Error("etree: failed to serialize document")
+	}
+
+	// Make sure the serialized XML matches expectation.
+	expected := `<root>
+	<child1>
+		<grandchild1 attr1="1" attr2="2"/>
+		<grandchild2 attr1="3" attr2="4"/>
+	</child1>
+	<child2>
+		<grandchild1 attr1="5" attr2="6"/>
+		<grandchild2 attr1="7" attr2="8"/>
+	</child2>
+</root>
+`
+
+	checkStrEq(t, s, expected)
+}