From 9f3822fbaaa44a293c5e7decf03ded0cf094c803 Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Tue, 20 Feb 2024 13:45:29 +1100
Subject: [PATCH] Improving property docs

---
 pkg/yqlib/doc/usage/properties.md | 35 ++++++++++++++++++++++++++++++-
 pkg/yqlib/properties_test.go      | 31 +++++++++++++++++++++++----
 2 files changed, 61 insertions(+), 5 deletions(-)

diff --git a/pkg/yqlib/doc/usage/properties.md b/pkg/yqlib/doc/usage/properties.md
index 6f3835dd..491e014d 100644
--- a/pkg/yqlib/doc/usage/properties.md
+++ b/pkg/yqlib/doc/usage/properties.md
@@ -38,7 +38,7 @@ person.food.0 = pizza
 ```
 
 ## Encode properties with array brackets
-Note that empty arrays and maps are not encoded by default.
+Declare the --properties-array-brackets flag to give array paths in brackets (e.g. SpringBoot).
 
 Given a sample.yml file of:
 ```yaml
@@ -70,6 +70,39 @@ person.pets[1].nested[0] = list entry
 person.food[0] = pizza
 ```
 
+## Encode properties - custom separator
+Use the --properties-customer-separator flag to specify your own key/value separator.
+
+Given a sample.yml file of:
+```yaml
+# block comments come through
+person: # neither do comments on maps
+    name: Mike Wazowski # comments on values appear
+    pets: 
+    - cat # comments on array values appear
+    - nested:
+        - list entry
+    food: [pizza] # comments on arrays do not
+emptyArray: []
+emptyMap: []
+
+```
+then
+```bash
+yq -o=props --properties-customer-separator=" :@ " sample.yml
+```
+will output
+```properties
+# block comments come through
+# comments on values appear
+person.name :@ Mike Wazowski
+
+# comments on array values appear
+person.pets.0 :@ cat
+person.pets.1.nested.0 :@ list entry
+person.food.0 :@ pizza
+```
+
 ## Encode properties: scalar encapsulation
 Note that string values with blank characters in them are encapsulated with double quotes
 
diff --git a/pkg/yqlib/properties_test.go b/pkg/yqlib/properties_test.go
index 892b93be..ed430bd9 100644
--- a/pkg/yqlib/properties_test.go
+++ b/pkg/yqlib/properties_test.go
@@ -82,6 +82,16 @@ person.pets[1].nested[0] = list entry
 person.food[0] = pizza
 `
 
+const expectedPropertiesUnwrappedCustomSeparator = `# block comments come through
+# comments on values appear
+person.name :@ Mike Wazowski
+
+# comments on array values appear
+person.pets.0 :@ cat
+person.pets.1.nested.0 :@ list entry
+person.food.0 :@ pizza
+`
+
 const expectedPropertiesWrapped = `# block comments come through
 # comments on values appear
 person.name = "Mike Wazowski"
@@ -154,11 +164,18 @@ var propertyScenarios = []formatScenario{
 	},
 	{
 		description:    "Encode properties with array brackets",
-		subdescription: "Note that empty arrays and maps are not encoded by default.",
+		subdescription: "Declare the --properties-array-brackets flag to give array paths in brackets (e.g. SpringBoot).",
 		input:          samplePropertiesYaml,
 		expected:       expectedPropertiesUnwrappedArrayBrackets,
 		scenarioType:   "encode-array-brackets",
 	},
+	{
+		description:    "Encode properties - custom separator",
+		subdescription: "Use the --properties-customer-separator flag to specify your own key/value separator.",
+		input:          samplePropertiesYaml,
+		expected:       expectedPropertiesUnwrappedCustomSeparator,
+		scenarioType:   "encode-custom-separator",
+	},
 	{
 		description:    "Encode properties: scalar encapsulation",
 		subdescription: "Note that string values with blank characters in them are encapsulated with double quotes",
@@ -294,15 +311,19 @@ func documentUnwrappedEncodePropertyScenario(w *bufio.Writer, s formatScenario)
 	expression := s.expression
 	prefs := NewDefaultPropertiesPreferences()
 	useArrayBracketsFlag := ""
+	useCustomSeparatorFlag := ""
 	if s.scenarioType == "encode-array-brackets" {
 		useArrayBracketsFlag = " --properties-array-brackets"
 		prefs.UseArrayBrackets = true
+	} else if s.scenarioType == "encode-custom-separator" {
+		prefs.KeyValueSeparator = " :@ "
+		useCustomSeparatorFlag = ` --properties-customer-separator=" :@ "`
 	}
 
 	if expression != "" {
-		writeOrPanic(w, fmt.Sprintf("```bash\nyq -o=props%v '%v' sample.yml\n```\n", useArrayBracketsFlag, expression))
+		writeOrPanic(w, fmt.Sprintf("```bash\nyq -o=props%v%v '%v' sample.yml\n```\n", useArrayBracketsFlag, useCustomSeparatorFlag, expression))
 	} else {
-		writeOrPanic(w, fmt.Sprintf("```bash\nyq -o=props%v sample.yml\n```\n", useArrayBracketsFlag))
+		writeOrPanic(w, fmt.Sprintf("```bash\nyq -o=props%v%v sample.yml\n```\n", useArrayBracketsFlag, useCustomSeparatorFlag))
 	}
 	writeOrPanic(w, "will output\n")
 
@@ -390,7 +411,7 @@ func documentPropertyScenario(_ *testing.T, w *bufio.Writer, i interface{}) {
 		return
 	}
 	switch s.scenarioType {
-	case "", "encode-array-brackets":
+	case "", "encode-array-brackets", "encode-custom-separator":
 		documentUnwrappedEncodePropertyScenario(w, s)
 	case "decode":
 		documentDecodePropertyScenario(w, s)
@@ -415,6 +436,8 @@ func TestPropertyScenarios(t *testing.T) {
 			test.AssertResultWithContext(t, s.expected, mustProcessFormatScenario(s, NewYamlDecoder(ConfiguredYamlPreferences), NewPropertiesEncoder(false, ConfiguredPropertiesPreferences)), s.description)
 		case "encode-array-brackets":
 			test.AssertResultWithContext(t, s.expected, mustProcessFormatScenario(s, NewYamlDecoder(ConfiguredYamlPreferences), NewPropertiesEncoder(true, PropertiesPreferences{KeyValueSeparator: " = ", UseArrayBrackets: true})), s.description)
+		case "encode-custom-separator":
+			test.AssertResultWithContext(t, s.expected, mustProcessFormatScenario(s, NewYamlDecoder(ConfiguredYamlPreferences), NewPropertiesEncoder(true, PropertiesPreferences{KeyValueSeparator: " :@ "})), s.description)
 		case "roundtrip":
 			test.AssertResultWithContext(t, s.expected, mustProcessFormatScenario(s, NewPropertiesDecoder(), NewPropertiesEncoder(true, ConfiguredPropertiesPreferences)), s.description)