refactoring doc gen

examples/mike.xml

@@ -1,11 +1,4 @@
   <?xml version="1.0" encoding="UTF-8"?>
-  <!-- osm-->
-  <osm version="0.6" generator="CGImap 0.0.2">
-  <!-- bounds-->
-   <bounds minlat="54.0889580" minlon="12.2487570" maxlat="54.0913900" maxlon="12.2524800">
-   <!-- great -->
-   cool
-   </bounds>
-   <foo>bar</foo>
-   <foo>bar23</foo>
-  </osm>
+  <cat>3f</cat>
+  <dog>meow:as</dog>
+  <dog3>true</dog3>

examples/mike2.xml

@@ -0,0 +1,11 @@
+  <?xml version="1.0" encoding="UTF-8"?>
+  <!-- osm-->
+  <osm version="0.6" generator="CGImap 0.0.2">
+  <!-- bounds-->
+   <bounds minlat="54.0889580" minlon="12.2487570" maxlat="54.0913900" maxlon="12.2524800">
+   <!-- great -->
+   cool
+   </bounds>
+   <foo>ba2234r</foo>
+   <foo>bar2234233</foo>
+  </osm>

pkg/yqlib/decode_xml_test.go

@@ -0,0 +1,106 @@
+package yqlib
+
+import (
+	"bufio"
+	"bytes"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/mikefarah/yq/v4/test"
+	yaml "gopkg.in/yaml.v3"
+)
+
+func decodeXml(t *testing.T, xml string) *CandidateNode {
+	decoder := NewXmlDecoder("+", "+content")
+
+	decoder.Init(strings.NewReader(xml))
+
+	node := &yaml.Node{}
+	err := decoder.Decode(node)
+	if err != nil {
+		t.Error(err, "fail to decode", xml)
+	}
+	return &CandidateNode{Node: node}
+}
+
+type xmlScenario struct {
+	inputXml       string
+	expected       string
+	description    string
+	subdescription string
+	skipDoc        bool
+}
+
+var xmlScenarios = []xmlScenario{
+	{
+		description: "Parse xml: simple",
+		inputXml:    "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<cat>meow</cat>",
+		expected:    "D0, P[], (doc)::cat: meow\n",
+	},
+	{
+		description:    "Parse xml: array",
+		subdescription: "Consecutive nodes with identical xml names are assumed to be arrays.",
+		inputXml:       "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<animal>1</animal><animal>2</animal>",
+		expected:       "D0, P[], (doc)::animal:\n    - \"1\"\n    - \"2\"\n",
+	},
+	{
+		description:    "Parse xml: attributes",
+		subdescription: "Attributes are converted to fields, with the attribute prefix.",
+		inputXml:       "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<cat legs=\"4\"><legs>7</legs></cat>",
+		expected:       "D0, P[], (doc)::cat:\n    +legs: \"4\"\n    legs: \"7\"\n",
+	},
+	{
+		description:    "Parse xml: attributes with content",
+		subdescription: "Content is added as a field, using the content name",
+		inputXml:       "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<cat legs=\"4\">meow</cat>",
+		expected:       "D0, P[], (doc)::cat:\n    +content: meow\n    +legs: \"4\"\n",
+	},
+}
+
+func testXmlScenario(t *testing.T, s *xmlScenario) {
+	var actual = resultToString(t, decodeXml(t, s.inputXml))
+	test.AssertResult(t, s.expected, actual)
+}
+
+func documentXmlScenario(t *testing.T, w *bufio.Writer, i interface{}) {
+	s := i.(xmlScenario)
+
+	if s.skipDoc {
+		return
+	}
+	writeOrPanic(w, fmt.Sprintf("## %v\n", s.description))
+
+	if s.subdescription != "" {
+		writeOrPanic(w, s.subdescription)
+		writeOrPanic(w, "\n\n")
+	}
+
+	writeOrPanic(w, "Given a sample.xml file of:\n")
+	writeOrPanic(w, fmt.Sprintf("```xml\n%v\n```\n", s.inputXml))
+
+	writeOrPanic(w, "then\n")
+	writeOrPanic(w, "```bash\nyq e sample.xml\n```\n")
+	writeOrPanic(w, "will output\n")
+
+	var output bytes.Buffer
+	printer := NewPrinterWithSingleWriter(bufio.NewWriter(&output), YamlOutputFormat, true, false, 2, true)
+
+	node := decodeXml(t, s.inputXml)
+
+	printer.PrintResults(node.AsList())
+
+	writeOrPanic(w, fmt.Sprintf("```yaml\n%v```\n\n", output.String()))
+
+}
+
+func TestXmlScenarios(t *testing.T) {
+	for _, tt := range xmlScenarios {
+		testXmlScenario(t, &tt)
+	}
+	genericScenarios := make([]interface{}, len(xmlScenarios))
+	for i, s := range xmlScenarios {
+		genericScenarios[i] = s
+	}
+	documentScenarios(t, "usage", "xml", genericScenarios, documentXmlScenario)
+}

pkg/yqlib/doc/usage/headers/xml.md

@@ -0,0 +1,12 @@
+# XML
+
+At the moment, `yq` only supports decoding `xml` (into one of the other supported output formats).
+
+As yaml does not have the concept of attributes, these are converted to regular fields with a prefix to prevent clobbering. Consecutive xml nodes with the same name are assumed to be arrays.
+
+All values in XML are assumed to be strings - but you can use `from_yaml` to parse them into their correct types:
+
+
+```
+yq e -p=xml '.myNumberField |= from_yaml' my.xml
+```

