Multiply, substract with custom types

* refactor: move from io/ioutil to io and os packages

The io/ioutil package has been deprecated as of Go 1.16, see
https://golang.org/doc/go1.16#ioutil. This commit replaces the existing
io/ioutil functions with their new definitions in io and os packages.

Signed-off-by: Eng Zer Jun <engzerjun@gmail.com>

* build: update snapcraft `go-channel` to 1.17

Signed-off-by: Eng Zer Jun <engzerjun@gmail.com>

.gitignore

@@ -48,4 +48,8 @@ test*.yml
 
 # man page
 man.md
-yq.1
+yq.1
+
+# debian pkg
+_build
+debian/files

.golangci.yml

@@ -18,6 +18,14 @@ linters:
     - revive
     - unconvert
     - unparam
+linters-settings:
+  depguard:
+    list-type: blacklist
+    include-go-root: true
+    packages:
+      - io/ioutil
+    packages-with-error-message:
+      - io/ioutil: "The 'io/ioutil' package is deprecated. Use corresponding 'os' or 'io' functions instead."
 issues:
   exclude-rules:
   - linters:

LICENSE

@@ -1,3 +1,5 @@
+The MIT License (MIT)
+
 Copyright (c) 2017 Mike Farah
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

README.md

@@ -3,7 +3,7 @@
 ![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)
 
 
-a lightweight and portable command-line YAML processor. `yq` uses [jq](https://github.com/stedolan/jq) like syntax but works with yaml files as well as json. 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 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.
 
 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.
 
@@ -104,6 +104,9 @@ rm /etc/myfile.tmp
 docker run --rm -v "${PWD}":/workdir mikefarah/yq <command> [flags] [expression ]FILE...
 ```
 
+Note that you can run `yq` in docker without network access and other privileges if you desire,
+namely `--security-opt=no-new-privileges --cap-drop all --network none`.
+
 ```bash
 podman run --rm -v "${PWD}":/workdir mikefarah/yq <command> [flags] [expression ]FILE...
 ```
@@ -195,6 +198,12 @@ webi yq
 See [webi](https://webinstall.dev/)
 Supported by @adithyasunil26 (https://github.com/webinstall/webi-installers/tree/master/yq)
 
+### Arch Linux
+
+```
+pacman -S go-yq
+```
+
 ### Windows:
 [![Chocolatey](https://img.shields.io/chocolatey/v/yq.svg)](https://chocolatey.org/packages/yq)
 [![Chocolatey](https://img.shields.io/chocolatey/dt/yq.svg)](https://chocolatey.org/packages/yq)
@@ -232,19 +241,21 @@ Supported by @rmescandon (https://launchpad.net/~rmescandon/+archive/ubuntu/yq)
 ## Features
 - [Detailed documentation with many examples](https://mikefarah.gitbook.io/yq/)
 - Written in portable go, so you can download a lovely dependency free binary
-- Uses similar syntax as `jq` but works with YAML and JSON files
+- Uses similar syntax as `jq` but works with YAML, [JSON](https://mikefarah.gitbook.io/yq/usage/convert) and [XML](https://mikefarah.gitbook.io/yq/usage/xml) files
 - Fully supports multi document yaml files
 - Supports yaml [front matter](https://mikefarah.gitbook.io/yq/usage/front-matter) blocks (e.g. jekyll/assemble)
 - Colorized yaml output
-- [Deeply traverse yaml](https://mikefarah.gitbook.io/yq/operators/traverse-read)
-- [Sort yaml by keys](https://mikefarah.gitbook.io/yq/operators/sort-keys)
+- [Deeply data structures](https://mikefarah.gitbook.io/yq/operators/traverse-read)
+- [Sort keys](https://mikefarah.gitbook.io/yq/operators/sort-keys)
 - Manipulate yaml [comments](https://mikefarah.gitbook.io/yq/operators/comment-operators), [styling](https://mikefarah.gitbook.io/yq/operators/style), [tags](https://mikefarah.gitbook.io/yq/operators/tag) and [anchors and aliases](https://mikefarah.gitbook.io/yq/operators/anchor-and-alias-operators).
-- [Update yaml inplace](https://mikefarah.gitbook.io/yq/v/v4.x/commands/evaluate#flags)
+- [Update inplace](https://mikefarah.gitbook.io/yq/v/v4.x/commands/evaluate#flags)
 - [Complex expressions to select and update](https://mikefarah.gitbook.io/yq/operators/select#select-and-update-matching-values-in-map)
 - Keeps yaml formatting and comments when updating (though there are issues with whitespace)
 - [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 xml](https://mikefarah.gitbook.io/yq/v/v4.x/usage/xml)
 - [Convert to properties](https://mikefarah.gitbook.io/yq/v/v4.x/usage/properties)
+- [Convert to csv/tsv](https://mikefarah.gitbook.io/yq/usage/csv-tsv)
 - [Pipe data in by using '-'](https://mikefarah.gitbook.io/yq/v/v4.x/commands/evaluate)
 - [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.
@@ -260,27 +271,32 @@ Usage:
   yq [command]
 
 Available Commands:
+  completion       Generate the autocompletion script for the specified shell
   eval             Apply the expression to each document in each yaml file in sequence
   eval-all         Loads _all_ yaml documents of _all_ yaml files and runs expression once
   help             Help about any command
   shell-completion Generate completion script
 
 Flags:
-  -C, --colors                force print with colors
-  -e, --exit-status           set exit status if there are no matches or null or false is returned
-  -f, --front-matter string   (extract|process) first input as yaml front-matter. Extract will pull out the yaml content, process will run the expression against the yaml content, leaving the remaining data intact
-      --header-preprocess     Slurp any header comments and seperators before processing expression. This is a workaround for go-yaml to persist header content (default true)
-  -h, --help                  help for yq
-  -I, --indent int            sets indent level for output (default 2)
-  -i, --inplace               update the yaml file inplace of first yaml file given.
-  -M, --no-colors             force print with no colors
-  -N, --no-doc                Don't print document separators (---)
-  -n, --null-input            Don't read input, simply evaluate the expression given. Useful for creating yaml docs from scratch.
-  -o, --output-format string  [yaml|y|json|j|props|p] output format type. (default "yaml")
-  -P, --prettyPrint           pretty print, shorthand for '... style = ""'
-      --unwrapScalar          unwrap scalar, print the value with no quotes, colors or comments (default true)
-  -v, --verbose               verbose mode
-  -V, --version               Print version information and quit
+  -C, --colors                        force print with colors
+  -e, --exit-status                   set exit status if there are no matches or null or false is returned
+  -f, --front-matter string           (extract|process) first input as yaml front-matter. Extract will pull out the yaml content, process will run the expression against the yaml content, leaving the remaining data intact
+      --header-preprocess             Slurp any header comments and separators before processing expression. (default true)
+  -h, --help                          help for yq
+  -I, --indent int                    sets indent level for output (default 2)
+  -i, --inplace                       update the file inplace of first file given.
+  -p, --input-format string           [yaml|y|xml|x] parse format for input. Note that json is a subset of yaml. (default "yaml")
+  -M, --no-colors                     force print with no colors
+  -N, --no-doc                        Don't print document separators (---)
+  -n, --null-input                    Don't read input, simply evaluate the expression given. Useful for creating docs from scratch.
+  -o, --output-format string          [yaml|y|json|j|props|p|xml|x] output format type. (default "yaml")
+  -P, --prettyPrint                   pretty print, shorthand for '... style = ""'
+  -s, --split-exp string              print each result (or doc) into a file named (exp). [exp] argument must return a string. You can use $index in the expression as the result counter.
+      --unwrapScalar                  unwrap scalar, print the value with no quotes, colors or comments (default true)
+  -v, --verbose                       verbose mode
+  -V, --version                       Print version information and quit
+      --xml-attribute-prefix string   prefix for xml attributes (default "+")
+      --xml-content-name string       name for xml content (if no attribute name is present). (default "+content")
 
 Use "yq [command] --help" for more information about a command.
 ```

acceptance_tests/inputs-format.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+setUp() {
+  rm test*.yml || true
+}
+
+testInputXml() {
+  cat >test.yml <<EOL
+<cat legs="4">BiBi</cat>
+EOL
+
+  read -r -d '' expected << EOM
+cat:
+  +content: BiBi
+  +legs: "4"
+EOM
+
+  X=$(./yq e -p=xml test.yml)
+  assertEquals "$expected" "$X"
+
+  X=$(./yq ea -p=xml test.yml)
+  assertEquals "$expected" "$X"
+}
+
+source ./scripts/shunit2

acceptance_tests/output-format.sh

@@ -102,4 +102,65 @@ EOM
   assertEquals "$expected" "$X"
 }
 
