Merge branch 'master' into xml-proc-inst

Updated XML acceptance tests with proc inst and directives
Added nix installation instructions
2026-08-24 16:39:58 +08:00 · 2022-10-24 09:57:50 +11:00 · 2022-10-24 09:54:39 +11:00 · 2022-10-24 09:42:22 +11:00 · 2022-10-23 14:59:21 +11:00 · 2022-10-23 14:58:04 +11:00
150 changed files with 3251 additions and 685 deletions
@@ -60,3 +60,23 @@ jobs:
            -t "${IMAGE_NAME}:4" \
            -t "${IMAGE_NAME}:latest" \
            .
+          
+          cd github-action
+          docker buildx build \
+            --label "org.opencontainers.image.authors=https://github.com/mikefarah/yq/graphs/contributors" \
+            --label "org.opencontainers.image.created=$(date --rfc-3339=seconds)" \
+            --label "org.opencontainers.image.description=yq is a portable command-line YAML processor" \
+            --label "org.opencontainers.image.documentation=https://mikefarah.gitbook.io/yq/" \
+            --label "org.opencontainers.image.licenses=MIT" \
+            --label "org.opencontainers.image.revision=$(git rev-parse HEAD)" \
+            --label "org.opencontainers.image.source=https://github.com/mikefarah/yq" \
+            --label "org.opencontainers.image.title=yq" \
+            --label "org.opencontainers.image.url=https://mikefarah.gitbook.io/yq/" \
+            --label "org.opencontainers.image.version=${IMAGE_VERSION}" \
+            --platform "${PLATFORMS}" \
+            --pull \
+            --push \
+            -t "${IMAGE_NAME}:${IMAGE_VERSION}-githubaction" \
+            -t "${IMAGE_NAME}:4-githubaction" \
+            -t "${IMAGE_NAME}:latest-githubaction" \
+            .
@@ -10,10 +10,10 @@ jobs:
    runs-on: ubuntu-latest
    steps:

-    - name: Set up Go 1.18
+    - name: Set up Go 1.19
      uses: actions/setup-go@v3
      with:
-        go-version: 1.18
+        go-version: 1.19
      id: go

    - name: Check out code into the Go module directory
@@ -12,7 +12,8 @@ jobs:
      - uses: actions/checkout@v3
      - uses: actions/setup-go@v3
        with:
-          go-version: '^1.18'
+          go-version: '^1.19'
+          check-latest: true
      - name: Compile man page markup
        id: gen-man-page-md
        run: |
@@ -1,5 +1,8 @@
 name: Test Yq Action
-on: [push]
+on: 
+  push:
+  workflow_dispatch:
+
 permissions:
  contents: read

@@ -12,11 +15,14 @@ jobs:
    steps:
      - uses: actions/checkout@v3
      - name: Get test
+        id: get_value
        uses: mikefarah/yq@master
        with:
-          cmd: yq eval '.a' examples/sample.yaml
+          cmd: yq '.test' examples/multiline-text.yaml
+      - name: Multiline test
+        run: echo "### It was [${{ steps.get_value.outputs.result }}]" >> $GITHUB_STEP_SUMMARY
      - name: Write inplace test
        id: lookupSdkVersion
        uses: mikefarah/yq@master
        with:
-          cmd: yq eval -i '.b.c = 5' examples/sample.yaml
+          cmd: yq -i '.b.c = 5' examples/sample.yaml
@@ -56,4 +56,9 @@ _build
 debian/files

 # intellij
-/.idea
+/.idea
+
+# vscode
+.vscode
+
+yq3
@@ -1,4 +1,4 @@
-FROM golang:1.18.3 as builder
+FROM golang:1.19.2 as builder

 WORKDIR /go/src/mikefarah/yq

@@ -1,4 +1,4 @@
-FROM golang:1.18.3
+FROM golang:1.19.2

 COPY scripts/devtools.sh /opt/devtools.sh

