Merge pull request #22 from mmonterroca/fix/pr20-code-review

fix: address PR #20 code review comments

Author: mmonterroca

README.md

@@ -173,7 +173,7 @@ func main() {
 
 ### More Examples
 
-See the [`examples/`](examples/) directory for 14 comprehensive examples:
+See the [`examples/`](examples/) directory for 15 comprehensive examples:
 
 - **[01_basic](examples/01_basic/)** - Simple document with builder pattern
 - **[02_intermediate](examples/02_intermediate/)** - Professional product catalog

RELEASE_NOTES_v2.3.0.md

@@ -70,65 +70,67 @@ import (
 
 doc := docx.NewDocument()
 para, _ := doc.AddParagraph()
-para.AddRun().SetText("Hello {{name}}, welcome to {{company}}!")
+run, _ := para.AddRun()
+run.SetText("Hello {{name}}, welcome to {{company}}!")
 
-data := map[string]string{
+data := template.MergeData{
     "name":    "John",
     "company": "Acme Corp",
 }
 
-result, _ := template.MergeTemplate(doc, data, nil)
-result.SaveAs("output.docx")
+err := template.MergeTemplate(doc, data)
+// MergeTemplate modifies the document in place
+doc.SaveAs("output.docx")
 ```
 
 ### External Word Template with MERGEFIELDs
 
 ```go
 doc, _ := docx.OpenDocument("template.docx")
 
-opts := &template.MergeOptions{
+opts := template.MergeOptions{
     OpenDelimiter:  "«",
     CloseDelimiter: "»",
 }
 
-data := map[string]string{
+data := template.MergeData{
     "Contact_FullName": "Jane Doe",
     "Account_Name":     "Acme Corp",
 }
 
-result, _ := template.MergeTemplate(doc, data, opts)
-result.SaveAs("merged_output.docx")
+err := template.MergeTemplate(doc, data, opts)
+// MergeTemplate modifies the document in place
+doc.SaveAs("merged_output.docx")
 ```
 
 ### Batch Merge
 
 ```go
-doc, _ := docx.OpenDocument("invoice_template.docx")
-
-records := []map[string]string{
+records := []template.MergeData{
     {"name": "John Smith", "amount": "$1,500.00"},
     {"name": "Alice Johnson", "amount": "$2,300.00"},
 }
 
-results, _ := template.BatchMerge("invoice_template.docx", records, nil)
-for i, result := range results {
-    result.SaveAs(fmt.Sprintf("invoice_%d.docx", i+1))
+for i, data := range records {
+    doc, _ := docx.OpenDocument("invoice_template.docx")
+    template.MergeTemplate(doc, data)
+    doc.SaveAs(fmt.Sprintf("invoice_%d.docx", i+1))
 }
 ```
 
 ## Files Added
 
-- `pkg/template/engine.go` — Main template engine
+- `pkg/template/doc.go` — Package documentation
 - `pkg/template/merge.go` — Core merge logic
 - `pkg/template/merge_test.go` — Merge tests
 - `pkg/template/placeholder.go` — Placeholder detection
 - `pkg/template/placeholder_test.go` — Placeholder tests
 - `pkg/template/consolidate.go` — Run consolidation
 - `pkg/template/consolidate_test.go` — Consolidation tests
-- `pkg/template/validate.go` — Template validation
-- `pkg/template/validate_test.go` — Validation tests
+- `pkg/template/format.go` — Run formatting comparison helper
+- `pkg/template/options.go` — MergeData, MergeOptions, ValidationError types
 - `pkg/template/walk.go` — Document traversal
-- `pkg/template/batch.go` — Batch merge support
+- `pkg/template/integration_test.go` — Integration tests
 - `examples/14_mail_merge/main.go` — Programmatic template example
 - `examples/15_external_template/main.go` — External Word template example
 

docs/V2_DESIGN.md

@@ -1350,9 +1350,5 @@ See [CREDITS.md](../CREDITS.md) for complete project history.
 - ✅ Advanced tables: Complete (merging, nesting, 8 styles, proper border serialization)
 - ✅ Theme system: Complete (7 preset themes, custom theme support)
 - ✅ Document reading: Complete (round-trip with style/hyperlink/image preservation)
-- ✅ Documentation: Comprehensive (13 working examples, full API guide)
+- ✅ Documentation: Comprehensive (15 working examples, full API guide)
 - ✅ All 12 phases complete
-
-```
-
-```

examples/15_external_template/main.go

@@ -43,18 +43,22 @@ func main() {
 	// -------------------------------------------------------------------------
 	// Step 2: Configure custom delimiters for Word-style merge fields
 	// -------------------------------------------------------------------------
+	fmt.Println("Step 2: Configuring custom delimiters for Word-style merge fields...")
 	// Microsoft Word uses « » (guillemet) delimiters for mail merge fields.
 	// Our template engine supports custom delimiters through MergeOptions.
 	opts := template.MergeOptions{
 		OpenDelimiter:  "«",
 		CloseDelimiter: "»",
 		StrictMode:     true, // require all placeholders to have data
 	}
+	fmt.Println("  Delimiters: « »")
+	fmt.Println("  Strict mode: enabled")
+	fmt.Println()
 
 	// -------------------------------------------------------------------------
 	// Step 3: Inspect the template — discover all placeholders
 	// -------------------------------------------------------------------------
-	fmt.Println("Step 2: Inspecting template placeholders...")
+	fmt.Println("Step 3: Inspecting template placeholders...")
 
 	// Use FindPlaceholdersCustom with a pattern matching « » delimiters
 	pattern := buildGuillemetsPattern()
@@ -89,7 +93,7 @@ func main() {
 	// -------------------------------------------------------------------------
 	// Step 4: Prepare merge data and validate
 	// -------------------------------------------------------------------------
-	fmt.Println("Step 3: Validating template against data...")
+	fmt.Println("Step 4: Validating template against data...")
 
 	data := template.MergeData{
 		// Organization info
@@ -142,7 +146,7 @@ func main() {
 	// -------------------------------------------------------------------------
 	// Step 5: Merge the template to produce a personalized letter
 	// -------------------------------------------------------------------------
-	fmt.Println("Step 4: Merging template with data...")
+	fmt.Println("Step 5: Merging template with data...")
 
 	if err := template.MergeTemplate(doc, data, opts); err != nil {
 		log.Fatalf("Merge failed: %v", err)
@@ -157,7 +161,7 @@ func main() {
 	// -------------------------------------------------------------------------
 	// Step 6: Verify — reopen the merged document and print its content
 	// -------------------------------------------------------------------------
-	fmt.Println("Step 5: Verifying merged document content...")
+	fmt.Println("Step 6: Verifying merged document content...")
 
 	merged, err := docx.OpenDocument(outputPath)
 	if err != nil {
@@ -175,7 +179,7 @@ func main() {
 	// -------------------------------------------------------------------------
 	// Step 7: Batch merge — send reminders to multiple contacts
 	// -------------------------------------------------------------------------
-	fmt.Println("Step 6: Batch merge for multiple contacts...")
+	fmt.Println("Step 7: Batch merge for multiple contacts...")
 
 	contacts := []template.MergeData{
 		{

examples/README.md

@@ -269,7 +269,7 @@ Run the included test script to verify all examples compile:
 ./test_all.sh
 ```
 
-This will test all 14 working examples and report results.
+This will test all 15 working examples and report results.
 
 ---
 

pkg/template/placeholder.go

@@ -94,6 +94,11 @@ func scanParagraph(para domain.Paragraph, pattern *regexp.Regexp, ctx paragraphC
 		matches := pattern.FindAllStringSubmatchIndex(text, -1)
 
 		for _, match := range matches {
+			// Ensure there is at least one capturing group before indexing.
+			if len(match) < 4 {
+				// Pattern does not provide the expected capturing group; skip this match.
+				continue
+			}
 			// match[0:2] is full match, match[2:4] is first capture group
 			fullMatch := text[match[0]:match[1]]
 			name := text[match[2]:match[3]]