From 3793f723b8d81bad3e8a248e4eaee5fa64670358 Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Sat, 15 Jan 2022 18:19:12 +1100
Subject: [PATCH] Improving select docs (#839)

---
 operators/select.md | 98 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 95 insertions(+), 3 deletions(-)

diff --git a/operators/select.md b/operators/select.md
index aabed120..b3de5ab2 100644
--- a/operators/select.md
+++ b/operators/select.md
@@ -2,7 +2,27 @@
 
 Select is used to filter arrays and maps by a boolean expression.
 
-## Select elements from array
+## 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 elements from array using wildcard prefix
 Given a sample.yml file of:
 ```yaml
 - cat
@@ -19,7 +39,79 @@ cat
 goat
 ```
 
-## Select and update matching values in map
+## 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 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 + 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:
@@ -29,7 +121,7 @@ a:
 ```
 then
 ```bash
-yq eval '(.a.[] | select(. == "*at")) |= "rabbit"' sample.yml
+yq eval '(.a.[] | select(. == "cat" or . == "goat")) |= "rabbit"' sample.yml
 ```
 will output
 ```yaml