updating docs

SUMMARY.md

@@ -76,6 +76,7 @@
 * [Working with JSON](usage/convert.md)
 * [Working with Properties](usage/properties.md)
 * [Working with XML](usage/xml.md)
+* [Working with LUA](usage/lua.md)
 * [Working with TOML](usage/toml.md)
 * [Working with Shell Output](usage/shellvariables.md)
 * [Front Matter](usage/front-matter.md)

usage/lua.md

@@ -0,0 +1,144 @@
+
+## Basic example
+Given a sample.yml file of:
+```yaml
+---
+country: Australia # this place
+cities:
+- Sydney
+- Melbourne
+- Brisbane
+- Perth
+```
+then
+```bash
+yq -o=lua '.' sample.yml
+```
+will output
+```lua
+return {
+	["country"] = "Australia"; -- this place
+	["cities"] = {
+		"Sydney",
+		"Melbourne",
+		"Brisbane",
+		"Perth",
+	};
+};
+```
+
+## Unquoted keys
+Uses the `--lua-unquoted` option to produce a nicer-looking output.
+
+Given a sample.yml file of:
+```yaml
+---
+country: Australia # this place
+cities:
+- Sydney
+- Melbourne
+- Brisbane
+- Perth
+```
+then
+```bash
+yq -o=lua --lua-unquoted '.' sample.yml
+```
+will output
+```lua
+return {
+	country = "Australia"; -- this place
+	cities = {
+		"Sydney",
+		"Melbourne",
+		"Brisbane",
+		"Perth",
+	};
+};
+```
+
+## Globals
+Uses the `--lua-globals` option to export the values into the global scope.
+
+Given a sample.yml file of:
+```yaml
+---
+country: Australia # this place
+cities:
+- Sydney
+- Melbourne
+- Brisbane
+- Perth
+```
+then
+```bash
+yq -o=lua --lua-globals '.' sample.yml
+```
+will output
+```lua
+country = "Australia"; -- this place
+cities = {
+	"Sydney",
+	"Melbourne",
+	"Brisbane",
+	"Perth",
+};
+```
+
+## Elaborate example
+Given a sample.yml file of:
+```yaml
+---
+hello: world
+tables:
+  like: this
+  keys: values
+  ? look: non-string keys
+  : True
+numbers:
+  - decimal: 12345
+  - hex: 0x7fabc123
+  - octal: 0o30
+  - float: 123.45
+  - infinity: .inf
+  - not: .nan
+
+```
+then
+```bash
+yq -o=lua '.' sample.yml
+```
+will output
+```lua
+return {
+	["hello"] = "world";
+	["tables"] = {
+		["like"] = "this";
+		["keys"] = "values";
+		[{
+			["look"] = "non-string keys";
+		}] = true;
+	};
+	["numbers"] = {
+		{
+			["decimal"] = 12345;
+		},
+		{
+			["hex"] = 0x7fabc123;
+		},
+		{
+			["octal"] = 24;
+		},
+		{
+			["float"] = 123.45;
+		},
+		{
+			["infinity"] = (1/0);
+		},
+		{
+			["not"] = (0/0);
+		},
+	};
+};
+```
+

usage/xml.md

@@ -53,7 +53,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -p=xml '.' sample.xml
+yq -oy '.' sample.xml
 ```
 will output
 ```yaml
@@ -78,7 +78,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -p=xml ' (.. | select(tag == "!!str")) |= from_yaml' sample.xml
+yq -oy ' (.. | select(tag == "!!str")) |= from_yaml' sample.xml
 ```
 will output
 ```yaml
@@ -100,7 +100,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -p=xml '.' sample.xml
+yq -oy '.' sample.xml
 ```
 will output
 ```yaml
@@ -110,6 +110,24 @@ animal:
   - goat
 ```
 
+## Parse xml: force as an array
+In XML, if your array has a single item, then yq doesn't know its an array. This is how you can consistently force it to be an array. This handles the 3 scenarios of having nothing in the array, having a single item and having multiple.
+
+Given a sample.xml file of:
+```xml
+<zoo><animal>cat</animal></zoo>
+```
+then
+```bash
+yq -oy '.zoo.animal |= ([] + .)' sample.xml
+```
+will output
+```yaml
+zoo:
+  animal:
+    - cat
+```
+
 ## Parse xml: attributes
 Attributes are converted to fields, with the default attribute prefix '+'. Use '--xml-attribute-prefix` to set your own.
 
@@ -122,7 +140,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -p=xml '.' sample.xml
+yq -oy '.' sample.xml
 ```
 will output
 ```yaml
@@ -142,7 +160,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -p=xml '.' sample.xml
+yq -oy '.' sample.xml
 ```
 will output
 ```yaml
@@ -161,7 +179,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -p=xml '.' sample.xml
+yq -oy '.' sample.xml
 ```
 will output
 ```yaml
@@ -190,7 +208,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -p=xml -o=xml '.' sample.xml
+yq '.' sample.xml
 ```
 will output
 ```xml
@@ -221,7 +239,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -p=xml -o=xml --xml-skip-directives '.' sample.xml
+yq --xml-skip-directives '.' sample.xml
 ```
 will output
 ```xml
@@ -257,7 +275,7 @@ for x --></x>
 ```
 then
 ```bash
-yq -p=xml '.' sample.xml
+yq -oy '.' sample.xml
 ```
 will output
 ```yaml
@@ -289,7 +307,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -p=xml -o=xml --xml-keep-namespace=false '.' sample.xml
+yq --xml-keep-namespace=false '.' sample.xml
 ```
 will output
 ```xml
@@ -314,7 +332,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -p=xml -o=xml --xml-raw-token=false '.' sample.xml
+yq --xml-raw-token=false '.' sample.xml
 ```
 will output
 ```xml
@@ -489,7 +507,7 @@ for x --></x>
 ```
 then
 ```bash
-yq -p=xml -o=xml '.' sample.xml
+yq '.' sample.xml
 ```
 will output
 ```xml
@@ -522,7 +540,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -p=xml -o=xml '.' sample.xml
+yq '.' sample.xml
 ```
 will output
 ```xml