+testOutputXml() {
+  cat >test.yml <<EOL
+a: {b: {c: ["cat"]}}
+EOL
+
+  read -r -d '' expected << EOM
+<a>
+  <b>
+    <c>cat</c>
+  </b>
+</a>
+EOM
+
+  X=$(./yq e --output-format=xml test.yml)
+  assertEquals "$expected" "$X"
+
+  X=$(./yq ea --output-format=xml test.yml)
+  assertEquals "$expected" "$X"
+}
+
+testOutputXmlShort() {
+  cat >test.yml <<EOL
+a: {b: {c: ["cat"]}}
+EOL
+
+  read -r -d '' expected << EOM
+<a>
+  <b>
+    <c>cat</c>
+  </b>
+</a>
+EOM
+
+  X=$(./yq e --output-format=x test.yml)
+  assertEquals "$expected" "$X"
+
+  X=$(./yq ea --output-format=x test.yml)
+  assertEquals "$expected" "$X"
+}
+
+testOutputXmComplex() {
+  cat >test.yml <<EOL
+a: {b: {c: ["cat", "dog"], +f: meow}}
+EOL
+
+  read -r -d '' expected << EOM
+<a>
+  <b f="meow">
+    <c>cat</c>
+    <c>dog</c>
+  </b>
+</a>
+EOM
+
+  X=$(./yq e --output-format=x test.yml)
+  assertEquals "$expected" "$X"
+
+  X=$(./yq ea --output-format=x test.yml)
+  assertEquals "$expected" "$X"
+}
+
 source ./scripts/shunit2

cmd/constant.go

@@ -6,6 +6,10 @@ var unwrapScalar = true
 var writeInplace = false
 var outputToJSON = false
 var outputFormat = "yaml"
+var inputFormat = "yaml"
+
+var xmlAttributePrefix = "+"
+var xmlContentName = "+content"
 
 var exitStatus = false
 var forceColor = false

cmd/evaluate_all_command.go

@@ -39,7 +39,7 @@ Note that it consumes more memory than eval.
 	}
 	return cmdEvalAll
 }