@@ -3,31 +3,10 @@
 ![Build](https://github.com/mikefarah/yq/workflows/Build/badge.svg)  ![Docker Pulls](https://img.shields.io/docker/pulls/mikefarah/yq.svg) ![Github Releases (by Release)](https://img.shields.io/github/downloads/mikefarah/yq/total.svg) ![Go Report](https://goreportcard.com/badge/github.com/mikefarah/yq) ![CodeQL](https://github.com/mikefarah/yq/workflows/CodeQL/badge.svg)


-a lightweight and portable command-line YAML, JSON and XML processor. `yq` uses [jq](https://github.com/stedolan/jq) like syntax but works with yaml files as well as json and xml. It doesn't yet support everything `jq` does - but it does support the most common operations and functions, and more is being added continuously.
+a lightweight and portable command-line YAML, JSON and XML processor. `yq` uses [jq](https://github.com/stedolan/jq) like syntax but works with yaml files as well as json, xml, properties, csv and tsv. It doesn't yet support everything `jq` does - but it does support the most common operations and functions, and more is being added continuously.

 yq is written in go - so you can download a dependency free binary for your platform and you are good to go! If you prefer there are a variety of package managers that can be used as well as Docker and Podman, all listed below.

-## Notice for v4.x versions prior to 4.18.1
-Since 4.18.1, yq's 'eval/e' command is the _default_ command and no longer needs to be specified.
-
-Older versions will still need to specify 'eval/e'.
-
-Similarly, '-' is no longer required as a filename to read from STDIN (unless reading from one or more files).
-
-TLDR:
-
-Prior to 4.18.1 
-```bash
-yq e '.cool' - < file.yaml
-```
-
-4.18+ 
-```bash
-yq '.cool' < file.yaml
-```
-
-When merging multiple files together, `eval-all/ea` is still required to tell `yq` to run the expression against all the document at once.
-
 ## Quick Usage Guide

 Read a value:
@@ -73,6 +52,8 @@ yq -P sample.json

 See the [documentation](https://mikefarah.gitbook.io/yq/) for more examples.

+Take a look at the discussions for [common questions](https://github.com/mikefarah/yq/discussions/categories/q-a), and [cool ideas](https://github.com/mikefarah/yq/discussions/categories/show-and-tell)
+
 ## Install

 ### [Download the latest binary](https://github.com/mikefarah/yq/releases/latest)
@@ -207,12 +188,27 @@ RUN apk add --no-cache tzdata
 USER yq
 ```

+#### Podman with SELinux
+
+If you are using podman with SELinux, you will need to set the shared volume flag `:z` on the volume mount:
+
+```
+-v "${PWD}":/workdir:z
+```
+
 ### GitHub Action
 ```
  - name: Set foobar to cool
    uses: mikefarah/yq@master
    with:
      cmd: yq -i '.foo.bar = "cool"' 'config.yml'
+  - name: Get an entry with a variable that might contain dots or spaces
+    id: get_username
+    uses: mikefarah/yq@master
+    with:
+      cmd: yq '.all.children.["${{ matrix.ip_address }}"].username' ops/inventories/production.yml
+  - name: Reuse a variable obtained in another step
+    run: echo ${{ steps.get_username.outputs.result }}
 ```

 See https://mikefarah.gitbook.io/yq/usage/github-action for more.
@@ -225,7 +221,17 @@ go install github.com/mikefarah/yq/v4@latest
 ## Community Supported Installation methods
 As these are supported by the community :heart: - however, they may be out of date with the officially supported releases.

-# Webi
+
+### Nix
+
+```
+nix profile install nixpkgs#yq-go
+```
+
+See [here](https://search.nixos.org/packages?channel=unstable&show=yq-go&from=0&size=50&sort=relevance&type=packages&query=yq-go)
+
+
+### Webi

 ```
 webi yq
@@ -248,6 +254,13 @@ choco install yq
 ```
 Supported by @chillum (https://chocolatey.org/packages/yq)

+and
+
+### Winget
+winget install yq
+
+https://winget.run/pkg/MikeFarah/yq
+
 ### Mac:
 Using [MacPorts](https://www.macports.org/)
 ```
@@ -290,10 +303,10 @@ Supported by @rmescandon (https://launchpad.net/~rmescandon/+archive/ubuntu/yq)
 - Keeps yaml formatting and comments when updating (though there are issues with whitespace)
 - [Decode/Encode base64 data](https://mikefarah.gitbook.io/yq/operators/encode-decode)
 - [Load content from other files](https://mikefarah.gitbook.io/yq/operators/load)
- [Convert to/from json](https://mikefarah.gitbook.io/yq/v/v4.x/usage/convert)
+- [Convert to/from json/ndjson](https://mikefarah.gitbook.io/yq/v/v4.x/usage/convert)
 - [Convert to/from xml](https://mikefarah.gitbook.io/yq/v/v4.x/usage/xml)
 - [Convert to/from properties](https://mikefarah.gitbook.io/yq/v/v4.x/usage/properties)
- [Convert to csv/tsv](https://mikefarah.gitbook.io/yq/usage/csv-tsv)
+- [Convert to/from csv/tsv](https://mikefarah.gitbook.io/yq/usage/csv-tsv)
 - [General shell completion scripts (bash/zsh/fish/powershell)](https://mikefarah.gitbook.io/yq/v/v4.x/commands/shell-completion)
 - [Reduce](https://mikefarah.gitbook.io/yq/operators/reduce) to merge multiple files or sum an array or other fancy things.
 - [Github Action](https://mikefarah.gitbook.io/yq/usage/github-action) to use in your automated pipeline (thanks @devorbitus)
@@ -0,0 +1,43 @@
+#!/bin/bash
+
+setUp() {
+  rm test*.yml || true
+  
+}
+
+testLineCountFirstLineComment() {
+  cat >test.yml <<EOL
+#test123 
+abc: 123 
+test123: 123123 
+#comment 
+lalilu: lalilu
+EOL
+
+  X=$(./yq '.lalilu | line' --header-preprocess=false < test.yml)
+  assertEquals "5" "$X"
+}
+
+testArrayOfDocs() {
+  cat >test.yml <<EOL
+---
+# leading comment doc 1
+a: 1
+---
+# leading comment doc 2
+a: 2
+EOL
+
+read -r -d '' expected << EOM
+- # leading comment doc 1
+  a: 1
+- # leading comment doc 2
+  a: 2
+EOM
+
+  X=$(./yq ea '[.]' --header-preprocess=false < test.yml)
+  assertEquals "$expected" "$X"
+
+}
+
+source ./scripts/shunit2
@@ -3,6 +3,8 @@
 setUp() {
  rm test*.yml 2>/dev/null || true
  rm test*.properties 2>/dev/null || true
+  rm test*.csv 2>/dev/null || true
+  rm test*.tsv 2>/dev/null || true
  rm test*.xml 2>/dev/null || true
 }

@@ -40,6 +42,65 @@ EOM
  assertEquals "$expected" "$X"
 }

+testInputCSV() {
+  cat >test.csv <<EOL
+fruit,yumLevel
+apple,5
+banana,4
+EOL
+
+  read -r -d '' expected << EOM
+- fruit: apple
+  yumLevel: 5
+- fruit: banana
+  yumLevel: 4
+EOM
+
+  X=$(./yq e -p=csv test.csv)
+  assertEquals "$expected" "$X"
+
+  X=$(./yq ea -p=csv test.csv)
+  assertEquals "$expected" "$X"
+}
+
+testInputCSVUTF8() {
+  read -r -d '' expected << EOM
+- id: 1
+  first: john
+  last: smith
+- id: 1
+  first: jane
+  last: smith
+EOM
+
+  X=$(./yq -p=csv utf8.csv)
+  assertEquals "$expected" "$X"
+}
+
+testInputTSV() {
+  cat >test.tsv <<EOL
+fruit	yumLevel
+apple	5
+banana	4
+EOL
+
+  read -r -d '' expected << EOM
+- fruit: apple
+  yumLevel: 5
+- fruit: banana
+  yumLevel: 4
+EOM
+
+  X=$(./yq e -p=t test.tsv)
+  assertEquals "$expected" "$X"
+
+  X=$(./yq ea -p=t test.tsv)
+  assertEquals "$expected" "$X"
+}
+
+
+
+
 testInputXml() {
  cat >test.yml <<EOL
 <cat legs="4">BiBi</cat>
@@ -66,6 +127,7 @@ testInputXmlNamespaces() {
 EOL

  read -r -d '' expected << EOM
+p_xml: version="1.0"
 map:
  +xmlns: some-namespace
  +xmlns:xsi: some-instance
@@ -79,6 +141,26 @@ EOM
  assertEquals "$expected" "$X"
 }

+testInputXmlRoundtrip() {
+  cat >test.yml <<EOL
+<?xml version="1.0"?>
+<!DOCTYPE config SYSTEM "/etc/iwatch/iwatch.dtd" >
+<map xmlns="some-namespace" xmlns:xsi="some-instance" xsi:schemaLocation="some-url">Meow</map>
+EOL
+
+  read -r -d '' expected << EOM
+<?xml version="1.0"?>
+<!DOCTYPE config SYSTEM "/etc/iwatch/iwatch.dtd" >
+<map xmlns="some-namespace" xmlns:xsi="some-instance" xsi:schemaLocation="some-url">Meow</map>
+EOM
+
+  X=$(./yq -p=xml -o=xml test.yml)
+  assertEquals "$expected" "$X"
+
+  X=$(./yq ea -p=xml -o=xml test.yml)
+  assertEquals "$expected" "$X"
+}
+

 testInputXmlStrict() {
  cat >test.yml <<EOL
@@ -92,11 +174,11 @@ testInputXmlStrict() {
 </root>
 EOL

-  X=$(./yq -p=xml --xml-strict-mode test.yml 2>&1)
+  X=$(./yq -p=xml --xml-strict-mode test.yml -o=xml 2>&1)
  assertEquals 1 $?
  assertEquals "Error: bad file 'test.yml': XML syntax error on line 7: invalid character entity &writer;" "$X"

-  X=$(./yq ea -p=xml --xml-strict-mode test.yml 2>&1)
+  X=$(./yq ea -p=xml --xml-strict-mode test.yml -o=xml 2>&1)
  assertEquals "Error: bad file 'test.yml': XML syntax error on line 7: invalid character entity &writer;" "$X"
 }

@@ -1,5 +1,8 @@
 #!/bin/bash

+
+# examples where header-preprocess is required
+
 setUp() {
  rm test*.yml || true
  cat >test.yml <<EOL
@@ -102,6 +102,48 @@ EOM
  assertEquals "$expected" "$X"
 }

+testOutputCSV() {
+  cat >test.yml <<EOL
+- fruit: apple
+  yumLevel: 5
+- fruit: banana
+  yumLevel: 4
+EOL
+
+  read -r -d '' expected << EOM
+fruit,yumLevel
+apple,5
+banana,4
+EOM
+
+  X=$(./yq -o=c test.yml)
+  assertEquals "$expected" "$X"
+
+  X=$(./yq ea -o=csv test.yml)
+  assertEquals "$expected" "$X"
+}
+
+testOutputTSV() {
+  cat >test.yml <<EOL
+- fruit: apple
+  yumLevel: 5
+- fruit: banana
+  yumLevel: 4
+EOL
+
+  read -r -d '' expected << EOM
+fruit	yumLevel
+apple	5
+banana	4
+EOM
+
+  X=$(./yq -o=t test.yml)
+  assertEquals "$expected" "$X"
+
+  X=$(./yq ea -o=tsv test.yml)
+  assertEquals "$expected" "$X"
+}
+
 testOutputXml() {
  cat >test.yml <<EOL
 a: {b: {c: ["cat"]}}
@@ -12,6 +12,6 @@ outputs:
    description: "The complete result from the yq command being run"
 runs:
  using: 'docker'
-  image: 'github-action/Dockerfile'
+  image: 'docker://mikefarah/yq:4-githubaction'
  args:
    - ${{ inputs.cmd }}
@@ -8,12 +8,6 @@ var outputToJSON = false
 var outputFormat = "yaml"
 var inputFormat = "yaml"

-var xmlAttributePrefix = "+"
-var xmlContentName = "+content"
-var xmlStrictMode = false
-var xmlKeepNamespace = true
-var xmlUseRawToken = true
-
 var exitStatus = false
 var forceColor = false
 var forceNoColor = false
@@ -47,14 +47,18 @@ yq -P sample.json
 			if verbose {
 				backend.SetLevel(logging.DEBUG, "")
 			} else {
-				backend.SetLevel(logging.ERROR, "")
+				backend.SetLevel(logging.WARNING, "")
 			}

 			logging.SetBackend(backend)
 			yqlib.InitExpressionParser()
-			yqlib.XMLPreferences.AttributePrefix = xmlAttributePrefix
-			yqlib.XMLPreferences.ContentName = xmlContentName
-			yqlib.XMLPreferences.StrictMode = xmlStrictMode
+			if (inputFormat == "x" || inputFormat == "xml") &&
+				outputFormat != "x" && outputFormat != "xml" &&
+				yqlib.XMLPreferences.AttributePrefix == "+" {
+				yqlib.GetLogger().Warning("The default xml-attribute-prefix will change in the v4.30 to `+@` to avoid " +
+					"naming conflicts with the default content name, directive name and proc inst prefix. If you need to keep " +
+					"`+` please set that value explicityly with --xml-attribute-prefix.")
+			}
 		},
 	}

@@ -69,11 +73,15 @@ yq -P sample.json
 	rootCmd.PersistentFlags().StringVarP(&outputFormat, "output-format", "o", "yaml", "[yaml|y|json|j|props|p|xml|x] output format type.")
 	rootCmd.PersistentFlags().StringVarP(&inputFormat, "input-format", "p", "yaml", "[yaml|y|props|p|xml|x] parse format for input. Note that json is a subset of yaml.")

-	rootCmd.PersistentFlags().StringVar(&xmlAttributePrefix, "xml-attribute-prefix", "+", "prefix for xml attributes")
-	rootCmd.PersistentFlags().StringVar(&xmlContentName, "xml-content-name", "+content", "name for xml content (if no attribute name is present).")
-	rootCmd.PersistentFlags().BoolVar(&xmlStrictMode, "xml-strict-mode", false, "enables strict parsing of XML. See https://pkg.go.dev/encoding/xml for more details.")
-	rootCmd.PersistentFlags().BoolVar(&xmlKeepNamespace, "xml-keep-namespace", true, "enables keeping namespace after parsing attributes")
-	rootCmd.PersistentFlags().BoolVar(&xmlUseRawToken, "xml-raw-token", true, "enables using RawToken method instead Token. Commonly disables namespace translations. See https://pkg.go.dev/encoding/xml#Decoder.RawToken for details.")
+	rootCmd.PersistentFlags().StringVar(&yqlib.XMLPreferences.AttributePrefix, "xml-attribute-prefix", "+", "prefix for xml attributes")
+	rootCmd.PersistentFlags().StringVar(&yqlib.XMLPreferences.ContentName, "xml-content-name", "+content", "name for xml content (if no attribute name is present).")
+	rootCmd.PersistentFlags().BoolVar(&yqlib.XMLPreferences.StrictMode, "xml-strict-mode", false, "enables strict parsing of XML. See https://pkg.go.dev/encoding/xml for more details.")
+	rootCmd.PersistentFlags().BoolVar(&yqlib.XMLPreferences.KeepNamespace, "xml-keep-namespace", true, "enables keeping namespace after parsing attributes")
+	rootCmd.PersistentFlags().BoolVar(&yqlib.XMLPreferences.UseRawToken, "xml-raw-token", true, "enables using RawToken method instead Token. Commonly disables namespace translations. See https://pkg.go.dev/encoding/xml#Decoder.RawToken for details.")
+	rootCmd.PersistentFlags().StringVar(&yqlib.XMLPreferences.ProcInstPrefix, "xml-proc-inst-prefix", "+p_", "prefix for xml processing instructions (e.g. <?xml version=\"1\"?>)")
+	rootCmd.PersistentFlags().StringVar(&yqlib.XMLPreferences.DirectiveName, "xml-directive-name", "+directive", "name for xml directives (e.g. <!DOCTYPE thing cat>)")
+	rootCmd.PersistentFlags().BoolVar(&yqlib.XMLPreferences.SkipProcInst, "xml-skip-proc-inst", false, "skip over process instructions (e.g. <?xml version=\"1\"?>)")
+	rootCmd.PersistentFlags().BoolVar(&yqlib.XMLPreferences.SkipDirectives, "xml-skip-directives", false, "skip over directives (e.g. <!DOCTYPE thing cat>)")

 	rootCmd.PersistentFlags().BoolVarP(&nullInput, "null-input", "n", false, "Don't read input, simply evaluate the expression given. Useful for creating docs from scratch.")
 	rootCmd.PersistentFlags().BoolVarP(&noDocSeparators, "no-doc", "N", false, "Don't print document separators (---)")
@@ -42,7 +42,7 @@ $ yq shell-completion fish > ~/.config/fish/completions/yq.fish
 `,
 	DisableFlagsInUseLine: true,
 	ValidArgs:             []string{"bash", "zsh", "fish", "powershell"},
-	Args:                  cobra.ExactValidArgs(1),
+	Args:                  cobra.MatchAll(cobra.ExactArgs(1), cobra.OnlyValidArgs),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		var err error = nil
 		switch args[0] {
@@ -63,9 +63,15 @@ func configureDecoder() (yqlib.Decoder, error) {
 	}
 	switch yqlibInputFormat {
 	case yqlib.XMLInputFormat:
-		return yqlib.NewXMLDecoder(xmlAttributePrefix, xmlContentName, xmlStrictMode, xmlKeepNamespace, xmlUseRawToken), nil
+		return yqlib.NewXMLDecoder(yqlib.XMLPreferences), nil
 	case yqlib.PropertiesInputFormat:
 		return yqlib.NewPropertiesDecoder(), nil
+	case yqlib.JsonInputFormat:
+		return yqlib.NewJSONDecoder(), nil
+	case yqlib.CSVObjectInputFormat:
+		return yqlib.NewCSVObjectDecoder(','), nil
+	case yqlib.TSVObjectInputFormat:
+		return yqlib.NewCSVObjectDecoder('\t'), nil
 	}

 	return yqlib.NewYamlDecoder(), nil
@@ -91,7 +97,7 @@ func configurePrinterWriter(format yqlib.PrinterOutputFormat, out io.Writer) (yq
 func configureEncoder(format yqlib.PrinterOutputFormat) yqlib.Encoder {
 	switch format {
 	case yqlib.JSONOutputFormat:
-		return yqlib.NewJONEncoder(indent, colorsEnabled)
+		return yqlib.NewJSONEncoder(indent, colorsEnabled)
 	case yqlib.PropsOutputFormat:
 		return yqlib.NewPropertiesEncoder(unwrapScalar)
 	case yqlib.CSVOutputFormat:
@@ -101,7 +107,7 @@ func configureEncoder(format yqlib.PrinterOutputFormat) yqlib.Encoder {
 	case yqlib.YamlOutputFormat:
 		return yqlib.NewYamlEncoder(indent, colorsEnabled, !noDocSeparators, unwrapScalar)
 	case yqlib.XMLOutputFormat:
-		return yqlib.NewXMLEncoder(indent, xmlAttributePrefix, xmlContentName)
+		return yqlib.NewXMLEncoder(indent, yqlib.XMLPreferences)
 	}
 	panic("invalid encoder")
 }
@@ -11,7 +11,7 @@ var (
 	GitDescribe string

 	// Version is main version number that is being run at the moment.
-	Version = "4.25.3"
+	Version = "4.28.2"

 	// VersionPrerelease is a pre-release marker for the version. If this is "" (empty string)
 	// then it means that it is a final release. Otherwise, this is a pre-release
@@ -1,12 +1,5 @@
-# --------------------------------------------------
-# It's a test with comment
-# --------------------------------------------------
-test:
-  - name: a
-  - name: b
-  - name: c
-groups:
-  - name: a
-  - name: b
-  - name: c
-  - name: c
+volumes:
+  beehive-conf:
+    driver: local
+services:
+  - beehive
@@ -1,14 +1,7 @@
-<!-- before cat -->
-<cat>
-	<!-- in cat before -->
-	<x>3<!-- multi
-line comment
-for x --></x>
-	<y>
-		<!-- in y before -->
-		<d><!-- in d before -->4<!-- in d after --></d>
-		<!-- in y after -->
-	</y>
-	<!-- in_cat_after -->
-</cat>
-<!-- after cat -->
+<?xml version="1.0"?>
+<!DOCTYPE config SYSTEM "/etc/iwatch/iwatch.dtd" >
+<apple>
+<?coolioo version="1.0"?>
+<!DOCTYPE config SYSTEM "/etc/iwatch/iwatch.dtd" >
+<b>things</b>
+</apple>
@@ -0,0 +1,3 @@
+name,numberOfCats,likesApples,height
+Gary,1,true,168.8
+Samantha's Rabbit,2,false,-188.8
@@ -2,7 +2,8 @@ FROM mikefarah/yq:4

 COPY entrypoint.sh /entrypoint.sh

-# this seems to be the default user in github actions
-USER 1001
+# github action recommendation is to run as root.
+# https://docs.github.com/en/actions/creating-actions/dockerfile-support-for-github-actions#user
+USER root

 ENTRYPOINT ["/entrypoint.sh"]
@@ -2,8 +2,11 @@
 set -e
 echo "::debug::\$cmd: $1"
 RESULT=$(eval "$1")
-RESULT="${RESULT//'%'/'%25'}"
-RESULT="${RESULT//$'\n'/'%0A'}"
-RESULT="${RESULT//$'\r'/'%0D'}"
 echo "::debug::\$RESULT: $RESULT"
-echo ::set-output name=result::"$RESULT"
+# updating from 
+# https://github.com/orgs/community/discussions/26288#discussioncomment-3876281
+# https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter
+delimiter=$(cat /proc/sys/kernel/random/uuid)
+echo "result<<${delimiter}" >> "${GITHUB_OUTPUT}"
+echo "${RESULT}" >> "${GITHUB_OUTPUT}"
+echo "${delimiter}" >> "${GITHUB_OUTPUT}"
@@ -2,22 +2,24 @@ module github.com/mikefarah/yq/v4

 require (
 	github.com/a8m/envsubst v1.3.0
-	github.com/alecthomas/participle/v2 v2.0.0-beta.4
-	github.com/alecthomas/repr v0.1.0
-	github.com/elliotchance/orderedmap v1.4.0
+	github.com/alecthomas/participle/v2 v2.0.0-beta.5
+	github.com/alecthomas/repr v0.1.1
+	github.com/dimchansky/utfbom v1.1.1
+	github.com/elliotchance/orderedmap v1.5.0
 	github.com/fatih/color v1.13.0
+	github.com/goccy/go-json v0.9.11
 	github.com/goccy/go-yaml v1.9.5
 	github.com/jinzhu/copier v0.3.5
 	github.com/magiconair/properties v1.8.6
 	github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e
-	github.com/spf13/cobra v1.5.0
+	github.com/spf13/cobra v1.6.0
 	golang.org/x/net v0.0.0-20220708220712-1185a9018129
 	gopkg.in/op/go-logging.v1 v1.0.0-20160211212156-b2cb9fa56473
 	gopkg.in/yaml.v3 v3.0.1
 )

 require (
-	github.com/inconshreveable/mousetrap v1.0.0 // indirect
+	github.com/inconshreveable/mousetrap v1.0.1 // indirect
 	github.com/mattn/go-colorable v0.1.12 // indirect
 	github.com/mattn/go-isatty v0.0.14 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
@@ -26,4 +28,4 @@ require (
 	golang.org/x/xerrors v0.0.0-20220609144429-65e65417b02f // indirect
 )

-go 1.18
+go 1.19
@@ -1,15 +1,17 @@
 github.com/a8m/envsubst v1.3.0 h1:GmXKmVssap0YtlU3E230W98RWtWCyIZzjtf1apWWyAg=
 github.com/a8m/envsubst v1.3.0/go.mod h1:MVUTQNGQ3tsjOOtKCNd+fl8RzhsXcDvvAEzkhGtlsbY=
 github.com/alecthomas/assert/v2 v2.0.3 h1:WKqJODfOiQG0nEJKFKzDIG3E29CN2/4zR9XGJzKIkbg=
-github.com/alecthomas/participle/v2 v2.0.0-beta.4 h1:ublfGBm+x+p2j7KotHhrUMbKtejT7M0Gv1Mt1u3absw=
-github.com/alecthomas/participle/v2 v2.0.0-beta.4/go.mod h1:RC764t6n4L8D8ITAJv0qdokritYSNR3wV5cVwmIEaMM=
-github.com/alecthomas/repr v0.1.0 h1:ENn2e1+J3k09gyj2shc0dHr/yjaWSHRlrJ4DPMevDqE=
-github.com/alecthomas/repr v0.1.0/go.mod h1:2kn6fqh/zIyPLmm3ugklbEi5hg5wS435eygvNfaDQL8=
+github.com/alecthomas/participle/v2 v2.0.0-beta.5 h1:y6dsSYVb1G5eK6mgmy+BgI3Mw35a3WghArZ/Hbebrjo=
+github.com/alecthomas/participle/v2 v2.0.0-beta.5/go.mod h1:RC764t6n4L8D8ITAJv0qdokritYSNR3wV5cVwmIEaMM=
+github.com/alecthomas/repr v0.1.1 h1:87P60cSmareLAxMc4Hro0r2RBY4ROm0dYwkJNpS4pPs=
+github.com/alecthomas/repr v0.1.1/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4=
 github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/elliotchance/orderedmap v1.4.0 h1:wZtfeEONCbx6in1CZyE6bELEt/vFayMvsxqI5SgsR+A=
-github.com/elliotchance/orderedmap v1.4.0/go.mod h1:wsDwEaX5jEoyhbs7x93zk2H/qv0zwuhg4inXhDkYqys=
+github.com/dimchansky/utfbom v1.1.1 h1:vV6w1AhK4VMnhBno/TPVCoK9U/LP0PkLCS9tbxHdi/U=
+github.com/dimchansky/utfbom v1.1.1/go.mod h1:SxdoEBH5qIqFocHMyGOXVAybYJdr71b1Q/j0mACtrfE=
+github.com/elliotchance/orderedmap v1.5.0 h1:1IsExUsjv5XNBD3ZdC7jkAAqLWOOKdbPTmkHx63OsBg=
+github.com/elliotchance/orderedmap v1.5.0/go.mod h1:wsDwEaX5jEoyhbs7x93zk2H/qv0zwuhg4inXhDkYqys=
 github.com/fatih/color v1.10.0/go.mod h1:ELkj/draVOlAH/xkhN6mQ50Qd0MPOk5AAr3maGEBuJM=
 github.com/fatih/color v1.13.0 h1:8LOYc1KYPPmyKMuN8QV2DNRWNbLo6LZ0iLs8+mlH53w=
 github.com/fatih/color v1.13.0/go.mod h1:kLAiJbzzSOZDVNGyDpeOxJ47H46qBXwg5ILebYFFOfk=
@@ -17,11 +19,13 @@ github.com/go-playground/assert/v2 v2.0.1/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvSc
 github.com/go-playground/locales v0.13.0/go.mod h1:taPMhCMXrRLJO55olJkUXHZBHCxTMfnGwq/HNwmWNS8=
 github.com/go-playground/universal-translator v0.17.0/go.mod h1:UkSxE5sNxxRwHyU+Scu5vgOQjsIJAF8j9muTVoKLVtA=
 github.com/go-playground/validator/v10 v10.4.1/go.mod h1:nlOn6nFhuKACm19sB/8EGNn9GlaMV7XkbRSipzJ0Ii4=
+github.com/goccy/go-json v0.9.11 h1:/pAaQDLHEoCq/5FFmSKBswWmK6H0e8g4159Kc/X/nqk=
+github.com/goccy/go-json v0.9.11/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
 github.com/goccy/go-yaml v1.9.5 h1:Eh/+3uk9kLxG4koCX6lRMAPS1OaMSAi+FJcya0INdB0=
 github.com/goccy/go-yaml v1.9.5/go.mod h1:U/jl18uSupI5rdI2jmuCswEA2htH9eXfferR3KfscvA=
 github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM=
-github.com/inconshreveable/mousetrap v1.0.0 h1:Z8tu5sraLXCXIcARxBp/8cbvlwVa7Z1NHg9XEKhtSvM=
-github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8=
+github.com/inconshreveable/mousetrap v1.0.1 h1:U3uMjPSQEBMNp1lFxmllqCPM6P5u/Xq7Pgzkat/bFNc=
+github.com/inconshreveable/mousetrap v1.0.1/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/jinzhu/copier v0.3.5 h1:GlvfUwHk62RokgqVNvYsku0TATCF7bAHVwEXoBh3iJg=
 github.com/jinzhu/copier v0.3.5/go.mod h1:DfbEm0FYsaqBcKcFuvmOZb218JkPGtvSHsKg8S8hyyg=
 github.com/leodido/go-urn v1.2.0/go.mod h1:+8+nEpDfqqsY+g338gtMEUOtuK+4dEMhiQEgxpxOKII=
@@ -39,8 +43,8 @@ github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsK
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
-github.com/spf13/cobra v1.5.0 h1:X+jTBEBqF0bHN+9cSMgmfuvv2VHJ9ezmFNf9Y/XstYU=
-github.com/spf13/cobra v1.5.0/go.mod h1:dWXEIy2H428czQCjInthrTRUg7yKbok+2Qi/yBIJoUM=
+github.com/spf13/cobra v1.6.0 h1:42a0n6jwCot1pUmomAp4T7DeMD+20LFv4Q54pxLf2LI=
+github.com/spf13/cobra v1.6.0/go.mod h1:IOw/AERYS7UzyrGinqmz6HLUo219MORXGxhbaJUqzrY=
 github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
 github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
@@ -73,7 +77,6 @@ gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8
 gopkg.in/op/go-logging.v1 v1.0.0-20160211212156-b2cb9fa56473 h1:6D+BvnJ/j6e222UW8s2qTSe3wGBtvo0MbVQG/c5k8RE=
 gopkg.in/op/go-logging.v1 v1.0.0-20160211212156-b2cb9fa56473/go.mod h1:N1eN2tsCx0Ydtgjl4cqmbRCsY4/+z4cYDeqwZTk6zog=
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
-gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
@@ -37,7 +37,7 @@ The `=` operator then pipes the 'root' context through the `rhs` expression of `
 dog
 ```

-Both sides have now been evaluated, so now the operator copies across the value from the RHS (`.b`) to the the LHS (`.a`), and it returns the now updated context:
+Both sides have now been evaluated, so now the operator copies across the value from the RHS (`.b`) to the LHS (`.a`), and it returns the now updated context:

 ```yaml
 a: dog
@@ -157,7 +157,7 @@ func (n *CandidateNode) UpdateAttributesFrom(other *CandidateNode, prefs assignP
 	n.Node.Kind = other.Node.Kind

 	// don't clobber custom tags...
-	if strings.HasPrefix(n.Node.Tag, "!!") || n.Node.Tag == "" {
+	if prefs.ClobberCustomTags || strings.HasPrefix(n.Node.Tag, "!!") || n.Node.Tag == "" {
 		n.Node.Tag = other.Node.Tag
 	}

@@ -0,0 +1,273 @@
+package yqlib
+
+import (
+	"bufio"
+	"fmt"
+	"testing"
+
+	"github.com/mikefarah/yq/v4/test"
+)
+
+const csvSimple = `name,numberOfCats,likesApples,height
+Gary,1,true,168.8
+Samantha's Rabbit,2,false,-188.8
+`
+
+const expectedUpdatedSimpleCsv = `name,numberOfCats,likesApples,height
+Gary,3,true,168.8
+Samantha's Rabbit,2,false,-188.8
+`
+
+const csvSimpleShort = `Name,Number of Cats
+Gary,1
+Samantha's Rabbit,2
+`
+
+const tsvSimple = `name	numberOfCats	likesApples	height
+Gary	1	true	168.8
+Samantha's Rabbit	2	false	-188.8
+`
+
+const expectedYamlFromCSV = `- name: Gary
+  numberOfCats: 1
+  likesApples: true
+  height: 168.8
+- name: Samantha's Rabbit
+  numberOfCats: 2
+  likesApples: false
+  height: -188.8
+`
+
+const expectedYamlFromCSVMissingData = `- name: Gary
+  numberOfCats: 1
+  height: 168.8
+- name: Samantha's Rabbit
+  height: -188.8
+  likesApples: false
+`
+
+const csvSimpleMissingData = `name,numberOfCats,height
+Gary,1,168.8
+Samantha's Rabbit,,-188.8
+`
+
+const csvTestSimpleYaml = `- [i, like, csv]
+- [because, excel, is, cool]`
+
+const expectedSimpleCsv = `i,like,csv
+because,excel,is,cool
+`
+
+const tsvTestExpectedSimpleCsv = `i	like	csv
+because	excel	is	cool
+`
+
+var csvScenarios = []formatScenario{
+	{
+		description:  "Encode CSV simple",
+		input:        csvTestSimpleYaml,
+		expected:     expectedSimpleCsv,
+		scenarioType: "encode-csv",
+	},
+	{
+		description:  "Encode TSV simple",
+		input:        csvTestSimpleYaml,
+		expected:     tsvTestExpectedSimpleCsv,
+		scenarioType: "encode-tsv",
+	},
+	{
+		description:  "Encode Empty",
+		skipDoc:      true,
+		input:        `[]`,
+		expected:     "",
+		scenarioType: "encode-csv",
+	},
+	{
+		description:  "Comma in value",
+		skipDoc:      true,
+		input:        `["comma, in, value", things]`,
+		expected:     "\"comma, in, value\",things\n",
+		scenarioType: "encode-csv",
+	},
+	{
+		description:  "Encode array of objects to csv",
+		input:        expectedYamlFromCSV,
+		expected:     csvSimple,
+		scenarioType: "encode-csv",
+	},
+	{
+		description:    "Encode array of objects to custom csv format",
+		subdescription: "Add the header row manually, then the we convert each object into an array of values - resulting in an array of arrays. Pick the columns and call the header whatever you like.",
+		input:          expectedYamlFromCSV,
+		expected:       csvSimpleShort,
+		expression:     `[["Name", "Number of Cats"]] +  [.[] | [.name, .numberOfCats ]]`,
+		scenarioType:   "encode-csv",
+	},
+	{
+		description:    "Encode array of objects to csv - missing fields behaviour",
+		subdescription: "First entry is used to determine the headers, and it is missing 'likesApples', so it is not included in the csv. Second entry does not have 'numberOfCats' so that is blank",
+		input:          expectedYamlFromCSVMissingData,
+		expected:       csvSimpleMissingData,
+		scenarioType:   "encode-csv",
+	},
+	{
+		description:    "Parse CSV into an array of objects",
+		subdescription: "First row is assumed to be the header row.",
+		input:          csvSimple,
+		expected:       expectedYamlFromCSV,
+		scenarioType:   "decode-csv-object",
+	},
+	{
+		description:    "Parse TSV into an array of objects",
+		subdescription: "First row is assumed to be the header row.",
+		input:          tsvSimple,
+		expected:       expectedYamlFromCSV,
+		scenarioType:   "decode-tsv-object",
+	},
+	{
+		description:  "Round trip",
+		input:        csvSimple,
+		expected:     expectedUpdatedSimpleCsv,
+		expression:   `(.[] | select(.name == "Gary") | .numberOfCats) = 3`,
+		scenarioType: "roundtrip-csv",
+	},
+}
+
+func testCSVScenario(t *testing.T, s formatScenario) {
+	switch s.scenarioType {
+	case "encode-csv":
+		test.AssertResultWithContext(t, s.expected, processFormatScenario(s, NewYamlDecoder(), NewCsvEncoder(',')), s.description)
+	case "encode-tsv":
+		test.AssertResultWithContext(t, s.expected, processFormatScenario(s, NewYamlDecoder(), NewCsvEncoder('\t')), s.description)
+	case "decode-csv-object":
+		test.AssertResultWithContext(t, s.expected, processFormatScenario(s, NewCSVObjectDecoder(','), NewYamlEncoder(2, false, true, true)), s.description)
+	case "decode-tsv-object":
+		test.AssertResultWithContext(t, s.expected, processFormatScenario(s, NewCSVObjectDecoder('\t'), NewYamlEncoder(2, false, true, true)), s.description)
+	case "roundtrip-csv":
+		test.AssertResultWithContext(t, s.expected, processFormatScenario(s, NewCSVObjectDecoder(','), NewCsvEncoder(',')), s.description)
+	default:
+		panic(fmt.Sprintf("unhandled scenario type %q", s.scenarioType))
+	}
+}
+
+func documentCSVDecodeObjectScenario(w *bufio.Writer, s formatScenario, formatType string) {
+	writeOrPanic(w, fmt.Sprintf("## %v\n", s.description))
+
+	if s.subdescription != "" {
+		writeOrPanic(w, s.subdescription)
+		writeOrPanic(w, "\n\n")
+	}
+
+	writeOrPanic(w, fmt.Sprintf("Given a sample.%v file of:\n", formatType))
+	writeOrPanic(w, fmt.Sprintf("```%v\n%v\n```\n", formatType, s.input))
+
+	writeOrPanic(w, "then\n")
+	writeOrPanic(w, fmt.Sprintf("```bash\nyq -p=%v sample.%v\n```\n", formatType, formatType))
+	writeOrPanic(w, "will output\n")
+
+	separator := ','
+	if formatType == "tsv" {
+		separator = '\t'
+	}
+
+	writeOrPanic(w, fmt.Sprintf("```yaml\n%v```\n\n",
+		processFormatScenario(s, NewCSVObjectDecoder(separator), NewYamlEncoder(s.indent, false, true, true))),
+	)
+}
+
+func documentCSVEncodeScenario(w *bufio.Writer, s formatScenario, formatType string) {
+	writeOrPanic(w, fmt.Sprintf("## %v\n", s.description))
+
+	if s.subdescription != "" {
+		writeOrPanic(w, s.subdescription)
+		writeOrPanic(w, "\n\n")
+	}
+
+	writeOrPanic(w, "Given a sample.yml file of:\n")
+	writeOrPanic(w, fmt.Sprintf("```yaml\n%v\n```\n", s.input))
+
+	writeOrPanic(w, "then\n")
+
+	expression := s.expression
+
+	if expression != "" {
+		writeOrPanic(w, fmt.Sprintf("```bash\nyq -o=%v '%v' sample.yml\n```\n", formatType, expression))
+	} else {
+		writeOrPanic(w, fmt.Sprintf("```bash\nyq -o=%v sample.yml\n```\n", formatType))
+	}
+	writeOrPanic(w, "will output\n")
+
+	separator := ','
+	if formatType == "tsv" {
+		separator = '\t'
+	}
+
+	writeOrPanic(w, fmt.Sprintf("```%v\n%v```\n\n", formatType,
+		processFormatScenario(s, NewYamlDecoder(), NewCsvEncoder(separator))),
+	)
+}
+
+func documentCSVRoundTripScenario(w *bufio.Writer, s formatScenario, formatType string) {
+	writeOrPanic(w, fmt.Sprintf("## %v\n", s.description))
+
+	if s.subdescription != "" {
+		writeOrPanic(w, s.subdescription)
+		writeOrPanic(w, "\n\n")
+	}
+
+	writeOrPanic(w, fmt.Sprintf("Given a sample.%v file of:\n", formatType))
+	writeOrPanic(w, fmt.Sprintf("```%v\n%v\n```\n", formatType, s.input))
+
+	writeOrPanic(w, "then\n")
+
+	expression := s.expression
+
+	if expression != "" {
+		writeOrPanic(w, fmt.Sprintf("```bash\nyq -p=%v -o=%v '%v' sample.%v\n```\n", formatType, formatType, expression, formatType))
+	} else {
+		writeOrPanic(w, fmt.Sprintf("```bash\nyq -p=%v -o=%v sample.%v\n```\n", formatType, formatType, formatType))
+	}
+	writeOrPanic(w, "will output\n")
+
+	separator := ','
+	if formatType == "tsv" {
+		separator = '\t'
+	}
+
+	writeOrPanic(w, fmt.Sprintf("```%v\n%v```\n\n", formatType,
+		processFormatScenario(s, NewCSVObjectDecoder(separator), NewCsvEncoder(separator))),
+	)
+}
+
+func documentCSVScenario(t *testing.T, w *bufio.Writer, i interface{}) {
+	s := i.(formatScenario)
+	if s.skipDoc {
+		return
+	}
+	switch s.scenarioType {
+	case "encode-csv":
+		documentCSVEncodeScenario(w, s, "csv")
+	case "encode-tsv":
+		documentCSVEncodeScenario(w, s, "tsv")
+	case "decode-csv-object":
+		documentCSVDecodeObjectScenario(w, s, "csv")
+	case "decode-tsv-object":
+		documentCSVDecodeObjectScenario(w, s, "tsv")
+	case "roundtrip-csv":
+		documentCSVRoundTripScenario(w, s, "csv")
+
+	default:
+		panic(fmt.Sprintf("unhandled scenario type %q", s.scenarioType))
+	}
+}
+
+func TestCSVScenarios(t *testing.T) {
+	for _, tt := range csvScenarios {
+		testCSVScenario(t, tt)
+	}
+	genericScenarios := make([]interface{}, len(csvScenarios))
+	for i, s := range csvScenarios {
+		genericScenarios[i] = s
+	}
+	documentScenarios(t, "usage", "csv-tsv", genericScenarios, documentCSVScenario)
+}
@@ -14,6 +14,9 @@ const (
 	XMLInputFormat
 	PropertiesInputFormat
 	Base64InputFormat
+	JsonInputFormat
+	CSVObjectInputFormat
+	TSVObjectInputFormat
 )

 type Decoder interface {
@@ -29,6 +32,12 @@ func InputFormatFromString(format string) (InputFormat, error) {
 		return XMLInputFormat, nil
 	case "props", "p":
 		return PropertiesInputFormat, nil
+	case "json", "ndjson", "j":
+		return JsonInputFormat, nil
+	case "csv", "c":
+		return CSVObjectInputFormat, nil
+	case "tsv", "t":
+		return TSVObjectInputFormat, nil
 	default:
 		return 0, fmt.Errorf("unknown format '%v' please use [yaml|xml|props]", format)
 	}
@@ -0,0 +1,80 @@
+package yqlib
+
+import (
+	"encoding/csv"
+	"errors"
+	"io"
+
+	"github.com/dimchansky/utfbom"
+	yaml "gopkg.in/yaml.v3"
+)
+
+type csvObjectDecoder struct {
+	separator rune
+	reader    csv.Reader
+	finished  bool
+}
+
+func NewCSVObjectDecoder(separator rune) Decoder {
+	return &csvObjectDecoder{separator: separator}
+}
+
+func (dec *csvObjectDecoder) Init(reader io.Reader) {
+	cleanReader, enc := utfbom.Skip(reader)
+	log.Debugf("Detected encoding: %s\n", enc)
+	dec.reader = *csv.NewReader(cleanReader)
+	dec.reader.Comma = dec.separator
+	dec.finished = false
+}
+
+func (dec *csvObjectDecoder) convertToYamlNode(content string) *yaml.Node {
+	node, err := parseSnippet(content)
+	if err != nil {
+		return createScalarNode(content, content)
+	}
+	return node
+}
+
+func (dec *csvObjectDecoder) createObject(headerRow []string, contentRow []string) *yaml.Node {
+	objectNode := &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map"}
+
+	for i, header := range headerRow {
+		objectNode.Content = append(
+			objectNode.Content,
+			createScalarNode(header, header),
+			dec.convertToYamlNode(contentRow[i]))
+	}
+	return objectNode
+}
+
+func (dec *csvObjectDecoder) Decode(rootYamlNode *yaml.Node) error {
+	if dec.finished {
+		return io.EOF
+	}
+	headerRow, err := dec.reader.Read()
+	log.Debugf(": headerRow%v", headerRow)
+	if err != nil {
+		return err
+	}
+
+	rootArray := &yaml.Node{Kind: yaml.SequenceNode, Tag: "!!seq"}
+
+	contentRow, err := dec.reader.Read()
+
+	for err == nil && len(contentRow) > 0 {
+		log.Debugf("Adding contentRow: %v", contentRow)
+		rootArray.Content = append(rootArray.Content, dec.createObject(headerRow, contentRow))
+		contentRow, err = dec.reader.Read()
+		log.Debugf("Read next contentRow: %v, %v", contentRow, err)
+	}
+	if !errors.Is(err, io.EOF) {
+		return err
+	}
+
+	log.Debugf("finished, contentRow%v", contentRow)
+	log.Debugf("err: %v", err)
+
+	rootYamlNode.Kind = yaml.DocumentNode
+	rootYamlNode.Content = []*yaml.Node{rootArray}
+	return nil
+}
@@ -0,0 +1,82 @@
+package yqlib
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/goccy/go-json"
+	yaml "gopkg.in/yaml.v3"
+)
+
+type jsonDecoder struct {
+	decoder json.Decoder
+}
+
+func NewJSONDecoder() Decoder {
+	return &jsonDecoder{}
+}
+
+func (dec *jsonDecoder) Init(reader io.Reader) {
+	dec.decoder = *json.NewDecoder(reader)
+}
+
+func (dec *jsonDecoder) Decode(rootYamlNode *yaml.Node) error {
+
+	var dataBucket orderedMap
+	log.Debug("going to decode")
+	err := dec.decoder.Decode(&dataBucket)
+	if err != nil {
+		return err
+	}
+	node, err := dec.convertToYamlNode(&dataBucket)
+
+	if err != nil {
+		return err
+	}
+	rootYamlNode.Kind = yaml.DocumentNode
+	rootYamlNode.Content = []*yaml.Node{node}
+	return nil
+}
+
+func (dec *jsonDecoder) convertToYamlNode(data *orderedMap) (*yaml.Node, error) {
+	if data.kv == nil {
+		switch rawData := data.altVal.(type) {
+		case nil:
+			return createScalarNode(nil, "null"), nil
+		case float64, float32:
+			// json decoder returns ints as float.
+			return parseSnippet(fmt.Sprintf("%v", rawData))
+		case int, int64, int32, string, bool:
+			return createScalarNode(rawData, fmt.Sprintf("%v", rawData)), nil
+		case []*orderedMap:
+			return dec.parseArray(rawData)
+		default:
+			return nil, fmt.Errorf("unrecognised type :( %v", rawData)
+		}
+	}
+
+	var yamlMap = &yaml.Node{Kind: yaml.MappingNode}
+	for _, keyValuePair := range data.kv {
+		yamlValue, err := dec.convertToYamlNode(&keyValuePair.V)
+		if err != nil {
+			return nil, err
+		}
+		yamlMap.Content = append(yamlMap.Content, createScalarNode(keyValuePair.K, keyValuePair.K), yamlValue)
+	}
+	return yamlMap, nil
+
+}
+
+func (dec *jsonDecoder) parseArray(dataArray []*orderedMap) (*yaml.Node, error) {
+
+	var yamlMap = &yaml.Node{Kind: yaml.SequenceNode}
+
+	for _, value := range dataArray {
+		yamlValue, err := dec.convertToYamlNode(value)
+		if err != nil {
+			return nil, err
+		}
+		yamlMap.Content = append(yamlMap.Content, yamlValue)
+	}
+	return yamlMap, nil
+}
@@ -12,27 +12,16 @@ import (
 )

 type xmlDecoder struct {
-	reader          io.Reader
-	readAnything    bool
-	attributePrefix string
-	contentName     string
-	strictMode      bool
-	keepNamespace   bool
-	useRawToken     bool
-	finished        bool
+	reader       io.Reader
+	readAnything bool
+	finished     bool
+	prefs        xmlPreferences
 }

-func NewXMLDecoder(attributePrefix string, contentName string, strictMode bool, keepNamespace bool, useRawToken bool) Decoder {
-	if contentName == "" {
-		contentName = "content"
-	}
+func NewXMLDecoder(prefs xmlPreferences) Decoder {
 	return &xmlDecoder{
-		attributePrefix: attributePrefix,
-		contentName:     contentName,
-		finished:        false,
-		strictMode:      strictMode,
-		keepNamespace:   keepNamespace,
-		useRawToken:     useRawToken,
+		finished: false,
+		prefs:    prefs,
 	}
 }

@@ -43,7 +32,7 @@ func (dec *xmlDecoder) Init(reader io.Reader) {
 }

 func (dec *xmlDecoder) createSequence(nodes []*xmlNode) (*yaml.Node, error) {
-	yamlNode := &yaml.Node{Kind: yaml.SequenceNode}
+	yamlNode := &yaml.Node{Kind: yaml.SequenceNode, Tag: "!!seq"}
 	for _, child := range nodes {
 		yamlChild, err := dec.convertToYamlNode(child)
 		if err != nil {
@@ -64,10 +53,10 @@ func (dec *xmlDecoder) processComment(c string) string {

 func (dec *xmlDecoder) createMap(n *xmlNode) (*yaml.Node, error) {
 	log.Debug("createMap: headC: %v, footC: %v", n.HeadComment, n.FootComment)
-	yamlNode := &yaml.Node{Kind: yaml.MappingNode}
+	yamlNode := &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map"}

 	if len(n.Data) > 0 {
-		label := dec.contentName
+		label := dec.prefs.ContentName
 		labelNode := createScalarNode(label, label)
 		labelNode.HeadComment = dec.processComment(n.HeadComment)
 		labelNode.FootComment = dec.processComment(n.FootComment)
@@ -86,9 +75,7 @@ func (dec *xmlDecoder) createMap(n *xmlNode) (*yaml.Node, error) {

 		}

-		// if i == len(n.Children)-1 {
 		labelNode.FootComment = dec.processComment(keyValuePair.FootComment)
-		// }

 		log.Debug("len of children in %v is %v", label, len(children))
 		if len(children) > 1 {
@@ -205,7 +192,7 @@ type element struct {
 // of the map keys.
 func (dec *xmlDecoder) decodeXML(root *xmlNode) error {
 	xmlDec := xml.NewDecoder(dec.reader)
-	xmlDec.Strict = dec.strictMode
+	xmlDec.Strict = dec.prefs.StrictMode
 	// That will convert the charset if the provided XML is non-UTF-8
 	xmlDec.CharsetReader = charset.NewReaderLabel

@@ -216,7 +203,7 @@ func (dec *xmlDecoder) decodeXML(root *xmlNode) error {
 	}

 	getToken := func() (xml.Token, error) {
-		if dec.useRawToken {
+		if dec.prefs.UseRawToken {
 			return xmlDec.RawToken()
 		}
 		return xmlDec.Token()
@@ -244,12 +231,12 @@ func (dec *xmlDecoder) decodeXML(root *xmlNode) error {

 			// Extract attributes as children
 			for _, a := range se.Attr {
-				if dec.keepNamespace {
+				if dec.prefs.KeepNamespace {
 					if a.Name.Space != "" {
 						a.Name.Local = a.Name.Space + ":" + a.Name.Local
 					}
 				}
-				elem.n.AddChild(dec.attributePrefix+a.Name.Local, &xmlNode{Data: a.Value})
+				elem.n.AddChild(dec.prefs.AttributePrefix+a.Name.Local, &xmlNode{Data: a.Value})
 			}
 		case xml.CharData:
 			// Extract XML data (if any)
@@ -282,6 +269,14 @@ func (dec *xmlDecoder) decodeXML(root *xmlNode) error {
 				elem.n.HeadComment = joinFilter([]string{elem.n.HeadComment, commentStr})
 			}

+		case xml.ProcInst:
+			if !dec.prefs.SkipProcInst {
+				elem.n.AddChild(dec.prefs.ProcInstPrefix+se.Target, &xmlNode{Data: string(se.Inst)})
+			}
+		case xml.Directive:
+			if !dec.prefs.SkipDirectives {
+				elem.n.AddChild(dec.prefs.DirectiveName, &xmlNode{Data: string(se)})
+			}
 		}
 	}

@@ -1,6 +0,0 @@
-
-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
@@ -9,12 +9,6 @@ Add behaves differently according to the type of the LHS:
 Use `+=` as a relative append assign for things like increment. Note that `.a += .x` is equivalent to running `.a = .a + .x`.


-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Concatenate arrays
 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 This operator is used to provide alternative (or default) values when a particular expression is either null or false.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## LHS is defined
 Given a sample.yml file of:
 ```yaml
@@ -79,3 +73,36 @@ will output
 cat
 ```

+## Update or create - entity exists
+This initialises `a` if it's not present
+
+Given a sample.yml file of:
+```yaml
+a: 1
+```
+then
+```bash
+yq '(.a // (.a = 0)) += 1' sample.yml
+```
+will output
+```yaml
+a: 2
+```
+
+## Update or create - entity does not exist
+This initialises `a` if it's not present
+
+Given a sample.yml file of:
+```yaml
+b: camel
+```
+then
+```bash
+yq '(.a // (.a = 0)) += 1' sample.yml
+```
+will output
+```yaml
+b: camel
+a: 1
+```
+
@@ -5,12 +5,6 @@ Use the `alias` and `anchor` operators to read and write yaml aliases and anchor
 `yq` supports merge aliases (like `<<: *blah`) however this is no longer in the standard yaml spec (1.2) and so `yq` will automatically add the `!!merge` tag to these nodes as it is effectively a custom tag.


-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Merge one map
 see https://yaml.org/type/merge.html

@@ -7,11 +7,10 @@ Which will assign the LHS node values to the RHS node values. The RHS expression

 ### relative form: `|=`
 This will do a similar thing to the plain form, however, the RHS expression is run against _the LHS nodes_. This is useful for updating values based on old values, e.g. increment.
-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;

-`yq e <exp> <file>`
-{% endhint %}
+
+### Flags
+- `c` clobber custom tags

 ## Create yaml file
 Running
@@ -235,3 +234,37 @@ a:
    - bogs
 ```

+## Custom types are maintained by default
+Given a sample.yml file of:
+```yaml
+a: !cat meow
+b: !dog woof
+```
+then
+```bash
+yq '.a = .b' sample.yml
+```
+will output
+```yaml
+a: !cat woof
+b: !dog woof
+```
+
+## Custom types: clovver
+Use the `c` option to clobber custom tags
+
+Given a sample.yml file of:
+```yaml
+a: !cat meow
+b: !dog woof
+```
+then
+```bash
+yq '.a =c .b' sample.yml
+```
+will output
+```yaml
+a: !dog woof
+b: !dog woof
+```
+
@@ -16,12 +16,6 @@ These are most commonly used with the `select` operator to filter particular nod
 - comparison (`>=`, `<` etc) operators [here](https://mikefarah.gitbook.io/yq/operators/compare)
 - select operator [here](https://mikefarah.gitbook.io/yq/operators/select)

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## `or` example
 Running
 ```bash
@@ -3,12 +3,6 @@
 This creates an array using the expression between the square brackets.


-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Collect empty
 Running
 ```bash
@@ -2,12 +2,6 @@

 Returns the column of the matching node. Starts from 1, 0 indicates there was no column data.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Returns column of _value_ node
 Given a sample.yml file of:
 ```yaml
@@ -1,6 +1,6 @@
 # Comment Operators

-Use these comment operators to set or retrieve comments.
+Use these comment operators to set or retrieve comments. Note that line comments on maps/arrays are actually set on the _key_ node as opposed to the _value_ (map/array). See below for examples.

 Like the `=` and `|=` assign operators, the same syntax applies when updating comments:

@@ -10,13 +10,9 @@ This will assign the LHS nodes comments to the expression on the RHS. The RHS is
 ### relative form: `|=` 
 Similar to the plain form, however the RHS evaluates against each matching LHS node! This is useful if you want to set the comments as a relative expression of the node, for instance its value or path.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Set line comment
+Set the comment on the key node for more reliability (see below).
+
 Given a sample.yml file of:
 ```yaml
 a: cat
@@ -30,6 +26,24 @@ will output
 a: cat # single
 ```

+## Set line comment of a maps/arrays
+For maps and arrays, you need to set the line comment on the _key_ node. This will also work for scalars.
+
+Given a sample.yml file of:
+```yaml
+a:
+  b: things
+```
+then
+```bash
+yq '(.a | key) line_comment="single"' sample.yml
+```
+will output
+```yaml
+a: # single
+  b: things
+```
+
 ## Use update assign to perform relative updates
 Given a sample.yml file of:
 ```yaml
@@ -46,6 +60,121 @@ a: cat # cat
 b: dog # dog
 ```

+## Where is the comment - map key example
+The underlying yaml parser can assign comments in a document to surprising nodes. Use an expression like this to find where you comment is. 'p' indicates the path, 'isKey' is if the node is a map key (as opposed to a map value).
+From this, you can see the 'hello-world-comment' is actually on the 'hello' key
+
+Given a sample.yml file of:
+```yaml
+hello: # hello-world-comment
+  message: world
+```
+then
+```bash
+yq '[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]' sample.yml
+```
+will output
+```yaml
+- p: ""
+  isKey: false
+  hc: ""
+  lc: ""
+  fc: ""
+- p: hello
+  isKey: true
+  hc: ""
+  lc: hello-world-comment
+  fc: ""
+- p: hello
+  isKey: false
+  hc: ""
+  lc: ""
+  fc: ""
+- p: hello.message
+  isKey: true
+  hc: ""
+  lc: ""
+  fc: ""
+- p: hello.message
+  isKey: false
+  hc: ""
+  lc: ""
+  fc: ""
+```
+
+## Retrieve comment - map key example
+From the previous example, we know that the comment is on the 'hello' _key_ as a lineComment
+
+Given a sample.yml file of:
+```yaml
+hello: # hello-world-comment
+  message: world
+```
+then
+```bash
+yq '.hello | key | line_comment' sample.yml
+```
+will output
+```yaml
+hello-world-comment
+```
+
+## Where is the comment - array example
+The underlying yaml parser can assign comments in a document to surprising nodes. Use an expression like this to find where you comment is. 'p' indicates the path, 'isKey' is if the node is a map key (as opposed to a map value).
+From this, you can see the 'under-name-comment' is actually on the first child
+
+Given a sample.yml file of:
+```yaml
+name:
+  # under-name-comment
+  - first-array-child
+```
+then
+```bash
+yq '[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]' sample.yml
+```
+will output
+```yaml
+- p: ""
+  isKey: false
+  hc: ""
+  lc: ""
+  fc: ""
+- p: name
+  isKey: true
+  hc: ""
+  lc: ""
+  fc: ""
+- p: name
+  isKey: false
+  hc: ""
+  lc: ""
+  fc: ""
+- p: name.0
+  isKey: false
+  hc: under-name-comment
+  lc: ""
+  fc: ""
+```
+
+## Retrieve comment - array example
+From the previous example, we know that the comment is on the first child as a headComment
+
+Given a sample.yml file of:
+```yaml
+name:
+  # under-name-comment
+  - first-array-child
+```
+then
+```bash
+yq '.name[0] | headComment' sample.yml
+```
+will output
+```yaml
+under-name-comment
+```
+
 ## Set head comment
 Given a sample.yml file of:
 ```yaml
@@ -62,6 +191,25 @@ will output
 a: cat
 ```

+## Set head comment of a map entry
+Given a sample.yml file of:
+```yaml
+f: foo
+a:
+  b: cat
+```
+then
+```bash
+yq '(.a | key) head_comment="single"' sample.yml
+```
+will output
+```yaml
+f: foo
+# single
+a:
+  b: cat
+```
+
 ## Set foot comment, using an expression
 Given a sample.yml file of:
 ```yaml
@@ -14,12 +14,6 @@ The following types are currently supported:
 - boolean operators (`and`, `or`, `any` etc) [here](https://mikefarah.gitbook.io/yq/operators/boolean-operators)
 - select operator [here](https://mikefarah.gitbook.io/yq/operators/select)

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Compare numbers (>)
 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 This returns `true` if the context contains the passed in parameter, and false otherwise.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Array contains array
 Array is equal or subset of

@@ -2,12 +2,6 @@

 This is used to construct objects (or maps). This can be used against existing yaml, or to create fresh yaml documents.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Collect empty object
 Running
 ```bash
@@ -13,11 +13,11 @@ To specify a custom parsing format, use the `with_dtf` operator. The first param
 yq 'with_dtf("myformat"; .a + "3h" | tz("Australia/Melbourne"))'
 ```

-See https://pkg.go.dev/time#pkg-constants for examples of formatting options.
+See the [library docs](https://pkg.go.dev/time#pkg-constants) for examples of formatting options.


 ## Timezones
-This uses golangs built in LoadLocation function to parse timezones strings. See https://pkg.go.dev/time#LoadLocation for more details.
+This uses golangs built in LoadLocation function to parse timezones strings. See the [library docs](https://pkg.go.dev/time#LoadLocation) for more details.


 ## Durations
@@ -25,12 +25,6 @@ Durations are parsed using golangs built in [ParseDuration](https://pkg.go.dev/t

 You can durations to time using the `+` operator.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Format: from standard RFC3339 format
 Providing a single parameter assumes a standard RFC3339 datetime format. If the target format is not a valid yaml datetime format, the result will be a string tagged node.

@@ -156,7 +150,7 @@ a: 2021-01-01T03:10:00Z
 ```

 ## Date subtraction
-You can subtract durations from dates. Assumes RFC3339 date time format, see [date-time operators](https://mikefarah.gitbook.io/yq/operators/date-time-operators) for more information.
+You can subtract durations from dates. Assumes RFC3339 date time format, see [date-time operators](https://mikefarah.gitbook.io/yq/operators/datetime#date-time-formattings) for more information.

 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 Deletes matching entries in maps or arrays.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Delete entry in map
 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 Use the `documentIndex` operator (or the `di` shorthand) to select nodes of a particular document.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Retrieve a document index
 Given a sample.yml file of:
 ```yaml
@@ -9,28 +9,22 @@ These operators are useful to process yaml documents that have stringified embed

 | Format | Decode (from string) | Encode (to string) |
 | --- | -- | --|
-| Yaml | from_yaml | to_yaml(i)/@yaml |
-| JSON | from_json | to_json(i)/@json |
-| Properties | from_props  | to_props/@props |
-| CSV |  | to_csv/@csv |
-| TSV |  | to_tsv/@tsv |
-| XML | from_xml | to_xml(i)/@xml |
+| Yaml | from_yaml/@yamld | to_yaml(i)/@yaml |
+| JSON | from_json/@jsond | to_json(i)/@json |
+| Properties | from_props/@propsd  | to_props/@props |
+| CSV | from_csv/@csvd | to_csv/@csv |
+| TSV | from_tsv/@tsvd | to_tsv/@tsv |
+| XML | from_xml/@xmld | to_xml(i)/@xml |
 | Base64 | @base64d | @base64 |


-CSV and TSV format both accept either a single array or scalars (representing a single row), or an array of array of scalars (representing multiple rows). 
+See CSV and TSV [documentation](https://mikefarah.gitbook.io/yq/usage/csv-tsv) for accepted formats.

 XML uses the `--xml-attribute-prefix` and `xml-content-name` flags to identify attributes and content fields.


 Base64 assumes [rfc4648](https://rfc-editor.org/rfc/rfc4648.html) encoding. Encoding and decoding both assume that the content is a string.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Encode value as json string
 Given a sample.yml file of:
 ```yaml
@@ -132,7 +126,7 @@ a: |-
 ```
 then
 ```bash
-yq '.a |= from_props' sample.yml
+yq '.a |= @propsd' sample.yml
 ```
 will output
 ```yaml
@@ -141,6 +135,42 @@ a:
  dogs: cool as well
 ```

+## Decode csv encoded string
+Given a sample.yml file of:
+```yaml
+a: |-
+  cats,dogs
+  great,cool as well
+```
+then
+```bash
+yq '.a |= @csvd' sample.yml
+```
+will output
+```yaml
+a:
+  - cats: great
+    dogs: cool as well
+```
+
+## Decode tsv encoded string
+Given a sample.yml file of:
+```yaml
+a: |-
+  cats	dogs
+  great	cool as well
+```
+then
+```bash
+yq '.a |= @tsvd' sample.yml
+```
+will output
+```yaml
+a:
+  - cats: great
+    dogs: cool as well
+```
+
 ## Encode value as yaml string
 Indent defaults to 2

@@ -2,12 +2,6 @@

 Similar to the same named functions in `jq` these functions convert to/from an object and an array of key-value pairs. This is most useful for performing operations on keys of maps.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## to_entries Map
 Given a sample.yml file of:
 ```yaml
@@ -107,6 +101,26 @@ KEY_a: 1
 KEY_b: 2
 ```

+## Custom sort map keys
+Use to_entries to convert to an array of key/value pairs, sort the array using sort/sort_by/etc, and convert it back.
+
+Given a sample.yml file of:
+```yaml
+a: 1
+c: 3
+b: 2
+```
+then
+```bash
+yq 'to_entries | sort_by(.key) | reverse | from_entries' sample.yml
+```
+will output
+```yaml
+c: 3
+b: 2
+a: 1
+```
+
 ## Use with_entries to filter the map
 Given a sample.yml file of:
 ```yaml
@@ -30,12 +30,6 @@ yq '(.. | select(tag == "!!str")) |= envsubst' file.yaml
 ```


-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Read string environment variable
 Running
 ```bash
@@ -21,12 +21,6 @@ The not equals `!=` operator returns `false` if the LHS is equal to the RHS.
 - select operator [here](https://mikefarah.gitbook.io/yq/operators/select)


-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Match string
 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 Use this operation to short-circuit expressions. Useful for validation.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Validate a particular value
 Given a sample.yml file of:
 ```yaml
@@ -6,12 +6,6 @@ Use `eval` to dynamically process an expression - for instance from an environme

 Tip: This can be useful way parameterise complex scripts.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Dynamically evaluate a path
 Given a sample.yml file of:
 ```yaml
@@ -10,12 +10,6 @@ Note the use of eval-all to ensure all documents are loaded into memory.
 yq eval-all 'select(fi == 0) * select(filename == "file2.yaml")' file1.yaml file2.yaml
 ```

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Get filename
 Given a sample.yml file of:
 ```yaml
@@ -1,12 +1,6 @@
 # Flatten
 This recursively flattens arrays.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Flatten
 Recursively flattens all arrays

@@ -2,12 +2,6 @@

 This is used to group items in an array by an expression.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Group by field
 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 This is operation that returns true if the key exists in a map (or index in an array), false otherwise.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Has map key
 Given a sample.yml file of:
 ```yaml
@@ -6,4 +6,8 @@ This operator is used to update node values. It can be used in either the:
 Which will assign the LHS node values to the RHS node values. The RHS expression is run against the matching nodes in the pipeline.

 ### relative form: `|=`
-This will do a similar thing to the plain form, however, the RHS expression is run against _the LHS nodes_. This is useful for updating values based on old values, e.g. increment.
+This will do a similar thing to the plain form, however, the RHS expression is run against _the LHS nodes_. This is useful for updating values based on old values, e.g. increment.
+
+
+### Flags
+- `c` clobber custom tags
@@ -1,6 +1,6 @@
 # Comment Operators

-Use these comment operators to set or retrieve comments.
+Use these comment operators to set or retrieve comments. Note that line comments on maps/arrays are actually set on the _key_ node as opposed to the _value_ (map/array). See below for examples.

 Like the `=` and `|=` assign operators, the same syntax applies when updating comments:

@@ -13,11 +13,11 @@ To specify a custom parsing format, use the `with_dtf` operator. The first param
 yq 'with_dtf("myformat"; .a + "3h" | tz("Australia/Melbourne"))'
 ```

-See https://pkg.go.dev/time#pkg-constants for examples of formatting options.
+See the [library docs](https://pkg.go.dev/time#pkg-constants) for examples of formatting options.


 ## Timezones
-This uses golangs built in LoadLocation function to parse timezones strings. See https://pkg.go.dev/time#LoadLocation for more details.
+This uses golangs built in LoadLocation function to parse timezones strings. See the [library docs](https://pkg.go.dev/time#LoadLocation) for more details.


 ## Durations
@@ -9,16 +9,16 @@ These operators are useful to process yaml documents that have stringified embed

 | Format | Decode (from string) | Encode (to string) |
 | --- | -- | --|
-| Yaml | from_yaml | to_yaml(i)/@yaml |
-| JSON | from_json | to_json(i)/@json |
-| Properties | from_props  | to_props/@props |
-| CSV |  | to_csv/@csv |
-| TSV |  | to_tsv/@tsv |
-| XML | from_xml | to_xml(i)/@xml |
+| Yaml | from_yaml/@yamld | to_yaml(i)/@yaml |
+| JSON | from_json/@jsond | to_json(i)/@json |
+| Properties | from_props/@propsd  | to_props/@props |
+| CSV | from_csv/@csvd | to_csv/@csv |
+| TSV | from_tsv/@tsvd | to_tsv/@tsv |
+| XML | from_xml/@xmld | to_xml(i)/@xml |
 | Base64 | @base64d | @base64 |


-CSV and TSV format both accept either a single array or scalars (representing a single row), or an array of array of scalars (representing multiple rows). 
+See CSV and TSV [documentation](https://mikefarah.gitbook.io/yq/usage/csv-tsv) for accepted formats.

 XML uses the `--xml-attribute-prefix` and `xml-content-name` flags to identify attributes and content fields.

@@ -14,6 +14,7 @@ You can control how objects are merged by using one or more of the following fla
 - `d` deeply merge arrays
 - `?` only merge _existing_ fields
 - `n` only merge _new_ fields
+- `c` clobber custom tags


 ### Merge two files together
@@ -1,5 +1,8 @@
 # Path

-The path operator can be used to get the traversal paths of matching nodes in an expression. The path is returned as an array, which if traversed in order will lead to the matching node.
+The `path` operator can be used to get the traversal paths of matching nodes in an expression. The path is returned as an array, which if traversed in order will lead to the matching node.

 You can get the key/index of matching nodes by using the `path` operator to return the path array then piping that through `.[-1]` to get the last element of that array, the key.
+
+Use `setpath` to set a value to the path array returned by `path`, and similarly `delpaths` for an array of path arrays.
+
@@ -11,3 +11,6 @@ diff file1.yml file2.yml
 ```

 Note that `yq` does not yet consider anchors when sorting by keys - this may result in invalid yaml documents if your are using merge anchors.
+
+For more advanced sorting, using `to_entries` to convert the map to an array, then sort/process the array as you like (e.g. using `sort_by`) and convert back to a map using `from_entries`.
+See [here](https://mikefarah.gitbook.io/yq/operators/entries#custom-sort-map-keys) for an example. 
@@ -2,12 +2,6 @@

 Use the `keys` operator to return map keys or array indices. 

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Map keys
 Given a sample.yml file of:
 ```yaml
@@ -118,3 +112,43 @@ will output
 comment on key
 ```

+## Check node is a key
+Given a sample.yml file of:
+```yaml
+a:
+  b:
+    - cat
+  c: frog
+```
+then
+```bash
+yq '[... | { "p": path | join("."), "isKey": is_key, "tag": tag }]' sample.yml
+```
+will output
+```yaml
+- p: ""
+  isKey: false
+  tag: '!!map'
+- p: a
+  isKey: true
+  tag: '!!str'
+- p: a
+  isKey: false
+  tag: '!!map'
+- p: a.b
+  isKey: true
+  tag: '!!str'
+- p: a.b
+  isKey: false
+  tag: '!!seq'
+- p: a.b.0
+  isKey: false
+  tag: '!!str'
+- p: a.c
+  isKey: true
+  tag: '!!str'
+- p: a.c
+  isKey: false
+  tag: '!!str'
+```
+
@@ -2,12 +2,6 @@

 Returns the lengths of the nodes. Length is defined according to the type of the node.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## String length
 returns length of string

@@ -2,12 +2,6 @@

 Returns the line of the matching node. Starts from 1, 0 indicates there was no line data.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Returns line of _value_ node
 Given a sample.yml file of:
 ```yaml
@@ -45,12 +45,6 @@ this.is = a properties file
 bXkgc2VjcmV0IGNoaWxsaSByZWNpcGUgaXMuLi4u
 ```

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Simple example
 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 Maps values of an array. Use `map_values` to map values of an object.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Map array
 Given a sample.yml file of:
 ```yaml
@@ -14,6 +14,7 @@ You can control how objects are merged by using one or more of the following fla
 - `d` deeply merge arrays
 - `?` only merge _existing_ fields
 - `n` only merge _new_ fields
+- `c` clobber custom tags


 ### Merge two files together
@@ -35,12 +36,6 @@ By default - `yq` merge is naive. It merges maps when they match the key name, a
 For more complex array merging (e.g. merging items that match on a certain key) please see the example [here](https://mikefarah.gitbook.io/yq/operators/multiply-merge#merge-arrays-of-objects-together-matching-on-a-key)


-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Multiply integers
 Given a sample.yml file of:
 ```yaml
@@ -481,3 +476,26 @@ b: !goat
  dog: woof
 ```

+## Custom types: clobber tags
+Use the `c` option to clobber custom tags. Note that the second tag is now used
+
+Given a sample.yml file of:
+```yaml
+a: !horse
+  cat: meow
+b: !goat
+  dog: woof
+```
+then
+```bash
+yq '.a *=c .b' sample.yml
+```
+will output
+```yaml
+a: !goat
+  cat: meow
+  dog: woof
+b: !goat
+  dog: woof
+```
+
@@ -2,12 +2,6 @@

 Parent simply returns the parent nodes of the matching nodes.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Simple example
 Given a sample.yml file of:
 ```yaml
@@ -1,14 +1,11 @@
 # Path

-The path operator can be used to get the traversal paths of matching nodes in an expression. The path is returned as an array, which if traversed in order will lead to the matching node.
+The `path` operator can be used to get the traversal paths of matching nodes in an expression. The path is returned as an array, which if traversed in order will lead to the matching node.

 You can get the key/index of matching nodes by using the `path` operator to return the path array then piping that through `.[-1]` to get the last element of that array, the key.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
+Use `setpath` to set a value to the path array returned by `path`, and similarly `delpaths` for an array of path arrays.

-`yq e <exp> <file>`
-{% endhint %}

 ## Map path
 Given a sample.yml file of:
@@ -98,3 +95,114 @@ will output
  value: frog
 ```

+## Set path
+Given a sample.yml file of:
+```yaml
+a:
+  b: cat
+```
+then
+```bash
+yq 'setpath(["a", "b"]; "things")' sample.yml
+```
+will output
+```yaml
+a:
+  b: things
+```
+
+## Set on empty document
+Running
+```bash
+yq --null-input 'setpath(["a", "b"]; "things")'
+```
+will output
+```yaml
+a:
+  b: things
+```
+
+## Set array path
+Given a sample.yml file of:
+```yaml
+a:
+  - cat
+  - frog
+```
+then
+```bash
+yq 'setpath(["a", 0]; "things")' sample.yml
+```
+will output
+```yaml
+a:
+  - things
+  - frog
+```
+
+## Set array path empty
+Running
+```bash
+yq --null-input 'setpath(["a", 0]; "things")'
+```
+will output
+```yaml
+a:
+  - things
+```
+
+## Delete path
+Notice delpaths takes an _array_ of paths.
+
+Given a sample.yml file of:
+```yaml
+a:
+  b: cat
+  c: dog
+  d: frog
+```
+then
+```bash
+yq 'delpaths([["a", "c"], ["a", "d"]])' sample.yml
+```
+will output
+```yaml
+a:
+  b: cat
+```
+
+## Delete array path
+Given a sample.yml file of:
+```yaml
+a:
+  - cat
+  - frog
+```
+then
+```bash
+yq 'delpaths([["a", 0]])' sample.yml
+```
+will output
+```yaml
+a:
+  - frog
+```
+
+## Delete - wrong parameter
+delpaths does not work with a single path array
+
+Given a sample.yml file of:
+```yaml
+a:
+  - cat
+  - frog
+```
+then
+```bash
+yq 'delpaths(["a", 0])' sample.yml
+```
+will output
+```bash
+Error: DELPATHS: expected entry [0] to be a sequence, but its a !!str. Note that delpaths takes an array of path arrays, e.g. [["a", "b"]]
+```
+
@@ -4,12 +4,6 @@ Filter a map by the specified list of keys. Map is returned with the key in the

 Similarly, filter an array by the specified list of indices.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Pick keys from map
 Note that the order of the keys matches the pick order and non existent keys are skipped.

@@ -2,12 +2,6 @@

 Pipe the results of an expression into another. Like the bash operator.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Simple Pipe
 Given a sample.yml file of:
 ```yaml
@@ -19,12 +19,6 @@ For instance to set the `style` of all nodes in a yaml doc, including the map ke
 ```bash
 yq '... style= "flow"' file.yaml
 ```
-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Recurse map (values only)
 Given a sample.yml file of:
 ```yaml
@@ -21,12 +21,6 @@ Reduce syntax in `yq` is a little different from `jq` - as `yq` (currently) isn'

 To that end, the reduce operator is called `ireduce` for backwards compatibility if a `jq` like prefix version of `reduce` is ever added.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Sum numbers
 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 Reverses the order of the items in an array 

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Reverse
 Given a sample.yml file of:
 ```yaml
@@ -8,12 +8,6 @@ Select is used to filter arrays and maps by a boolean expression.
 - comparison (`>=`, `<` etc) operators [here](https://mikefarah.gitbook.io/yq/operators/compare)
 - boolean operators (`and`, `or`, `any` etc) [here](https://mikefarah.gitbook.io/yq/operators/boolean-operators)

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Select elements from array using wildcard prefix
 Given a sample.yml file of:
 ```yaml
@@ -12,11 +12,8 @@ diff file1.yml file2.yml

 Note that `yq` does not yet consider anchors when sorting by keys - this may result in invalid yaml documents if your are using merge anchors.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
+For more advanced sorting, using `to_entries` to convert the map to an array, then sort/process the array as you like (e.g. using `sort_by`) and convert back to a map using `from_entries`.
+See [here](https://mikefarah.gitbook.io/yq/operators/entries#custom-sort-map-keys) for an example. 

 ## Sort keys of map
 Given a sample.yml file of:
@@ -7,12 +7,6 @@ To sort by descending order, pipe the results through the `reverse` operator aft
 Note that at this stage, `yq` only sorts scalar fields.


-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Sort by string field
 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 This operator splits all matches into separate documents

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Split empty
 Running
 ```bash
@@ -56,12 +56,6 @@ IFS= read -rd '' output < <(cat my_file)
 output=$output ./yq '.data.values = strenv(output)' first.yml
 ```

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## To up (upper) case
 Works with unicode characters

@@ -112,6 +106,26 @@ will output
 cat; meow; 1; ; true
 ```

+## Trim strings
+Given a sample.yml file of:
+```yaml
+- ' cat'
+- 'dog '
+- ' cow cow '
+- horse
+```
+then
+```bash
+yq '.[] | trim' sample.yml
+```
+will output
+```yaml
+cat
+dog
+cow cow
+horse
+```
+
 ## Match string
 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 The style operator can be used to get or set the style of nodes (e.g. string style, yaml style)

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Update and set style of a particular node (simple)
 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 You can use subtract to subtract numbers, as well as removing elements from an array.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Array subtraction
 Running
 ```bash
@@ -2,12 +2,6 @@

 The tag operator can be used to get or set the tag of nodes (e.g. `!!str`, `!!int`, `!!bool`).

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Get tag
 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 This is the simplest (and perhaps most used) operator, it is used to navigate deeply into yaml structures.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Simple map navigation
 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 This operator is used to combine different results together.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Combine scalars
 Running
 ```bash
@@ -3,12 +3,6 @@
 This is used to filter out duplicated items in an array. Note that the original order of the array is maintained.


-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Unique array of scalars (string/numbers)
 Note that unique maintains the original order of the array.

@@ -4,12 +4,6 @@ Like the `jq` equivalents, variables are sometimes required for the more complex

 Note that there is also an additional `ref` operator that holds a reference (instead of a copy) of the path, allowing you to make multiple changes to the same path.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Single value variable
 Given a sample.yml file of:
 ```yaml
@@ -2,12 +2,6 @@

 Use the `with` operator to conveniently make multiple updates to a deeply nested path, or to update array elements relatively to each other. The first argument expression sets the root context, and the second expression runs against that root context.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Update and style
 Given a sample.yml file of:
 ```yaml
@@ -1,14 +1,9 @@
 # JSON

-Encode and decode to and from JSON. Note that YAML is a _superset_ of JSON - so `yq` can read any json file without doing anything special.
+Encode and decode to and from JSON. Supports multiple JSON documents in a single file (e.g. NDJSON).

-This means you don't need to 'convert' a JSON file to YAML - however if you want idiomatic YAML styling, then you can use the `-P/--prettyPrint` flag, see examples below.
+Note that YAML is a superset of (single document) JSON - so you don't have to use the JSON parser to read JSON when there is only one JSON document in the input. You will probably want to pretty print the result in this case, to get idiomatic YAML styling.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}

 ## Parse json: simple
 JSON is a subset of yaml, so all you need to do is prettify the output
@@ -130,3 +125,129 @@ will output
 {"whatever":"cat"}
 ```

+## Roundtrip NDJSON
+Unfortunately the json encoder strips leading spaces of values.
+
+Given a sample.json file of:
+```json
+{"this": "is a multidoc json file"}
+{"each": ["line is a valid json document"]}
+{"a number": 4}
+
+```
+then
+```bash
+yq -p=json -o=json -I=0 sample.json
+```
+will output
+```yaml
+{"this":"is a multidoc json file"}
+{"each":["line is a valid json document"]}
+{"a number":4}
+```
+
+## Roundtrip multi-document JSON
+The NDJSON parser can also handle multiple multi-line json documents in a single file!
+
+Given a sample.json file of:
+```json
+{
+	"this": "is a multidoc json file"
+}
+{
+	"it": [
+		"has",
+		"consecutive",
+		"json documents"
+	]
+}
+{
+	"a number": 4
+}
+
+```
+then
+```bash
+yq -p=json -o=json -I=2 sample.json
+```
+will output
+```yaml
+{
+  "this": "is a multidoc json file"
+}
+{
+  "it": [
+    "has",
+    "consecutive",
+    "json documents"
+  ]
+}
+{
+  "a number": 4
+}
+```
+
+## Update a specific document in a multi-document json
+Documents are indexed by the `documentIndex` or `di` operator.
+
+Given a sample.json file of:
+```json
+{"this": "is a multidoc json file"}
+{"each": ["line is a valid json document"]}
+{"a number": 4}
+
+```
+then
+```bash
+yq -p=json -o=json -I=0 '(select(di == 1) | .each ) += "cool"' sample.json
+```
+will output
+```yaml
+{"this":"is a multidoc json file"}
+{"each":["line is a valid json document","cool"]}
+{"a number":4}
+```
+
+## Find and update a specific document in a multi-document json
+Use expressions as you normally would.
+
+Given a sample.json file of:
+```json
+{"this": "is a multidoc json file"}
+{"each": ["line is a valid json document"]}
+{"a number": 4}
+
+```
+then
+```bash
+yq -p=json -o=json -I=0 '(select(has("each")) | .each ) += "cool"' sample.json
+```
+will output
+```yaml
+{"this":"is a multidoc json file"}
+{"each":["line is a valid json document","cool"]}
+{"a number":4}
+```
+
+## Decode NDJSON
+Given a sample.json file of:
+```json
+{"this": "is a multidoc json file"}
+{"each": ["line is a valid json document"]}
+{"a number": 4}
+
+```
+then
+```bash
+yq -p=json sample.json
+```
+will output
+```yaml
+this: is a multidoc json file
+---
+each:
+    - line is a valid json document
+---
+a number: 4
+```
+
@@ -0,0 +1,208 @@
+# CSV
+Encode/Decode/Roundtrip CSV and TSV files.
+
+## Encode 
+Currently supports arrays of homogenous flat objects, that is: no nesting and it assumes the _first_ object has all the keys required:
+
+```yaml
+- name: Bobo
+  type: dog
+- name: Fifi
+  type: cat
+```
+
+As well as arrays of arrays of scalars (strings/numbers/booleans):
+
+```yaml
+- [Bobo, dog]
+- [Fifi, cat]
+```
+
+## Decode
+Decode assumes the first CSV/TSV row is the header row, and all rows beneath are the entries.
+The data will be coded into an array of objects, using the header rows as keys.
+
+```csv
+name,type
+Bobo,dog
+Fifi,cat
+```
+
+
+## Encode CSV simple
+Given a sample.yml file of:
+```yaml
+- [i, like, csv]
+- [because, excel, is, cool]
+```
+then
+```bash
+yq -o=csv sample.yml
+```
+will output
+```csv
+i,like,csv
+because,excel,is,cool
+```
+
+## Encode TSV simple
+Given a sample.yml file of:
+```yaml
+- [i, like, csv]
+- [because, excel, is, cool]
+```
+then
+```bash
+yq -o=tsv sample.yml
+```
+will output
+```tsv
+i	like	csv
+because	excel	is	cool
+```
+
+## Encode array of objects to csv
+Given a sample.yml file of:
+```yaml
+- name: Gary
+  numberOfCats: 1
+  likesApples: true
+  height: 168.8
+- name: Samantha's Rabbit
+  numberOfCats: 2
+  likesApples: false
+  height: -188.8
+
+```
+then
+```bash
+yq -o=csv sample.yml
+```
+will output
+```csv
+name,numberOfCats,likesApples,height
+Gary,1,true,168.8
+Samantha's Rabbit,2,false,-188.8
+```
+
+## Encode array of objects to custom csv format
+Add the header row manually, then the we convert each object into an array of values - resulting in an array of arrays. Pick the columns and call the header whatever you like.
+
+Given a sample.yml file of:
+```yaml
+- name: Gary
+  numberOfCats: 1
+  likesApples: true
+  height: 168.8
+- name: Samantha's Rabbit
+  numberOfCats: 2
+  likesApples: false
+  height: -188.8
+
+```
+then
+```bash
+yq -o=csv '[["Name", "Number of Cats"]] +  [.[] | [.name, .numberOfCats ]]' sample.yml
+```
+will output
+```csv
+Name,Number of Cats
+Gary,1
+Samantha's Rabbit,2
+```
+
+## Encode array of objects to csv - missing fields behaviour
+First entry is used to determine the headers, and it is missing 'likesApples', so it is not included in the csv. Second entry does not have 'numberOfCats' so that is blank
+
+Given a sample.yml file of:
+```yaml
+- name: Gary
+  numberOfCats: 1
+  height: 168.8
+- name: Samantha's Rabbit
+  height: -188.8
+  likesApples: false
+
+```
+then
+```bash
+yq -o=csv sample.yml
+```
+will output
+```csv
+name,numberOfCats,height
+Gary,1,168.8
+Samantha's Rabbit,,-188.8
+```
+
+## Parse CSV into an array of objects
+First row is assumed to be the header row.
+
+Given a sample.csv file of:
+```csv
+name,numberOfCats,likesApples,height
+Gary,1,true,168.8
+Samantha's Rabbit,2,false,-188.8
+
+```
+then
+```bash
+yq -p=csv sample.csv
+```
+will output
+```yaml
+- name: Gary
+  numberOfCats: 1
+  likesApples: true
+  height: 168.8
+- name: Samantha's Rabbit
+  numberOfCats: 2
+  likesApples: false
+  height: -188.8
+```
+
+## Parse TSV into an array of objects
+First row is assumed to be the header row.
+
+Given a sample.tsv file of:
+```tsv
+name	numberOfCats	likesApples	height
+Gary	1	true	168.8
+Samantha's Rabbit	2	false	-188.8
+
+```
+then
+```bash
+yq -p=tsv sample.tsv
+```
+will output
+```yaml
+- name: Gary
+  numberOfCats: 1
+  likesApples: true
+  height: 168.8
+- name: Samantha's Rabbit
+  numberOfCats: 2
+  likesApples: false
+  height: -188.8
+```
+
+## Round trip
+Given a sample.csv file of:
+```csv
+name,numberOfCats,likesApples,height
+Gary,1,true,168.8
+Samantha's Rabbit,2,false,-188.8
+
+```
+then
+```bash
+yq -p=csv -o=csv '(.[] | select(.name == "Gary") | .numberOfCats) = 3' sample.csv
+```
+will output
+```csv
+name,numberOfCats,likesApples,height
+Gary,3,true,168.8
+Samantha's Rabbit,2,false,-188.8
+```
+
@@ -1,5 +1,6 @@
 # JSON

-Encode and decode to and from JSON. Note that YAML is a _superset_ of JSON - so `yq` can read any json file without doing anything special.
+Encode and decode to and from JSON. Supports multiple JSON documents in a single file (e.g. NDJSON).
+
+Note that YAML is a superset of (single document) JSON - so you don't have to use the JSON parser to read JSON when there is only one JSON document in the input. You will probably want to pretty print the result in this case, to get idiomatic YAML styling.

-This means you don't need to 'convert' a JSON file to YAML - however if you want idiomatic YAML styling, then you can use the `-P/--prettyPrint` flag, see examples below.
@@ -0,0 +1,30 @@
+# CSV
+Encode/Decode/Roundtrip CSV and TSV files.
+
+## Encode 
+Currently supports arrays of homogenous flat objects, that is: no nesting and it assumes the _first_ object has all the keys required:
+
+```yaml
+- name: Bobo
+  type: dog
+- name: Fifi
+  type: cat
+```
+
+As well as arrays of arrays of scalars (strings/numbers/booleans):
+
+```yaml
+- [Bobo, dog]
+- [Fifi, cat]
+```
+
+## Decode
+Decode assumes the first CSV/TSV row is the header row, and all rows beneath are the entries.
+The data will be coded into an array of objects, using the header rows as keys.
+
+```csv
+name,type
+Bobo,dog
+Fifi,cat
+```
+
@@ -1,5 +1,5 @@
 # Properties

-Encode to a property file (decode not yet supported). Line comments on value nodes will be copied across.
+Encode/Decode/Roundtrip to/from a property file. Line comments on value nodes will be copied across.

 By default, empty maps and arrays are not encoded - see below for an example on how to encode a value for these.
@@ -4,4 +4,37 @@ Encode and decode to and from XML. Whitespace is not conserved for round trips -

 Consecutive xml nodes with the same name are assumed to be arrays.

-XML content data and attributes are created as fields. This can be controlled by the `'--xml-attribute-prefix` and `--xml-content-name` flags - see below for examples.
+XML content data, attributes processing instructions and directives are all created as plain fields. 
+
+This can be controlled by:
+
+| Flag | Default |Sample XML | 
+| -- | -- |  -- |
+ | `--xml-attribute-prefix` | `+` (changing to `+@` soon) | Legs in ```<cat legs="4"/>``` |  
+ |  `--xml-content-name` | `+content` | Meow in ```<cat>Meow <fur>true</true></cat>``` |
+ | `--xml-directive-name` | `+directive` | ```<!DOCTYPE config system "blah">``` |
+ | `--xml-proc-inst-prefix` | `+p_` |  ```<?xml version="1"?>``` |
+
+
+{% hint style="warning" %}
+Default Attribute Prefix will be changing in v4.30!
+In order to avoid name conflicts (e.g. having an attribute named "content" will create a field that clashes with the default content name of "+content") the attribute prefix will be changing to "+@".
+
+This will affect users that have not set their own prefix and are not roundtripping XML changes.
+
+{% endhint %}
+
+## Encoder / Decoder flag options
+
+In addition to the above flags, there are the following xml encoder/decoder options controlled by flags:
+
+| Flag | Default | Description |
+| -- | -- | -- |
+| `--xml-strict-mode` | false | Strict mode enforces the requirements of the XML specification. When switched off the parser allows input containing common mistakes. See [the Golang xml decoder ](https://pkg.go.dev/encoding/xml#Decoder) for more details.| 
+| `--xml-keep-namespace` | true | Keeps the namespace of attributes |
+| `--xml-raw-token` | true |  Does not verify that start and end elements match and does not translate name space prefixes to their corresponding URLs. |
+| `--xml-skip-proc-inst` | false | Skips over processing instructions, e.g. `<?xml version="1"?>` |
+| `--xml-skip-directives` | false | Skips over directives, e.g. ```<!DOCTYPE config system "blah">``` |
+
+
+See below for examples
@@ -1,15 +1,9 @@
 # Properties

-Encode to a property file (decode not yet supported). Line comments on value nodes will be copied across.
+Encode/Decode/Roundtrip to/from a property file. Line comments on value nodes will be copied across.

 By default, empty maps and arrays are not encoded - see below for an example on how to encode a value for these.

-{% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
-
-`yq e <exp> <file>`
-{% endhint %}
-
 ## Encode properties
 Note that empty arrays and maps are not encoded by default.

@@ -4,14 +4,41 @@ Encode and decode to and from XML. Whitespace is not conserved for round trips -

 Consecutive xml nodes with the same name are assumed to be arrays.

-XML content data and attributes are created as fields. This can be controlled by the `'--xml-attribute-prefix` and `--xml-content-name` flags - see below for examples.
+XML content data, attributes processing instructions and directives are all created as plain fields. 
+
+This can be controlled by:
+
+| Flag | Default |Sample XML | 
+| -- | -- |  -- |
+ | `--xml-attribute-prefix` | `+` (changing to `+@` soon) | Legs in ```<cat legs="4"/>``` |  
+ |  `--xml-content-name` | `+content` | Meow in ```<cat>Meow <fur>true</true></cat>``` |
+ | `--xml-directive-name` | `+directive` | ```<!DOCTYPE config system "blah">``` |
+ | `--xml-proc-inst-prefix` | `+p_` |  ```<?xml version="1"?>``` |
+

 {% hint style="warning" %}
-Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
+Default Attribute Prefix will be changing in v4.30!
+In order to avoid name conflicts (e.g. having an attribute named "content" will create a field that clashes with the default content name of "+content") the attribute prefix will be changing to "+@".
+
+This will affect users that have not set their own prefix and are not roundtripping XML changes.

-`yq e <exp> <file>`
 {% endhint %}

+## Encoder / Decoder flag options
+
+In addition to the above flags, there are the following xml encoder/decoder options controlled by flags:
+
+| Flag | Default | Description |
+| -- | -- | -- |
+| `--xml-strict-mode` | false | Strict mode enforces the requirements of the XML specification. When switched off the parser allows input containing common mistakes. See [the Golang xml decoder ](https://pkg.go.dev/encoding/xml#Decoder) for more details.| 
+| `--xml-keep-namespace` | true | Keeps the namespace of attributes |
+| `--xml-raw-token` | true |  Does not verify that start and end elements match and does not translate name space prefixes to their corresponding URLs. |
+| `--xml-skip-proc-inst` | false | Skips over processing instructions, e.g. `<?xml version="1"?>` |
+| `--xml-skip-directives` | false | Skips over directives, e.g. ```<!DOCTYPE config system "blah">``` |
+
+
+See below for examples
+
 ## Parse xml: simple
 Notice how all the values are strings, see the next example on how you can fix that.

@@ -30,6 +57,7 @@ yq -p=xml '.' sample.xml
 ```
 will output
 ```yaml
+p_xml: version="1.0" encoding="UTF-8"
 cat:
  says: meow
  legs: "4"
@@ -54,6 +82,7 @@ yq -p=xml ' (.. | select(tag == "!!str")) |= from_yaml' sample.xml
 ```
 will output
 ```yaml
+p_xml: version="1.0" encoding="UTF-8"
 cat:
  says: meow
  legs: 4
@@ -75,6 +104,7 @@ yq -p=xml '.' sample.xml
 ```
 will output
 ```yaml
+p_xml: version="1.0" encoding="UTF-8"
 animal:
  - cat
  - goat
@@ -96,6 +126,7 @@ yq -p=xml '.' sample.xml
 ```
 will output
 ```yaml
+p_xml: version="1.0" encoding="UTF-8"
 cat:
  +legs: "4"
  legs: "7"
@@ -115,13 +146,14 @@ yq -p=xml '.' sample.xml
 ```
 will output
 ```yaml
+p_xml: version="1.0" encoding="UTF-8"
 cat:
  +content: meow
  +legs: "4"
 ```

 ## Parse xml: custom dtd
-DTD entities are ignored.
+DTD entities are processed as directives.

 Given a sample.xml file of:
 ```xml
@@ -137,12 +169,45 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -p=xml '.' sample.xml
+yq -p=xml -o=xml '.' sample.xml
 ```
 will output
-```yaml
-root:
-  item: '&writer;&copyright;'
+```xml
+<?xml version="1.0"?>
+<!DOCTYPE root [
+<!ENTITY writer "Blah.">
+<!ENTITY copyright "Blah">
+]>
+<root>
+  <item>&amp;writer;&amp;copyright;</item>
+</root>
+```
+
+## Parse xml: skip custom dtd
+DTDs are directives, skip over directives to skip DTDs.
+
+Given a sample.xml file of:
+```xml
+
+<?xml version="1.0"?>
+<!DOCTYPE root [
+<!ENTITY writer "Blah.">
+<!ENTITY copyright "Blah">
+]>
+<root>
+    <item>&writer;&copyright;</item>
+</root>
+```
+then
+```bash
+yq -p=xml -o=xml --xml-skip-directives '.' sample.xml
+```
+will output
+```xml
+<?xml version="1.0"?>
+<root>
+  <item>&amp;writer;&amp;copyright;</item>
+</root>
 ```

 ## Parse xml: with comments
@@ -207,12 +272,14 @@ yq -p=xml -o=xml --xml-keep-namespace '.' sample.xml
 ```
 will output
 ```xml
+<?xml version="1.0"?>
 <map xmlns="some-namespace" xmlns:xsi="some-instance" some-instance:schemaLocation="some-url"></map>
 ```

 instead of
 ```xml
-<map xmlns="some-namespace" xsi="some-instance" schemaLocation="some-url"></map>
+<?xml version="1.0"?>
+<map xmlns="some-namespace" xmlns:xsi="some-instance" some-instance:schemaLocation="some-url"></map>
 ```

 ## Parse xml: keep raw attribute namespace
@@ -230,11 +297,13 @@ yq -p=xml -o=xml --xml-keep-namespace --xml-raw-token '.' sample.xml
 ```
 will output
 ```xml
-<map xmlns="some-namespace" xmlns:xsi="some-instance" xsi:schemaLocation="some-url"></map>
+<?xml version="1.0"?>
+<map xmlns="some-namespace" xmlns:xsi="some-instance" some-instance:schemaLocation="some-url"></map>
 ```

 instead of
 ```xml
+<?xml version="1.0"?>
 <map xmlns="some-namespace" xsi="some-instance" schemaLocation="some-url"></map>
 ```

@@ -339,6 +408,32 @@ will output
 </cat><!-- below_cat -->
 ```

+## Encode: doctype and xml declaration
+Use the special xml names to add/modify proc instructions and directives.
+
+Given a sample.yml file of:
+```yaml
+p_xml: version="1.0"
+directive: 'DOCTYPE config SYSTEM "/etc/iwatch/iwatch.dtd" '
+apple:
+  +p_coolioo: version="1.0"
+  +directive: 'CATYPE meow purr puss '
+  b: things
+
+```
+then
+```bash
+yq -o=xml '.' sample.yml
+```
+will output
+```xml
+<?xml version="1.0"?>
+<!DOCTYPE config SYSTEM "/etc/iwatch/iwatch.dtd" >
+<apple><?coolioo version="1.0"?><!CATYPE meow purr puss >
+  <b>things</b>
+</apple>
+```
+
 ## Round trip: with comments
 A best effort is made, but comment positions and white space are not preserved perfectly.

@@ -380,3 +475,31 @@ in d before -->
 </cat><!-- after cat -->
 ```

+## Roundtrip: with doctype and declaration
+yq parses XML proc instructions and directives into nodes.
+Unfortunately the underlying XML parser loses whitespace information.
+
+Given a sample.xml file of:
+```xml
+<?xml version="1.0"?>
+<!DOCTYPE config SYSTEM "/etc/iwatch/iwatch.dtd" >
+<apple>
+  <?coolioo version="1.0"?>
+  <!CATYPE meow purr puss >
+  <b>things</b>
+</apple>
+
+```
+then
+```bash
+yq -p=xml -o=xml '.' sample.xml
+```
+will output
+```xml
+<?xml version="1.0"?>
+<!DOCTYPE config SYSTEM "/etc/iwatch/iwatch.dtd" >
+<apple><?coolioo version="1.0"?><!CATYPE meow purr puss >
+  <b>things</b>
+</apple>
+```
+
@@ -66,8 +66,13 @@ func (o *orderedMap) UnmarshalJSON(data []byte) error {
 		}
 		return nil
 	case '[':
-		var arr []orderedMap
-		return json.Unmarshal(data, &arr)
+		var res []*orderedMap
+		if err := json.Unmarshal(data, &res); err != nil {
+			return err
+		}
+		o.altVal = res
+		o.kv = nil
+		return nil
 	}

 	return json.Unmarshal(data, &o.altVal)
@@ -13,7 +13,7 @@ type csvEncoder struct {
 }

 func NewCsvEncoder(separator rune) Encoder {
-	return &csvEncoder{separator}
+	return &csvEncoder{separator: separator}
 }

 func (e *csvEncoder) CanHandleAliases() bool {
@@ -41,6 +41,67 @@ func (e *csvEncoder) encodeRow(csvWriter *csv.Writer, contents []*yaml.Node) err
 	return csvWriter.Write(stringValues)
 }

+func (e *csvEncoder) encodeArrays(csvWriter *csv.Writer, content []*yaml.Node) error {
+	for i, child := range content {
+
+		if child.Kind != yaml.SequenceNode {
+			return fmt.Errorf("csv encoding only works for arrays of scalars (string/numbers/booleans), child[%v] is a %v", i, child.Tag)
+		}
+		err := e.encodeRow(csvWriter, child.Content)
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (e *csvEncoder) extractHeader(child *yaml.Node) ([]*yaml.Node, error) {
+	if child.Kind != yaml.MappingNode {
+		return nil, fmt.Errorf("csv object encoding only works for arrays of flat objects (string key => string/numbers/boolean value), child[0] is a %v", child.Tag)
+	}
+	mapKeys := getMapKeys(child)
+	return mapKeys.Content, nil
+}
+
+func (e *csvEncoder) createChildRow(child *yaml.Node, headers []*yaml.Node) []*yaml.Node {
+	childRow := make([]*yaml.Node, 0)
+	for _, header := range headers {
+		keyIndex := findKeyInMap(child, header)
+		value := createScalarNode(nil, "")
+		if keyIndex != -1 {
+			value = child.Content[keyIndex+1]
+		}
+		childRow = append(childRow, value)
+	}
+	return childRow
+
+}
+
+func (e *csvEncoder) encodeObjects(csvWriter *csv.Writer, content []*yaml.Node) error {
+	headers, err := e.extractHeader(content[0])
+	if err != nil {
+		return nil
+	}
+
+	err = e.encodeRow(csvWriter, headers)
+	if err != nil {
+		return nil
+	}
+
+	for i, child := range content {
+		if child.Kind != yaml.MappingNode {
+			return fmt.Errorf("csv object encoding only works for arrays of flat objects (string key => string/numbers/boolean value), child[%v] is a %v", i, child.Tag)
+		}
+		row := e.createChildRow(child, headers)
+		err = e.encodeRow(csvWriter, row)
+		if err != nil {
+			return err
+		}
+
+	}
+	return nil
+}
+
 func (e *csvEncoder) Encode(writer io.Writer, originalNode *yaml.Node) error {
 	csvWriter := csv.NewWriter(writer)
 	csvWriter.Comma = e.separator
@@ -56,15 +117,10 @@ func (e *csvEncoder) Encode(writer io.Writer, originalNode *yaml.Node) error {
 		return e.encodeRow(csvWriter, node.Content)
 	}

-	for i, child := range node.Content {
-
-		if child.Kind != yaml.SequenceNode {
-			return fmt.Errorf("csv encoding only works for arrays of scalars (string/numbers/booleans), child[%v] is a %v", i, child.Tag)
-		}
-		err := e.encodeRow(csvWriter, child.Content)
-		if err != nil {
-			return err
-		}
+	if node.Content[0].Kind == yaml.MappingNode {
+		return e.encodeObjects(csvWriter, node.Content)
 	}
-	return nil
+
+	return e.encodeArrays(csvWriter, node.Content)
+
 }
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Mike Farah	14ffa90cb6	Merge branch 'master' into xml-proc-inst	2022-10-24 09:57:50 +11:00
Mike Farah	86ef4e4d90	Updated XML acceptance tests with proc inst and directives	2022-10-24 09:54:39 +11:00
Mike Farah	14f827b9b7	Added nix installation instructions	2022-10-24 09:42:22 +11:00
Mike Farah	e4b5769477	Removing old warning, added xml update warning	2022-10-23 14:59:21 +11:00
Mike Farah	eb491e0511	Removing old warning, added xml update warning	2022-10-23 14:58:04 +11:00
Mike Farah	eac988abdc	Updated release to always use latest go	2022-10-23 14:50:00 +11:00
Mike Farah	cb86ec94ff	xml wip	2022-10-23 14:48:57 +11:00
Mike Farah	55383b9ce1	warn about attribute change	2022-10-21 20:46:26 +11:00
Mike Farah	9546eb8939	wip	2022-10-21 15:59:13 +11:00
Mike Farah	585cafc1c0	wip	2022-10-21 15:58:47 +11:00
Mike Farah	ea4a50f6e9	Fixing matt phelps username reference	2022-10-20 09:59:36 +11:00
Mike Farah	6c94869329	test yq action can now be run manually	2022-10-19 12:04:52 +11:00
Mike Farah	5ef9101913	Updated release notes	2022-10-19 11:25:56 +11:00
Mike Farah	1f0881fb5f	Bumping version	2022-10-19 11:14:32 +11:00
Mike Farah	600e132fb6	Actions use built docker-images	2022-10-19 11:10:50 +11:00
Mike Farah	f571b163e5	Merge branch 'action-use-published-docker'	2022-10-19 11:09:06 +11:00
Mike Farah	0b235b367d	action uses built docker image	2022-10-19 11:06:41 +11:00
Mike Farah	a264833c06	test action using built docker image	2022-10-19 11:05:09 +11:00
Mike Farah	22c44d3ecb	action uses built docker image	2022-10-19 11:04:53 +11:00
Mike Farah	8ed817916f	muiltiline github action test	2022-10-19 10:59:09 +11:00
Mike Farah	cb4c41eebf	different name to docker github action	2022-10-19 10:49:04 +11:00
Mike Farah	ecc490a0fa	Attempt to prebuild github action	2022-10-19 10:48:16 +11:00
mattphelps-8451andGitHub	8a45e02cbb	Fix broken multiline strings from `dee0c94` (#1390 ) 1. Escaping behavior changed as a result of set-output deprecation. - Otherwise you'll encounter breaking changes for example "appVersion: "1.0.0"%0Aapplica..." where %0A is escaped newline \n but shouldn't be escaped. 2. Delimeter is required for multiline strings. - See here: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings - Delimeter must be random. UUID is a solid choice. I verified that /proc/sys/kernel/random/uuid does indeed exist on the yq image.	2022-10-19 10:16:07 +11:00
Mike Farah	2e9c91f8a1	wip	2022-10-18 14:56:50 +11:00
Mike Farah	6bbab2a664	Can handle xml directives	2022-10-18 14:33:57 +11:00
Mike Farah	c1b333b2c2	Added xml support for proc instructions	2022-10-18 14:16:05 +11:00
mattphelps-8451andGitHub	28a6c9c532	Fix set-output deprecate; keys are case sensitive (#1383 )	2022-10-18 13:41:58 +11:00
Mike Farah	dee0c94346	Updating action to new entrypoint format	2022-10-17 15:33:12 +11:00
Mike Farah	780ae29c2b	Improved github action test	2022-10-17 15:28:38 +11:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>Mike Farah	9ca20451b7	Bump github.com/spf13/cobra from 1.5.0 to 1.6.0 (#1380 ) * Bump github.com/spf13/cobra from 1.5.0 to 1.6.0 Bumps [github.com/spf13/cobra](https://github.com/spf13/cobra) from 1.5.0 to 1.6.0. - [Release notes](https://github.com/spf13/cobra/releases) - [Commits](https://github.com/spf13/cobra/compare/v1.5.0...v1.6.0) --- updated-dependencies: - dependency-name: github.com/spf13/cobra dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> * Fixed deprecated usage of ExactArgs Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Mike Farah <mikefarah@gmail.com>	2022-10-17 15:15:19 +11:00
Mike Farah	6db7acbf69	Added custom sort map example	2022-10-17 15:03:47 +11:00
Mike Farah	d16ee386d2	Fixed broken link	2022-10-14 14:24:57 +11:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	c3f4bb8156	Bump github.com/alecthomas/repr from 0.1.0 to 0.1.1 (#1379 ) Bumps [github.com/alecthomas/repr](https://github.com/alecthomas/repr) from 0.1.0 to 0.1.1. - [Release notes](https://github.com/alecthomas/repr/releases) - [Commits](https://github.com/alecthomas/repr/compare/v0.1.0...v0.1.1) --- updated-dependencies: - dependency-name: github.com/alecthomas/repr dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2022-10-14 09:33:34 +11:00
Mike Farah	c640888133	Fixed bug - can now delete documents #1377	2022-10-11 11:48:18 +11:00
Mike Farah	33ec66cfdd	Fixed handling of UTF8 encoded CSVs #1373	2022-10-08 13:12:50 +11:00
Mike Farah	1b8d399de4	Detect and fail on missing closing brackets #1366	2022-10-08 12:44:54 +11:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	48c36efe07	Bump golang from 1.19.1 to 1.19.2 (#1375 ) Bumps golang from 1.19.1 to 1.19.2. --- updated-dependencies: - dependency-name: golang dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2022-10-06 15:07:30 +11:00
Mike Farah	f27a3c5c92	Added winget instructions	2022-10-05 20:51:48 +11:00
Mike Farah	ffe635f943	Bumping version	2022-10-05 20:15:02 +11:00
Mike Farah	b5b81abb90	Added DELPATHS operator	2022-10-05 20:09:53 +11:00
Mike Farah	da3f3b93b4	Added SETPATH operator	2022-10-05 14:12:08 +11:00
Mike Farah	7f4c8e1c78	Added comment operator examples	2022-09-30 11:30:31 +10:00
Mike Farah	60f30f8a48	Added comment operator examples	2022-09-30 11:26:36 +10:00
Mike Farah	2362451fda	Added comment operator examples	2022-09-30 11:22:58 +10:00
Mike Farah	55a7fdfd8a	Added is_key operator	2022-09-30 10:27:35 +10:00
Mike Farah	3dd5f0c80c	Added another comment test	2022-09-30 10:15:41 +10:00
Mike Farah	be304a1102	Added another comment test	2022-09-30 09:46:07 +10:00
Mike Farah	a4b60039ca	Added examples of header-preprocess needing to be turned off	2022-09-30 09:36:38 +10:00
Mike Farah	b20477210f	Added missing validation for adding sequences to maps #1341	2022-09-16 10:04:48 +10:00
Mike Farah	9b6961875e	Bumping version	2022-09-09 12:29:41 +10:00
Mike Farah	51b64e6cf3	Fixing relative merge bug #1333	2022-09-09 12:28:38 +10:00
Mike Farah	851d93e5a8	Bumping version	2022-09-09 11:23:14 +10:00
Mike Farah	9291865eed	Preparing release notes	2022-09-09 11:21:53 +10:00
Mike Farah	fb330ebcb0	Updated github action to run as root	2022-09-09 11:14:25 +10:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	ae7a48df2d	Bump github.com/elliotchance/orderedmap from 1.4.0 to 1.5.0 (#1331 ) Bumps [github.com/elliotchance/orderedmap](https://github.com/elliotchance/orderedmap) from 1.4.0 to 1.5.0. - [Release notes](https://github.com/elliotchance/orderedmap/releases) - [Commits](https://github.com/elliotchance/orderedmap/compare/v1.4.0...v1.5.0) --- updated-dependencies: - dependency-name: github.com/elliotchance/orderedmap dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2022-09-09 11:05:46 +10:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2e3c50c535	Bump golang from 1.19.0 to 1.19.1 (#1330 ) Bumps golang from 1.19.0 to 1.19.1. --- updated-dependencies: - dependency-name: golang dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2022-09-09 11:05:36 +10:00
Mike Farah	a64eea3b1a	Fixed bug in alternative op, dont evaluate RHS if LHS is truthy	2022-09-09 11:05:12 +10:00
AbirdcflyandGitHub	a12c1a6610	chore: remove duplicate word in doc (#1322 ) Signed-off-by: Abirdcfly <fp544037857@gmail.com> Signed-off-by: Abirdcfly <fp544037857@gmail.com>	2022-08-31 18:43:03 +10:00
Mike Farah	bf6b4d3941	Fixed footer comment issue #1321	2022-08-30 11:24:26 +10:00
Mike Farah	3d11b0545d	Bumping version	2022-08-29 15:41:07 +10:00
Mike Farah	b4ca184108	Added new "c" flag to clobber custom tags when needed	2022-08-29 15:38:21 +10:00
Mike Farah	b1a40a9fb7	Bumped go compiler; bumped quality tools	2022-08-29 14:13:15 +10:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	187d9523c6	Bump github.com/goccy/go-json from 0.9.10 to 0.9.11 (#1314 ) Bumps [github.com/goccy/go-json](https://github.com/goccy/go-json) from 0.9.10 to 0.9.11. - [Release notes](https://github.com/goccy/go-json/releases) - [Changelog](https://github.com/goccy/go-json/blob/master/CHANGELOG.md) - [Commits](https://github.com/goccy/go-json/compare/v0.9.10...v0.9.11) --- updated-dependencies: - dependency-name: github.com/goccy/go-json dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2022-08-25 13:41:11 +10:00
Matti SchneiderandGitHub	a44938101d	Document dynamic get and output in GitHub Action (#1303 )	2022-08-14 10:40:41 +10:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	a4634cdc86	Bump github.com/alecthomas/participle/v2 (#1302 ) Bumps [github.com/alecthomas/participle/v2](https://github.com/alecthomas/participle) from 2.0.0-beta.4 to 2.0.0-beta.5. - [Release notes](https://github.com/alecthomas/participle/releases) - [Changelog](https://github.com/alecthomas/participle/blob/master/CHANGES.md) - [Commits](https://github.com/alecthomas/participle/compare/v2.0.0-beta.4...v2.0.0-beta.5) --- updated-dependencies: - dependency-name: github.com/alecthomas/participle/v2 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2022-08-11 13:47:22 +10:00
Mike Farah	a696dceea4	Added string trim operator	2022-08-08 13:35:57 +10:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	989dabac5a	Bump golang from 1.18.4 to 1.19.0 (#1292 ) Bumps golang from 1.18.4 to 1.19.0. --- updated-dependencies: - dependency-name: golang dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2022-08-04 14:23:20 +10:00
Mike Farah	8eac186a35	Add link to discussions on readme	2022-08-01 16:55:55 +10:00
Mike Farah	1c7dc0e88a	Bug fix	2022-08-01 16:27:42 +10:00
Mike Farah	2c9b5be408	Fixed json decode to maintain key order	2022-08-01 16:26:43 +10:00
Mike Farah	a91a8ccc66	Improving docs	2022-08-01 14:12:35 +10:00
Mike Farah	6dfef716d7	Bumping version	2022-08-01 14:00:13 +10:00
Mike Farah	06a2b9d426	updating release notes	2022-08-01 13:47:24 +10:00
Mike Farah	6cd0892d59	Added SELinux note #1289	2022-08-01 13:47:16 +10:00
Mike Farah	51b3985aa0	Preparing release notes	2022-08-01 13:40:41 +10:00
Mike FarahandGitHub	c8815f5ab9	Csv decoder (#1290 ) * WIP: adding CSV decoder * Adding CSV decoder * Added CSV roundtrip * Fixing from review	2022-08-01 10:28:34 +10:00
Jih-Wei, LiangandGitHub	3c222d8707	Added StringEvaluator for evaluating string input #1266 (#1278 )	2022-08-01 08:50:56 +10:00
Mike Farah	4508bc2dc2	Updating release notes for next release	2022-07-29 10:28:06 +10:00
Mike Farah	8c3a8c085e	Fixes xml decode missing tags #1284	2022-07-29 10:26:50 +10:00
Mike FarahandGitHub	b9a1ef89fe	Added NDJSON decoder (#1281 )	2022-07-27 12:26:22 +10:00
Mike Farah	c2c48bbe1d	Bumping version	2022-07-15 10:27:18 +10:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	97f89c0edb	Bump golang from 1.18.3 to 1.18.4 (#1273 ) Bumps golang from 1.18.3 to 1.18.4. --- updated-dependencies: - dependency-name: golang dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2022-07-14 15:38:26 +10:00
Mike FarahandGitHub	03ba38eaff	Using new lexer by alecthomas! (#1270 )	2022-07-13 14:45:28 +10:00