From d25785c3f38176f6d90d103a242baffb6d7d1203 Mon Sep 17 00:00:00 2001 From: Mike Farah Date: Fri, 1 Sep 2023 11:52:38 +1000 Subject: [PATCH] updating docs --- SUMMARY.md | 1 + usage/lua.md | 144 +++++++++++++++++++++++++++++++++++++++++++++++++++ usage/xml.md | 44 +++++++++++----- 3 files changed, 176 insertions(+), 13 deletions(-) create mode 100644 usage/lua.md diff --git a/SUMMARY.md b/SUMMARY.md index 6788a995..1ff899b3 100644 --- a/SUMMARY.md +++ b/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) diff --git a/usage/lua.md b/usage/lua.md new file mode 100644 index 00000000..61458be2 --- /dev/null +++ b/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); + }, + }; +}; +``` + diff --git a/usage/xml.md b/usage/xml.md index 3d85a4ff..89bee794 100644 --- a/usage/xml.md +++ b/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 +cat +``` +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 --> ``` 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 --> ``` 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