-func evaluateAll(cmd *cobra.Command, args []string) error {
+func evaluateAll(cmd *cobra.Command, args []string) (cmdError error) {
 	// 0 args, read std in
 	// 1 arg, null input, process expression
 	// 1 arg, read file in sequence
@@ -67,7 +67,11 @@ func evaluateAll(cmd *cobra.Command, args []string) error {
 		}
 		// need to indirectly call the function so  that completedSuccessfully is
 		// passed when we finish execution as opposed to now
-		defer func() { writeInPlaceHandler.FinishWriteInPlace(completedSuccessfully) }()
+		defer func() {
+			if cmdError == nil {
+				cmdError = writeInPlaceHandler.FinishWriteInPlace(completedSuccessfully)
+			}
+		}()
 	}
 
 	format, err := yqlib.OutputFormatFromString(outputFormat)
@@ -75,9 +79,15 @@ func evaluateAll(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	printerWriter := configurePrinterWriter(format, out)
+	decoder, err := configureDecoder()
+	if err != nil {
+		return err
+	}
 
-	printer := yqlib.NewPrinter(printerWriter, format, unwrapScalar, colorsEnabled, indent, !noDocSeparators)
+	printerWriter := configurePrinterWriter(format, out)
+	encoder := configureEncoder(format)
+
+	printer := yqlib.NewPrinter(encoder, printerWriter)
 
 	if frontMatter != "" {
 		frontMatterHandler := yqlib.NewFrontMatterHandler(args[firstFileIndex])
@@ -99,7 +109,7 @@ func evaluateAll(cmd *cobra.Command, args []string) error {
 	switch len(args) {
 	case 0:
 		if pipingStdIn {
-			err = allAtOnceEvaluator.EvaluateFiles(processExpression(""), []string{"-"}, printer, leadingContentPreProcessing)
+			err = allAtOnceEvaluator.EvaluateFiles(processExpression(""), []string{"-"}, printer, leadingContentPreProcessing, decoder)
 		} else {
 			cmd.Println(cmd.UsageString())
 			return nil
@@ -108,10 +118,10 @@ func evaluateAll(cmd *cobra.Command, args []string) error {
 		if nullInput {
 			err = yqlib.NewStreamEvaluator().EvaluateNew(processExpression(args[0]), printer, "")
 		} else {
-			err = allAtOnceEvaluator.EvaluateFiles(processExpression(""), []string{args[0]}, printer, leadingContentPreProcessing)
+			err = allAtOnceEvaluator.EvaluateFiles(processExpression(""), []string{args[0]}, printer, leadingContentPreProcessing, decoder)
 		}
 	default:
-		err = allAtOnceEvaluator.EvaluateFiles(processExpression(args[0]), args[1:], printer, leadingContentPreProcessing)
+		err = allAtOnceEvaluator.EvaluateFiles(processExpression(args[0]), args[1:], printer, leadingContentPreProcessing, decoder)
 	}
 
 	completedSuccessfully = err == nil

cmd/evalute_sequence_command.go

@@ -44,16 +44,16 @@ expression and prints the result in sequence.`,
 }
 
 func processExpression(expression string) string {
-	var prettyPrintExp = `(... | (select(tag != "!!str"), select(tag == "!!str") | select(test("(?i)^(y|yes|n|no|on|off)$") | not))  ) style=""`
+
 	if prettyPrint && expression == "" {
-		return prettyPrintExp
+		return yqlib.PrettyPrintExp
 	} else if prettyPrint {
-		return fmt.Sprintf("%v | %v", expression, prettyPrintExp)
+		return fmt.Sprintf("%v | %v", expression, yqlib.PrettyPrintExp)
 	}
 	return expression
 }
 
-func evaluateSequence(cmd *cobra.Command, args []string) error {
+func evaluateSequence(cmd *cobra.Command, args []string) (cmdError error) {
 	// 0 args, read std in
 	// 1 arg, null input, process expression
 	// 1 arg, read file in sequence
@@ -80,7 +80,11 @@ func evaluateSequence(cmd *cobra.Command, args []string) error {
 		}
 		// need to indirectly call the function so  that completedSuccessfully is
 		// passed when we finish execution as opposed to now
-		defer func() { writeInPlaceHandler.FinishWriteInPlace(completedSuccessfully) }()
+		defer func() {
+			if cmdError == nil {
+				cmdError = writeInPlaceHandler.FinishWriteInPlace(completedSuccessfully)
+			}
+		}()
 	}
 
 	format, err := yqlib.OutputFormatFromString(outputFormat)
@@ -89,8 +93,14 @@ func evaluateSequence(cmd *cobra.Command, args []string) error {
 	}
 
 	printerWriter := configurePrinterWriter(format, out)
+	encoder := configureEncoder(format)
 
-	printer := yqlib.NewPrinter(printerWriter, format, unwrapScalar, colorsEnabled, indent, !noDocSeparators)
+	printer := yqlib.NewPrinter(encoder, printerWriter)
+
+	decoder, err := configureDecoder()
+	if err != nil {
+		return err
+	}
 
 	streamEvaluator := yqlib.NewStreamEvaluator()
 
@@ -113,7 +123,7 @@ func evaluateSequence(cmd *cobra.Command, args []string) error {
 	switch len(args) {
 	case 0:
 		if pipingStdIn {
-			err = streamEvaluator.EvaluateFiles(processExpression(""), []string{"-"}, printer, leadingContentPreProcessing)
+			err = streamEvaluator.EvaluateFiles(processExpression(""), []string{"-"}, printer, leadingContentPreProcessing, decoder)
 		} else {
 			cmd.Println(cmd.UsageString())
 			return nil
@@ -122,10 +132,10 @@ func evaluateSequence(cmd *cobra.Command, args []string) error {
 		if nullInput {
 			err = streamEvaluator.EvaluateNew(processExpression(args[0]), printer, "")
 		} else {
-			err = streamEvaluator.EvaluateFiles(processExpression(""), []string{args[0]}, printer, leadingContentPreProcessing)
+			err = streamEvaluator.EvaluateFiles(processExpression(""), []string{args[0]}, printer, leadingContentPreProcessing, decoder)
 		}
 	default:
-		err = streamEvaluator.EvaluateFiles(processExpression(args[0]), args[1:], printer, leadingContentPreProcessing)
+		err = streamEvaluator.EvaluateFiles(processExpression(args[0]), args[1:], printer, leadingContentPreProcessing, decoder)
 	}
 	completedSuccessfully = err == nil
 

cmd/root.go

@@ -3,6 +3,7 @@ package cmd
 import (
 	"os"
 
+	"github.com/mikefarah/yq/v4/pkg/yqlib"
 	"github.com/spf13/cobra"
 	logging "gopkg.in/op/go-logging.v1"
 )
@@ -37,6 +38,8 @@ See https://mikefarah.gitbook.io/yq/ for detailed documentation and examples.`,
 			}
 
 			logging.SetBackend(backend)
+			yqlib.XmlPreferences.AttributePrefix = xmlAttributePrefix
+			yqlib.XmlPreferences.ContentName = xmlContentName
 		},
 	}
 
@@ -48,13 +51,18 @@ See https://mikefarah.gitbook.io/yq/ for detailed documentation and examples.`,
 		panic(err)
 	}
 
-	rootCmd.PersistentFlags().StringVarP(&outputFormat, "output-format", "o", "yaml", "[yaml|y|json|j|props|p] output format type.")
-	rootCmd.PersistentFlags().BoolVarP(&nullInput, "null-input", "n", false, "Don't read input, simply evaluate the expression given. Useful for creating yaml docs from scratch.")
+	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|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().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 (---)")
 
 	rootCmd.PersistentFlags().IntVarP(&indent, "indent", "I", 2, "sets indent level for output")
 	rootCmd.Flags().BoolVarP(&version, "version", "V", false, "Print version information and quit")
-	rootCmd.PersistentFlags().BoolVarP(&writeInplace, "inplace", "i", false, "update the yaml file inplace of first yaml file given.")
+	rootCmd.PersistentFlags().BoolVarP(&writeInplace, "inplace", "i", false, "update the file inplace of first file given.")
 	rootCmd.PersistentFlags().BoolVarP(&unwrapScalar, "unwrapScalar", "", true, "unwrap scalar, print the value with no quotes, colors or comments")
 	rootCmd.PersistentFlags().BoolVarP(&prettyPrint, "prettyPrint", "P", false, "pretty print, shorthand for '... style = \"\"'")
 	rootCmd.PersistentFlags().BoolVarP(&exitStatus, "exit-status", "e", false, "set exit status if there are no matches or null or false is returned")
@@ -62,7 +70,7 @@ See https://mikefarah.gitbook.io/yq/ for detailed documentation and examples.`,
 	rootCmd.PersistentFlags().BoolVarP(&forceColor, "colors", "C", false, "force print with colors")
 	rootCmd.PersistentFlags().BoolVarP(&forceNoColor, "no-colors", "M", false, "force print with no colors")
 	rootCmd.PersistentFlags().StringVarP(&frontMatter, "front-matter", "f", "", "(extract|process) first input as yaml front-matter. Extract will pull out the yaml content, process will run the expression against the yaml content, leaving the remaining data intact")
-	rootCmd.PersistentFlags().BoolVarP(&leadingContentPreProcessing, "header-preprocess", "", true, "Slurp any header comments and separators before processing expression. This is a workaround for go-yaml to persist header content properly.")
+	rootCmd.PersistentFlags().BoolVarP(&leadingContentPreProcessing, "header-preprocess", "", true, "Slurp any header comments and separators before processing expression.")
 
 	rootCmd.PersistentFlags().StringVarP(&splitFileExp, "split-exp", "s", "", "print each result (or doc) into a file named (exp). [exp] argument must return a string. You can use $index in the expression as the result counter.")
 

cmd/utils.go

@@ -45,6 +45,18 @@ func initCommand(cmd *cobra.Command, args []string) (firstFileIndex int, err err
 	return firstFileIndex, nil
 }
 
+func configureDecoder() (yqlib.Decoder, error) {
+	yqlibInputFormat, err := yqlib.InputFormatFromString(inputFormat)
+	if err != nil {
+		return nil, err
+	}
+	switch yqlibInputFormat {
+	case yqlib.XmlInputFormat:
+		return yqlib.NewXmlDecoder(xmlAttributePrefix, xmlContentName), nil
+	}
+	return yqlib.NewYamlDecoder(), nil
+}
+
 func configurePrinterWriter(format yqlib.PrinterOutputFormat, out io.Writer) yqlib.PrinterWriter {
 
 	var printerWriter yqlib.PrinterWriter
@@ -61,3 +73,21 @@ func configurePrinterWriter(format yqlib.PrinterOutputFormat, out io.Writer) yql
 	}
 	return printerWriter
 }
+
+func configureEncoder(format yqlib.PrinterOutputFormat) yqlib.Encoder {
+	switch format {
+	case yqlib.JsonOutputFormat:
+		return yqlib.NewJsonEncoder(indent)
+	case yqlib.PropsOutputFormat:
+		return yqlib.NewPropertiesEncoder()
+	case yqlib.CsvOutputFormat:
+		return yqlib.NewCsvEncoder(',')
+	case yqlib.TsvOutputFormat:
+		return yqlib.NewCsvEncoder('\t')
+	case yqlib.YamlOutputFormat:
+		return yqlib.NewYamlEncoder(indent, colorsEnabled, !noDocSeparators, unwrapScalar)
+	case yqlib.XmlOutputFormat:
+		return yqlib.NewXmlEncoder(indent, xmlAttributePrefix, xmlContentName)
+	}
+	panic("invalid encoder")
+}

cmd/version.go

@@ -11,7 +11,7 @@ var (
 	GitDescribe string
 
 	// Version is main version number that is being run at the moment.
-	Version = "4.16.2"
+	Version = "4.17.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

debian/changelog

@@ -1,3 +1,112 @@
+yq (4.16.2) focal; urgency=medium
+
+  * Fixed with semicolon space issue
+  * Updating with documentation
+  * Added STDIN example to the top
+  * minor readme cleanup
+  * Help text tweak
+  * Fixed docker timeout - simplify docker builds
+  * New release with docker build fixes
+  * Updating to go 1.17 to fix CVE #944
+  * Fix a typo in root.go
+  * Skip the tests if the nocheck Debian build option is specified
+  * Fixed select bug (#958)
+  * Sped up explode operator
+  * Slight performance improvement to context.ChildContext
+  * Speed up multiply
+  * Update README with recently added / changed options
+  * Make deepMatch report in linear time
+  * Removed leadingContentPreProcessing flag - header preprocessing is stable
+  * Revert "Removed leadingContentPreProcessing flag - header preprocessing is stable"
+  * Keep flag, it is needed in corner cases
+  * Updated Readme
+  * Man page
+  * Fixed expression parsing bug #970
+  * Bumping go-lang, docker versions
+  * Added test release flow
+  * Updated github action release to generate man page
+  * Bumping version
+  * Removing no longer needed github action
+  * Added decoder op
+  * Fixed newline handling when decoding/encoding
+  * Fixed newline handling in encoder/decoder
+  * Can specify indent in encode ops
+  * Added group_by operator
+  * Added flatten operator
+  * Fixed flatten error message
+  * Improving docs
+  * Split printer
+  * Refactored command logic
+  * Fix JSON encoding removing null #985
+  * Fixed acceptance tests
+  * gitbook
+  * Update document generation script
+  * Updating README
+  * Updating release instructions
+  * github action no longer uses data1.yml
+  * Create dependabot.yml
+  * Bump actions/create-release from 1.0.0 to 1.1.4
+  * Bump actions/setup-go from 1 to 2.1.4
+  * Bump github.com/goccy/go-yaml from 1.8.9 to 1.9.4
+  * Bump github.com/jinzhu/copier from 0.2.8 to 0.3.2
+  * Bump github.com/fatih/color from 1.10.0 to 1.13.0
+  * Bump github.com/spf13/cobra from 1.1.3 to 1.2.1
+  * Update dependabot.yml
+  * Update go.yml
+  * add build check to PRs
+  * Include secure as part of build process
+  * Fixing bad label in github action
+  * fixed printer test
+  * remove leading content indicator
+  * Fixed header preprocessing!
+  * lint : define golangci configuration file
+  * Update check.sh
+  * Load file acceptance test
+  * Minor improvement on handling front matter
+  * Improved load doc
+  * feature: detect MANPATh and install there
+  * Update install-man-page.sh
+  * simplify prod stage, move version label to action
+  * add labels, quote some values
+  * enable errorlint linter
+  * Added errorlint to devtools
+  * Added key operator
+  * Added more tests
+  * Fixing comments
+  * Attempt to fix golint problem
+  * Include version query for tools
+  * Clean up errored file?
+  * enable misspell linter
+  * updated readme
+  * update Golangci version to v1.43.0
+  * gci linter
+  * Better merge array by key example
+  * Added credit for merge by array example
+  * Better formatting of merge arrays example
+  * Better merge example
+  * Add accessor for the yq logger instance (#1013)
+  * Fixed collect op when working with multiple nodes
+  * Added map, map_values
+  * Add support for Podman as well as Docker (#1026)
+  * Bump github.com/jinzhu/copier from 0.3.2 to 0.3.4 (#1027)
+  * Added csv, tsv output formats
+  * Added encoder tests
+  * Cleanup test
+  * Fixed docker permission issue #1014
+  * Recording release notes for next release
+  * Assignment op no longer clobbers anchor (#1029)
+  * Added sort_by operator
+  * Improved error message
+  * Improved tips and tricks
+  * Report while filename failed to parse #1030
+  * Added script for extracting checksums
+  * Improved extract-checksum.sh
+  * Bump github.com/spf13/cobra from 1.2.1 to 1.3.0 (#1039)
+  * enable more linters (#1043)
+  * Bump golang compiler #1037
+
+ -- Roberto Mier Escandon <rmescandon@gmail.com>  Tue, 21 Dec 2021 09:41:44 +0000
+
 yq (4.13.0) focal; urgency=medium
 
   * New `with` operator for making multiple changes to a given path

debian/control

@@ -3,7 +3,8 @@ Section: devel
 Priority: optional
 Maintainer: Roberto Mier Escandón <rmescandon@gmail.com>
 Build-Depends: debhelper (>=10),
-               golang-1.15,
+               golang-1.17-go,
+               pandoc,
                rsync
 Standards-Version: 4.1.4
 Homepage: https://github.com/mikefarah/yq.git

debian/rules

@@ -1,6 +1,6 @@
 #!/usr/bin/make -f
 #
-# Copyright (C) 2018 Roberto Mier Escandón <rmescandon@gmail.com>
+# Copyright (C) 2018-2021 Roberto Mier Escandón <rmescandon@gmail.com>
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License version 3 as
@@ -17,20 +17,21 @@
 PROJECT := yq
 OWNER := mikefarah
 REPO := github.com
-GOVERSION := 1.15
 
 export DH_OPTIONS
 export DH_GOPKG := ${REPO}/${OWNER}/${PROJECT}
-export GOROOT := /usr/lib/go-${GOVERSION}
+export GOROOT := /usr/local/go
 export GOPATH := ${CURDIR}/_build
 export GOBIN := ${GOPATH}/bin
 export PATH := ${GOROOT}/bin:${GOBIN}:${PATH}
 export GOCACHE := /tmp/gocache
 export GOFLAGS := -mod=vendor
+export GO111MODULE := on
 
 SRCDIR := ${GOPATH}/src/${DH_GOPKG}
 DESTDIR := ${CURDIR}/debian/${PROJECT}
 BINDIR := /usr/bin
+MANDIR := /usr/share/man/man1/
 ASSETSDIR := /usr/share/${PROJECT}
 
 %:
@@ -42,7 +43,17 @@ override_dh_auto_build:
 	# copy project to local srcdir to build from there
 	rsync -avz --progress --exclude=_build --exclude=debian --exclude=tmp. --exclude=go.mod --exclude=docs . $(SRCDIR)
 	# build go code
-	(cd ${SRCDIR} && go install -buildmode=pie ./...)
+	( \
+		cd ${SRCDIR} && \
+		go install -buildmode=pie ./... \
+	)
+
+	# build man page
+	( \
+		cd ${SRCDIR} && \
+		./scripts/generate-man-page-md.sh && \
+		./scripts/generate-man-page.sh \
+	)
 	
 override_dh_auto_test:
 ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))
@@ -54,6 +65,10 @@ override_dh_auto_install:
 	cp -f ${SRCDIR}/LICENSE ${DESTDIR}/${ASSETSDIR}
 	chmod a+x ${DESTDIR}/${BINDIR}/yq
 
+	# man
+	mkdir -p "${DESTDIR}"/"${MANDIR}"
+	cp "${SRCDIR}"/yq.1 "${DESTDIR}"/"${MANDIR}" \
+
 override_dh_auto_clean:
 	dh_clean
 	rm -rf ${CURDIR}/_build

examples/data1.yaml

@@ -1,15 +1 @@
-strings:
-  - a: banana
-  - a: cat
-  - a: apple
-
-numbers:
-  - a: 12
-  - a: 13
-  - a: 120
-
-
-obj:
-  - a: {cat: "adog"}
-  - a: {cat: "doga"}
-  - a: apple
+cat: purrs

examples/mike.xml

@@ -0,0 +1,14 @@
+<!-- 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 -->

examples/mike2.xml

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

go.mod

@@ -3,11 +3,13 @@ module github.com/mikefarah/yq/v4
 require (
 	github.com/elliotchance/orderedmap v1.4.0
 	github.com/fatih/color v1.13.0
-	github.com/goccy/go-yaml v1.9.4
-	github.com/jinzhu/copier v0.3.4
+	github.com/goccy/go-yaml v1.9.5
+	github.com/jinzhu/copier v0.3.5
 	github.com/magiconair/properties v1.8.5
+	github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e
 	github.com/spf13/cobra v1.3.0
 	github.com/timtadh/lexmachine v0.2.2
+	golang.org/x/net v0.0.0-20210813160813-60bc85c4be6d
 	gopkg.in/op/go-logging.v1 v1.0.0-20160211212156-b2cb9fa56473
 	gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b
 )
@@ -19,6 +21,7 @@ require (
 	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/timtadh/data-structures v0.5.3 // indirect
 	golang.org/x/sys v0.0.0-20211205182925-97ca703d548d // indirect
+	golang.org/x/text v0.3.7 // indirect
 	golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 // indirect
 )
 

go.sum

@@ -123,8 +123,8 @@ github.com/go-playground/locales v0.13.0/go.mod h1:taPMhCMXrRLJO55olJkUXHZBHCxTM
 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/go-stack/stack v1.8.0/go.mod h1:v0f6uXyyMGvRgIKkXu+yp6POWl0qKG85gN/melR3HDY=
-github.com/goccy/go-yaml v1.9.4 h1:S0GCYjwHKVI6IHqio7QWNKNThUl6NLzFd/g8Z65Axw8=
-github.com/goccy/go-yaml v1.9.4/go.mod h1:U/jl18uSupI5rdI2jmuCswEA2htH9eXfferR3KfscvA=
+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/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
 github.com/gogo/protobuf v1.1.1/go.mod h1:r8qH/GZQm5c6nD/R0oafs1akxWv10x8SbQlK7atdtwQ=
 github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
@@ -235,8 +235,8 @@ github.com/ianlancetaylor/demangle v0.0.0-20181102032728-5e5cf60278f6/go.mod h1:
 github.com/ianlancetaylor/demangle v0.0.0-20200824232613-28f6c0f3b639/go.mod h1:aSSvb/t6k1mPoxDqO4vJh6VOCGPwU4O0C2/Eqndh1Sc=
 github.com/inconshreveable/mousetrap v1.0.0 h1:Z8tu5sraLXCXIcARxBp/8cbvlwVa7Z1NHg9XEKhtSvM=
 github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8=
-github.com/jinzhu/copier v0.3.4 h1:mfU6jI9PtCeUjkjQ322dlff9ELjGDu975C2p/nrubVI=
-github.com/jinzhu/copier v0.3.4/go.mod h1:DfbEm0FYsaqBcKcFuvmOZb218JkPGtvSHsKg8S8hyyg=
+github.com/jinzhu/copier v0.3.5 h1:GlvfUwHk62RokgqVNvYsku0TATCF7bAHVwEXoBh3iJg=
+github.com/jinzhu/copier v0.3.5/go.mod h1:DfbEm0FYsaqBcKcFuvmOZb218JkPGtvSHsKg8S8hyyg=
 github.com/json-iterator/go v1.1.6/go.mod h1:+SdeFBvtyEkXs7REEP0seUULqWtbJapLOCVDaaPEHmU=
 github.com/json-iterator/go v1.1.9/go.mod h1:KdQUCv79m/52Kvf8AW2vK1V8akMuk1QjK/uOdHXbAo4=
 github.com/json-iterator/go v1.1.11/go.mod h1:KdQUCv79m/52Kvf8AW2vK1V8akMuk1QjK/uOdHXbAo4=
@@ -292,6 +292,8 @@ github.com/mwitkow/go-conntrack v0.0.0-20161129095857-cc309e4a2223/go.mod h1:qRW
 github.com/pascaldekloe/goe v0.0.0-20180627143212-57f6aae5913c/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc=
 github.com/pascaldekloe/goe v0.1.0/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc=
 github.com/pelletier/go-toml v1.9.4/go.mod h1:u1nR/EPcESfeI/szUZKdtJ0xRNbUoANCkoOuaOx1Y+c=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e h1:aoZm08cpOy4WuID//EZDgcC4zIxODThtZNPirFr42+A=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
 github.com/pkg/errors v0.8.0/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/sftp v1.10.1/go.mod h1:lYOWFsE0bwd1+KfKJaKeuokY15vzFx25BLbzYYoAxZI=
@@ -449,6 +451,7 @@ golang.org/x/net v0.0.0-20210316092652-d523dce5a7f4/go.mod h1:RBQZq4jEuRlivfhVLd
 golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4/go.mod h1:p54w0d4576C0XHj96bSt6lcn1PtDYWL6XObtHCRCNQM=
 golang.org/x/net v0.0.0-20210410081132-afb366fc7cd1/go.mod h1:9tjilg8BloeKEkVJvy7fQ90B1CfIiPueXVOjqfkSzI8=
 golang.org/x/net v0.0.0-20210503060351-7fd8e65b6420/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
+golang.org/x/net v0.0.0-20210813160813-60bc85c4be6d h1:LO7XpTYMwTqxjLcGWPijK3vRXg1aWdlNOVOHRq45d7c=
 golang.org/x/net v0.0.0-20210813160813-60bc85c4be6d/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
 golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
 golang.org/x/oauth2 v0.0.0-20190226205417-e64efc72b421/go.mod h1:gOpvHmFTYa4IltrdGE7lF6nIHvwfUNPOp7c8zoXwtLw=
@@ -553,6 +556,7 @@ golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.4/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.5/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.7 h1:olpwvP2KacW1ZWvsR7uQhoyTYvKAupfQrRGBFM352Gk=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
 golang.org/x/time v0.0.0-20181108054448-85acf8d2951c/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
 golang.org/x/time v0.0.0-20190308202827-9d24e82272b4/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=

pkg/yqlib/all_at_once_evaluator.go

@@ -8,7 +8,7 @@ import (
 
 // A yaml expression evaluator that runs the expression once against all files/nodes in memory.
 type Evaluator interface {
-	EvaluateFiles(expression string, filenames []string, printer Printer, leadingContentPreProcessing bool) error
+	EvaluateFiles(expression string, filenames []string, printer Printer, leadingContentPreProcessing bool, decoder Decoder) error
 
 	// EvaluateNodes takes an expression and one or more yaml nodes, returning a list of matching candidate nodes
 	EvaluateNodes(expression string, nodes ...*yaml.Node) (*list.List, error)
@@ -46,7 +46,7 @@ func (e *allAtOnceEvaluator) EvaluateCandidateNodes(expression string, inputCand
 	return context.MatchingNodes, nil
 }
 
-func (e *allAtOnceEvaluator) EvaluateFiles(expression string, filenames []string, printer Printer, leadingContentPreProcessing bool) error {
+func (e *allAtOnceEvaluator) EvaluateFiles(expression string, filenames []string, printer Printer, leadingContentPreProcessing bool, decoder Decoder) error {
 	fileIndex := 0
 	firstFileLeadingContent := ""
 
@@ -61,7 +61,7 @@ func (e *allAtOnceEvaluator) EvaluateFiles(expression string, filenames []string
 			firstFileLeadingContent = leadingContent
 		}
 
-		fileDocuments, err := readDocuments(reader, filename, fileIndex)
+		fileDocuments, err := readDocuments(reader, filename, fileIndex, decoder)
 		if err != nil {
 			return err
 		}

pkg/yqlib/candidate_node.go

@@ -136,7 +136,12 @@ func (n *CandidateNode) UpdateAttributesFrom(other *CandidateNode, prefs assignP
 		n.Node.Value = ""
 	}
 	n.Node.Kind = other.Node.Kind
-	n.Node.Tag = other.Node.Tag
+
+	// don't clobber custom tags...
+	if strings.HasPrefix(n.Node.Tag, "!!") || n.Node.Tag == "" {
+		n.Node.Tag = other.Node.Tag
+	}
+
 	n.Node.Alias = other.Node.Alias
 
 	if !prefs.DontOverWriteAnchor {

pkg/yqlib/decoder_xml.go

@@ -0,0 +1,330 @@
+package yqlib
+
+import (
+	"encoding/xml"
+	"fmt"
+	"io"
+	"strings"
+	"unicode"
+
+	"golang.org/x/net/html/charset"
+	yaml "gopkg.in/yaml.v3"
+)
+
+type InputFormat uint
+
+const (
+	YamlInputFormat = 1 << iota
+	XmlInputFormat
+)
+
+func InputFormatFromString(format string) (InputFormat, error) {
+	switch format {
+	case "yaml", "y":
+		return YamlInputFormat, nil
+	case "xml", "x":
+		return XmlInputFormat, nil
+	default:
+		return 0, fmt.Errorf("unknown format '%v' please use [yaml|xml]", format)
+	}
+}
+
+type xmlDecoder struct {
+	reader          io.Reader
+	attributePrefix string
+	contentName     string
+	finished        bool
+}
+
+func NewXmlDecoder(attributePrefix string, contentName string) Decoder {
+	if contentName == "" {
+		contentName = "content"
+	}
+	return &xmlDecoder{attributePrefix: attributePrefix, contentName: contentName, finished: false}
+}
+
+func (dec *xmlDecoder) Init(reader io.Reader) {
+	dec.reader = reader
+	dec.finished = false
+}
+
+func (dec *xmlDecoder) createSequence(nodes []*xmlNode) (*yaml.Node, error) {
+	yamlNode := &yaml.Node{Kind: yaml.SequenceNode}
+	for _, child := range nodes {
+		yamlChild, err := dec.convertToYamlNode(child)
+		if err != nil {
+			return nil, err
+		}
+		yamlNode.Content = append(yamlNode.Content, yamlChild)
+	}
+
+	return yamlNode, nil
+}
+
+func (dec *xmlDecoder) processComment(c string) string {
+	if c == "" {
+		return ""
+	}
+	return "#" + strings.TrimRight(c, " ")
+}
+
+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}
+
+	if len(n.Data) > 0 {
+		label := dec.contentName
+		labelNode := createScalarNode(label, label)
+		labelNode.HeadComment = dec.processComment(n.HeadComment)
+		labelNode.FootComment = dec.processComment(n.FootComment)
+		yamlNode.Content = append(yamlNode.Content, labelNode, createScalarNode(n.Data, n.Data))
+	}
+
+	for i, keyValuePair := range n.Children {
+		label := keyValuePair.K
+		children := keyValuePair.V
+		labelNode := createScalarNode(label, label)
+		var valueNode *yaml.Node
+		var err error
+
+		if i == 0 {
+			labelNode.HeadComment = dec.processComment(n.HeadComment)
+
+		}
+
+		// 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 {
+			valueNode, err = dec.createSequence(children)
+			if err != nil {
+				return nil, err
+			}
+		} else {
+			// comment hack for maps of scalars
+			// if the value is a scalar, the head comment of the scalar needs to go on the key?
+			// add tests for <z/> as well as multiple <ds> of inputXmlWithComments > yaml
+			if len(children[0].Children) == 0 && children[0].HeadComment != "" {
+				labelNode.HeadComment = labelNode.HeadComment + "\n" + strings.TrimSpace(children[0].HeadComment)
+				children[0].HeadComment = ""
+			}
+			valueNode, err = dec.convertToYamlNode(children[0])
+			if err != nil {
+				return nil, err
+			}
+		}
+		yamlNode.Content = append(yamlNode.Content, labelNode, valueNode)
+	}
+
+	return yamlNode, nil
+}
+
+func (dec *xmlDecoder) convertToYamlNode(n *xmlNode) (*yaml.Node, error) {
+	if len(n.Children) > 0 {
+		return dec.createMap(n)
+	}
+	scalar := createScalarNode(n.Data, n.Data)
+	log.Debug("scalar headC: %v, footC: %v", n.HeadComment, n.FootComment)
+	scalar.HeadComment = dec.processComment(n.HeadComment)
+	scalar.LineComment = dec.processComment(n.LineComment)
+	scalar.FootComment = dec.processComment(n.FootComment)
+
+	return scalar, nil
+}
+
+func (dec *xmlDecoder) Decode(rootYamlNode *yaml.Node) error {
+	if dec.finished {
+		return io.EOF
+	}
+	root := &xmlNode{}
+	// cant use xj - it doesn't keep map order.
+	err := dec.decodeXml(root)
+
+	if err != nil {
+		return err
+	}
+	firstNode, err := dec.convertToYamlNode(root)
+
+	if err != nil {
+		return err
+	}
+	rootYamlNode.Kind = yaml.DocumentNode
+	rootYamlNode.Content = []*yaml.Node{firstNode}
+	dec.finished = true
+	return nil
+}
+
+type xmlNode struct {
+	Children    []*xmlChildrenKv
+	HeadComment string
+	FootComment string
+	LineComment string
+	Data        string
+}
+
+type xmlChildrenKv struct {
+	K           string
+	V           []*xmlNode
+	FootComment string
+}
+
+// AddChild appends a node to the list of children
+func (n *xmlNode) AddChild(s string, c *xmlNode) {
+
+	if n.Children == nil {
+		n.Children = make([]*xmlChildrenKv, 0)
+	}
+	log.Debug("looking for %s", s)
+	// see if we can find an existing entry to add to
+	for _, childEntry := range n.Children {
+		if childEntry.K == s {
+			log.Debug("found it, appending an entry%s", s)
+			childEntry.V = append(childEntry.V, c)
+			log.Debug("yay len of children in %v is %v", s, len(childEntry.V))
+			return
+		}
+	}
+	log.Debug("not there, making a new one %s", s)
+	n.Children = append(n.Children, &xmlChildrenKv{K: s, V: []*xmlNode{c}})
+}
+
+type element struct {
+	parent *element
+	n      *xmlNode
+	label  string
+	state  string
+}
+
+// this code is heavily based on https://github.com/basgys/goxml2json
+// main changes are to decode into a structure that preserves the original order
+// of the map keys.
+func (dec *xmlDecoder) decodeXml(root *xmlNode) error {
+	xmlDec := xml.NewDecoder(dec.reader)
+
+	// That will convert the charset if the provided XML is non-UTF-8
+	xmlDec.CharsetReader = charset.NewReaderLabel
+
+	// Create first element from the root node
+	elem := &element{
+		parent: nil,
+		n:      root,
+	}
+
+	for {
+		t, _ := xmlDec.Token()
+		if t == nil {
+			break
+		}
+
+		switch se := t.(type) {
+		case xml.StartElement:
+			log.Debug("start element %v", se.Name.Local)
+			elem.state = "started"
+			// Build new a new current element and link it to its parent
+			elem = &element{
+				parent: elem,
+				n:      &xmlNode{},
+				label:  se.Name.Local,
+			}
+
+			// Extract attributes as children
+			for _, a := range se.Attr {
+				elem.n.AddChild(dec.attributePrefix+a.Name.Local, &xmlNode{Data: a.Value})
+			}
+		case xml.CharData:
+			// Extract XML data (if any)
+			elem.n.Data = trimNonGraphic(string(se))
+			if elem.n.Data != "" {
+				elem.state = "chardata"
+				log.Debug("chardata [%v] for %v", elem.n.Data, elem.label)
+			}
+		case xml.EndElement:
+			log.Debug("end element %v", elem.label)
+			elem.state = "finished"
+			// And add it to its parent list
+			if elem.parent != nil {
+				elem.parent.n.AddChild(elem.label, elem.n)
+			}
+
+			// Then change the current element to its parent
+			elem = elem.parent
+		case xml.Comment:
+
+			commentStr := string(xml.CharData(se))
+			if elem.state == "started" {
+				applyFootComment(elem, commentStr)
+
+			} else if elem.state == "chardata" {
+				log.Debug("got a line comment for (%v) %v: [%v]", elem.state, elem.label, commentStr)
+				elem.n.LineComment = joinFilter([]string{elem.n.LineComment, commentStr})
+			} else {
+				log.Debug("got a head comment for (%v) %v: [%v]", elem.state, elem.label, commentStr)
+				elem.n.HeadComment = joinFilter([]string{elem.n.HeadComment, commentStr})
+			}
+
+		}
+	}
+
+	return nil
+}
+
+func applyFootComment(elem *element, commentStr string) {
+
+	// first lets try to put the comment on the last child
+	if len(elem.n.Children) > 0 {
+		lastChildIndex := len(elem.n.Children) - 1
+		childKv := elem.n.Children[lastChildIndex]
+		log.Debug("got a foot comment for %v: [%v]", childKv.K, commentStr)
+		childKv.FootComment = joinFilter([]string{elem.n.FootComment, commentStr})
+	} else {
+		log.Debug("got a foot comment for %v: [%v]", elem.label, commentStr)
+		elem.n.FootComment = joinFilter([]string{elem.n.FootComment, commentStr})
+	}
+}
+
+func joinFilter(rawStrings []string) string {
+	stringsToJoin := make([]string, 0)
+	for _, str := range rawStrings {
+		if str != "" {
+			stringsToJoin = append(stringsToJoin, str)
+		}
+	}
+	return strings.Join(stringsToJoin, " ")
+}
+
+// trimNonGraphic returns a slice of the string s, with all leading and trailing
+// non graphic characters and spaces removed.
+//
+// Graphic characters include letters, marks, numbers, punctuation, symbols,
+// and spaces, from categories L, M, N, P, S, Zs.
+// Spacing characters are set by category Z and property Pattern_White_Space.
+func trimNonGraphic(s string) string {
+	if s == "" {
+		return s
+	}
+
+	var first *int
+	var last int
+	for i, r := range []rune(s) {
+		if !unicode.IsGraphic(r) || unicode.IsSpace(r) {
+			continue
+		}
+
+		if first == nil {
+			f := i // copy i
+			first = &f
+			last = i
+		} else {
+			last = i
+		}
+	}
+
+	// If first is nil, it means there are no graphic characters
+	if first == nil {
+		return ""
+	}
+
+	return string([]rune(s)[*first : last+1])
+}

pkg/yqlib/decoder_yaml.go

@@ -0,0 +1,28 @@
+package yqlib
+
+import (
+	"io"
+
+	yaml "gopkg.in/yaml.v3"
+)
+
+type Decoder interface {
+	Init(reader io.Reader)
+	Decode(node *yaml.Node) error
+}
+
+type yamlDecoder struct {
+	decoder yaml.Decoder
+}
+
+func NewYamlDecoder() Decoder {
+	return &yamlDecoder{}
+}
+
+func (dec *yamlDecoder) Init(reader io.Reader) {
+	dec.decoder = *yaml.NewDecoder(reader)
+}
+
+func (dec *yamlDecoder) Decode(rootYamlNode *yaml.Node) error {
+	return dec.decoder.Decode(rootYamlNode)
+}

pkg/yqlib/doc/operators/add.md

@@ -7,6 +7,8 @@ Add behaves differently according to the type of the LHS:
 
 Use `+=` as append assign for things like increment. Note that `.a += .x` is equivalent to running `.a = .a + .x`.
 
+Add is not (yet) supported for maps - however you can use merge `*` which will have a similar effect...
+
 ## Concatenate and assign arrays
 Given a sample.yml file of:
 ```yaml
@@ -265,3 +267,39 @@ will output
 cat
 ```
 
+## Custom types: that are really strings
+When custom tags are encountered, yq will try to decode the underlying type.
+
+Given a sample.yml file of:
+```yaml
+a: !horse cat
+b: !goat _meow
+```
+then
+```bash
+yq eval '.a += .b' sample.yml
+```
+will output
+```yaml
+a: !horse cat_meow
+b: !goat _meow
+```
+
+## Custom types: that are really numbers
+When custom tags are encountered, yq will try to decode the underlying type.
+
+Given a sample.yml file of:
+```yaml
+a: !horse 1.2
+b: !goat 2.3
+```
+then
+```bash
+yq eval '.a += .b' sample.yml
+```
+will output
+```yaml
+a: !horse 3.5
+b: !goat 2.3
+```
+

pkg/yqlib/doc/operators/encode-decode.md

@@ -14,10 +14,13 @@ These operators are useful to process yaml documents that have stringified embed
 | Properties |  | to_props/@props |
 | CSV |  | to_csv/@csv |
 | TSV |  | to_tsv/@tsv |
+| XML | from_xml | to_xml(i)/@xml |
 
 
 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). 
 
+XML uses the `--xml-attribute-prefix` and `xml-content-name` flags to identify attributes and content fields.
+
 
 ## Encode value as json string
 Given a sample.yml file of:
@@ -271,3 +274,77 @@ cat	thing1,thing2	true	3.40
 dog	thing3	false	12
 ```
 
+## Encode value as xml string
+Given a sample.yml file of:
+```yaml
+a:
+  cool:
+    foo: bar
+    +id: hi
+```
+then
+```bash
+yq eval '.a | to_xml' sample.yml
+```
+will output
+```yaml
+<cool id="hi">
+  <foo>bar</foo>
+</cool>
+
+```
+
+## Encode value as xml string on a single line
+Given a sample.yml file of:
+```yaml
+a:
+  cool:
+    foo: bar
+    +id: hi
+```
+then
+```bash
+yq eval '.a | @xml' sample.yml
+```
+will output
+```yaml
+<cool id="hi"><foo>bar</foo></cool>
+
+```
+
+## Encode value as xml string with custom indentation
+Given a sample.yml file of:
+```yaml
+a:
+  cool:
+    foo: bar
+    +id: hi
+```
+then
+```bash
+yq eval '{"cat": .a | to_xml(1)}' sample.yml
+```
+will output
+```yaml
+cat: |
+  <cool id="hi">
+   <foo>bar</foo>
+  </cool>
+```
+
+## Decode a xml encoded string
+Given a sample.yml file of:
+```yaml
+a: <foo>bar</foo>
+```
+then
+```bash
+yq eval '.b = (.a | from_xml)' sample.yml
+```
+will output
+```yaml
+a: <foo>bar</foo>
+b:
+  foo: bar
+```
+

pkg/yqlib/doc/operators/headers/add.md

@@ -6,3 +6,5 @@ Add behaves differently according to the type of the LHS:
 * string scalars: concatenate
 
 Use `+=` as append assign for things like increment. Note that `.a += .x` is equivalent to running `.a = .a + .x`.
+
+Add is not (yet) supported for maps - however you can use merge `*` which will have a similar effect...

pkg/yqlib/doc/operators/headers/encode-decode.md

@@ -14,7 +14,10 @@ These operators are useful to process yaml documents that have stringified embed
 | Properties |  | to_props/@props |
 | CSV |  | to_csv/@csv |
 | TSV |  | to_tsv/@tsv |
+| XML | from_xml | to_xml(i)/@xml |
 
 
 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). 
 
+XML uses the `--xml-attribute-prefix` and `xml-content-name` flags to identify attributes and content fields.
+

pkg/yqlib/doc/operators/headers/multiply-merge.md

@@ -10,9 +10,10 @@ Note that when merging objects, this operator returns the merged object (not the
 ### Merge Flags
 You can control how objects are merged by using one or more of the following flags. Multiple flags can be used together, e.g. `.a *+? .b`.  See examples below
 
-- `+` to append arrays
-- `?` to only merge existing fields
-- `d` to deeply merge arrays
+- `+` append arrays
+- `d` deeply merge arrays
+- `?` only merge _existing_ fields
+- `n` only merge _new_ fields
 
 ### Merging files
 Note the use of `eval-all` to ensure all documents are loaded into memory.

pkg/yqlib/doc/operators/multiply-merge.md

@@ -10,9 +10,10 @@ Note that when merging objects, this operator returns the merged object (not the
 ### Merge Flags
 You can control how objects are merged by using one or more of the following flags. Multiple flags can be used together, e.g. `.a *+? .b`.  See examples below
 
-- `+` to append arrays
-- `?` to only merge existing fields
-- `d` to deeply merge arrays
+- `+` append arrays
+- `d` deeply merge arrays
+- `?` only merge _existing_ fields
+- `n` only merge _new_ fields
 
 ### Merging files
 Note the use of `eval-all` to ensure all documents are loaded into memory.
@@ -148,6 +149,27 @@ thing: two
 cat: frog
 ```
 
+## Merge, only new fields
+Given a sample.yml file of:
+```yaml
+a:
+  thing: one
+  cat: frog
+b:
+  missing: two
+  thing: two
+```
+then
+```bash
+yq eval '.a *n .b' sample.yml
+```
+will output
+```yaml
+thing: one
+cat: frog
+missing: two
+```
+
 ## Merge, appending arrays
 Given a sample.yml file of:
 ```yaml
@@ -388,3 +410,44 @@ thing: foobar_thing
 b: foobarList_b
 ```
 
+## Custom types: that are really numbers
+When custom tags are encountered, yq will try to decode the underlying type.
+
+Given a sample.yml file of:
+```yaml
+a: !horse 2
+b: !goat 3
+```
+then
+```bash
+yq eval '.a = .a * .b' sample.yml
+```
+will output
+```yaml
+a: !horse 6
+b: !goat 3
+```
+
+## Custom types: that are really maps
+Custom tags will be maintained.
+
+Given a sample.yml file of:
+```yaml
+a: !horse
+  cat: meow
+b: !goat
+  dog: woof
+```
+then
+```bash
+yq eval '.a = .a * .b' sample.yml
+```
+will output
+```yaml
+a: !horse
+  cat: meow
+  dog: woof
+b: !goat
+  dog: woof
+```
+

pkg/yqlib/doc/operators/select.md

@@ -0,0 +1,133 @@
+# Select
+
+Select is used to filter arrays and maps by a boolean expression.
+
+## Select elements from array using wildcard prefix
+Given a sample.yml file of:
+```yaml
+- cat
+- goat
+- dog
+```
+then
+```bash
+yq eval '.[] | select(. == "*at")' sample.yml
+```
+will output
+```yaml
+cat
+goat
+```
+
+## Select elements from array using wildcard suffix
+Given a sample.yml file of:
+```yaml
+- go-kart
+- goat
+- dog
+```
+then
+```bash
+yq eval '.[] | select(. == "go*")' sample.yml
+```
+will output
+```yaml
+go-kart
+goat
+```
+
+## Select elements from array using wildcard prefix and suffix
+Given a sample.yml file of:
+```yaml
+- ago
+- go
+- meow
+- going
+```
+then
+```bash
+yq eval '.[] | select(. == "*go*")' sample.yml
+```
+will output
+```yaml
+ago
+go
+going
+```
+
+## Select elements from array with regular expression
+See more regular expression examples under the `string` operator docs.
+
+Given a sample.yml file of:
+```yaml
+- this_0
+- not_this
+- nor_0_this
+- thisTo_4
+```
+then
+```bash
+yq eval '.[] | select(test("[a-zA-Z]+_[0-9]$"))' sample.yml
+```
+will output
+```yaml
+this_0
+thisTo_4
+```
+
+## Select items from a map
+Given a sample.yml file of:
+```yaml
+things: cat
+bob: goat
+horse: dog
+```
+then
+```bash
+yq eval '.[] | select(. == "cat" or test("og$"))' sample.yml
+```
+will output
+```yaml
+cat
+dog
+```
+
+## Use select and with_entries to filter map keys
+Given a sample.yml file of:
+```yaml
+name: bob
+legs: 2
+game: poker
+```
+then
+```bash
+yq eval 'with_entries(select(.key | test("ame$")))' sample.yml
+```
+will output
+```yaml
+name: bob
+game: poker
+```
+
+## Select multiple items in a map and update
+Note the brackets around the entire LHS.
+
+Given a sample.yml file of:
+```yaml
+a:
+  things: cat
+  bob: goat
+  horse: dog
+```
+then
+```bash
+yq eval '(.a.[] | select(. == "cat" or . == "goat")) |= "rabbit"' sample.yml
+```
+will output
+```yaml
+a:
+  things: rabbit
+  bob: rabbit
+  horse: dog
+```
+