v4.41.2

operators/column.md

@@ -2,6 +2,8 @@
 
 Returns the column of the matching node. Starts from 1, 0 indicates there was no column data.
 
+Column is the number of characters that precede that node on the line it starts.
+
 ## Returns column of _value_ node
 Given a sample.yml file of:
 ```yaml

usage/convert.md

@@ -36,10 +36,10 @@ will output
 ```yaml
 a: Easy! as one two three
 b:
-    c: 2
+  c: 2
-    d:
+  d:
-        - 3
+    - 3
-        - 4
+    - 4
 ```
 
 ## Encode json: simple
@@ -244,7 +244,7 @@ will output
 this: is a multidoc json file
 ---
 each:
-    - line is a valid json document
+  - line is a valid json document
 ---
 a number: 4
 ```

usage/formatting-expressions.md

@@ -5,6 +5,8 @@
 You can put expressions into `.yq` files, use whitespace and comments to break up complex expressions and explain what's going on.
 
 ## Using expression files and comments
+Note that you can execute the file directly - but make sure you make the expression file executable.
+
 Given a sample.yaml file of:
 ```yaml
 a:
@@ -12,6 +14,8 @@ a:
 ```
 And an 'update.yq' expression file of:
 ```bash
+#! yq
+
 # This is a yq expression that updates the map
 # for several great reasons outlined here.
 
@@ -22,7 +26,7 @@ And an 'update.yq' expression file of:
 ```
 then
 ```bash
-yq --from-file update.yq sample.yml
+./update.yq sample.yaml
 ```
 will output
 ```yaml
@@ -31,8 +35,8 @@ a:
   c: frog
 ```
 
-## Commenting out yq expressions
+## Flags in expression files
-Note that `c` is no longer set to 'frog'.
+You can specify flags on the shebang line, this only works when executing the file directly.
 
 Given a sample.yaml file of:
 ```yaml
@@ -41,6 +45,41 @@ a:
 ```
 And an 'update.yq' expression file of:
 ```bash
+#! yq -oj
+
+# This is a yq expression that updates the map
+# for several great reasons outlined here.
+
+.a.b = "new" # line comment here
+| .a.c = "frog"
+
+# Now good things will happen.
+```
+then
+```bash
+./update.yq sample.yaml
+```
+will output
+```yaml
+{
+  "a": {
+    "b": "new",
+    "c": "frog"
+  }
+}
+```
+
+## Commenting out yq expressions
+Note that `c` is no longer set to 'frog'. In this example we're calling yq directly and passing the expression file into `--from-file`, this is no different from executing the expression file directly.
+
+Given a sample.yaml file of:
+```yaml
+a:
+  b: old
+```
+And an 'update.yq' expression file of:
+```bash
+#! yq
 # This is a yq expression that updates the map
 # for several great reasons outlined here.
 

usage/properties.md

@@ -14,6 +14,8 @@ 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: []
@@ -31,9 +33,76 @@ 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 with array brackets
+Declare the --properties-array-brackets flag to give array paths in brackets (e.g. SpringBoot).
+
+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-array-brackets 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 - 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
 
@@ -44,6 +113,8 @@ 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: []
@@ -61,6 +132,7 @@ person.name = "Mike Wazowski"
 
 # comments on array values appear
 person.pets.0 = cat
+person.pets.1.nested.0 = "list entry"
 person.food.0 = pizza
 ```
 
@@ -72,6 +144,8 @@ 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: []
@@ -85,6 +159,7 @@ will output
 ```properties
 person.name = Mike Wazowski
 person.pets.0 = cat
+person.pets.1.nested.0 = list entry
 person.food.0 = pizza
 ```
 
@@ -98,6 +173,8 @@ 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: []
@@ -115,6 +192,7 @@ person.name = Mike Wazowski
 
 # comments on array values appear
 person.pets.0 = cat
+person.pets.1.nested.0 = list entry
 person.food.0 = pizza
 emptyArray = 
 emptyMap = 
@@ -129,6 +207,7 @@ person.name = Mike Wazowski
 
 # comments on array values appear
 person.pets.0 = cat
+person.pets.1.nested.0 = list entry
 person.food.0 = pizza
 
 ```
@@ -139,14 +218,16 @@ yq -p=props sample.properties
 will output
 ```yaml
 person:
-    # block comments come through
+  # block comments come through
-    # comments on values appear
+  # comments on values appear
-    name: Mike Wazowski
+  name: Mike Wazowski
-    pets:
+  pets:
-        # comments on array values appear
+    # comments on array values appear
-        - cat
+    - cat
-    food:
+    - nested:
-        - pizza
+        - list entry
+  food:
+    - pizza
 ```
 
 ## Decode properties - array should be a map
@@ -163,7 +244,7 @@ yq -p=props '.things |= array_to_map' sample.properties
 will output
 ```yaml
 things:
-    10: mike
+  10: mike
 ```
 
 ## Roundtrip
@@ -175,6 +256,7 @@ person.name = Mike Wazowski
 
 # comments on array values appear
 person.pets.0 = cat
+person.pets.1.nested.0 = list entry
 person.food.0 = pizza
 
 ```
@@ -190,6 +272,7 @@ person.name = Mike Wazowski
 
 # comments on array values appear
 person.pets.0 = dog
+person.pets.1.nested.0 = list entry
 person.food.0 = pizza
 ```