pkg/yqlib/doc/usage/xml.md

@@ -0,0 +1,80 @@
+# XML
+
+At the moment, `yq` only supports decoding `xml` (into one of the other supported output formats).
+
+As yaml does not have the concept of attributes, these are converted to regular fields with a prefix to prevent clobbering. Consecutive xml nodes with the same name are assumed to be arrays.
+
+All values in XML are assumed to be strings.
+
+## Parse xml: simple
+Given a sample.xml file of:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<cat>meow</cat>
+```
+then
+```bash
+yq e sample.xml
+```
+will output
+```yaml
+cat: meow
+```
+
+## Parse xml: array
+Consecutive nodes with identical xml names are assumed to be arrays.
+
+Given a sample.xml file of:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<animal>1</animal><animal>2</animal>
+```
+then
+```bash
+yq e sample.xml
+```
+will output
+```yaml
+animal:
+  - "1"
+  - "2"
+```
+
+## Parse xml: attributes
+Attributes are converted to fields, with the attribute prefix.
+
+Given a sample.xml file of:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<cat legs="4"><legs>7</legs></cat>
+```
+then
+```bash
+yq e sample.xml
+```
+will output
+```yaml
+cat:
+  +legs: "4"
+  legs: "7"
+```
+
+## Parse xml: attributes with content
+Content is added as a field, using the content name
+
+Given a sample.xml file of:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<cat legs="4">meow</cat>
+```
+then
+```bash
+yq e sample.xml
+```
+will output
+```yaml
+cat:
+  +content: meow
+  +legs: "4"
+```
+

pkg/yqlib/operator_add_test.go

@@ -150,5 +150,5 @@ func TestAddOperatorScenarios(t *testing.T) {
 	for _, tt := range addOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	documentScenarios(t, "add", addOperatorScenarios)
+	documentOperatorScenarios(t, "add", addOperatorScenarios)
 }

pkg/yqlib/operator_alternative_test.go

@@ -91,5 +91,5 @@ func TestAlternativeOperatorScenarios(t *testing.T) {
 	for _, tt := range alternativeOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	documentScenarios(t, "alternative-default-value", alternativeOperatorScenarios)
+	documentOperatorScenarios(t, "alternative-default-value", alternativeOperatorScenarios)
 }

pkg/yqlib/operator_anchors_aliases_test.go

@@ -233,5 +233,5 @@ func TestAnchorAliasOperatorScenarios(t *testing.T) {
 	for _, tt := range anchorOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	documentScenarios(t, "anchor-and-alias-operators", anchorOperatorScenarios)
+	documentOperatorScenarios(t, "anchor-and-alias-operators", anchorOperatorScenarios)
 }

pkg/yqlib/operator_assign_test.go

@@ -178,5 +178,5 @@ func TestAssignOperatorScenarios(t *testing.T) {
 	for _, tt := range assignOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	documentScenarios(t, "assign-update", assignOperatorScenarios)
+	documentOperatorScenarios(t, "assign-update", assignOperatorScenarios)
 }

pkg/yqlib/operator_booleans_test.go

@@ -229,5 +229,5 @@ func TestBooleanOperatorScenarios(t *testing.T) {
 	for _, tt := range booleanOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	documentScenarios(t, "boolean-operators", booleanOperatorScenarios)
+	documentOperatorScenarios(t, "boolean-operators", booleanOperatorScenarios)
 }

pkg/yqlib/operator_collect_object_test.go

@@ -160,5 +160,5 @@ func TestCollectObjectOperatorScenarios(t *testing.T) {
 	for _, tt := range collectObjectOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	documentScenarios(t, "create-collect-into-object", collectObjectOperatorScenarios)
+	documentOperatorScenarios(t, "create-collect-into-object", collectObjectOperatorScenarios)
 }

pkg/yqlib/operator_collect_test.go

@@ -108,5 +108,5 @@ func TestCollectOperatorScenarios(t *testing.T) {
 	for _, tt := range collectOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	documentScenarios(t, "collect-into-array", collectOperatorScenarios)
+	documentOperatorScenarios(t, "collect-into-array", collectOperatorScenarios)
 }

pkg/yqlib/operator_comments_test.go

@@ -136,5 +136,5 @@ func TestCommentOperatorScenarios(t *testing.T) {
 	for _, tt := range commentOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	documentScenarios(t, "comment-operators", commentOperatorScenarios)
+	documentOperatorScenarios(t, "comment-operators", commentOperatorScenarios)
 }

pkg/yqlib/operator_contains_test.go

@@ -78,5 +78,5 @@ func TestContainsOperatorScenarios(t *testing.T) {
 	for _, tt := range containsOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	documentScenarios(t, "contains", containsOperatorScenarios)
+	documentOperatorScenarios(t, "contains", containsOperatorScenarios)
 }

pkg/yqlib/operator_delete_test.go

@@ -171,5 +171,5 @@ func TestDeleteOperatorScenarios(t *testing.T) {
 	for _, tt := range deleteOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	documentScenarios(t, "delete", deleteOperatorScenarios)
+	documentOperatorScenarios(t, "delete", deleteOperatorScenarios)
 }