From 2ba03c4c118ed43517df6ef803e34e81e81f374f Mon Sep 17 00:00:00 2001
From: Thomas Voss <mail@thomasvoss.com>
Date: Sun, 10 Dec 2023 15:23:33 +0100
Subject: Update README

---
 README.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 54 insertions(+), 9 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 14e5546..6fc3971 100644
--- a/README.md
+++ b/README.md
@@ -14,19 +14,64 @@ command is optional.
 
 For example, a pattern string may look like ‘`x/[a-z]+/ g.foo. v/bar/`’.
 
-The available operators are ‘g’, ‘v’, and ‘x’.  The ‘x' operator iterates
-over all matches of the corresponding regex.  This means that to print
-all numbers in a file, you can use the pattern string ‘`x/[0-9]+/`’.  The
-‘g’ and ‘v’ operators are filters.  The ‘g’ operator discards all results
-that don’t match the given regex, while the ‘v’ operator discards all
-results that *do* match the given regex.  This means that to select all
-numbers in a file that contain a ‘3’ but are not ‘1337’, you can use the
-pattern string ‘`x/[0-9]+/ g/3/ v/^1337$/`’.
+The available operators are ‘g’, ‘v’, ‘x’, and ‘y’.  The ‘g’ and ‘v’
+operators are filter operators, while ‘x’ and ‘y’ are selection
+operators.
+
+You probably want to begin your pattern with a selection operator.  By
+default the entire contents of the file you’re searching through will be
+selected, but you probably want to shrink that down to a specific query.
+With ‘x’ you can specify what text you want to select in the file.  For
+example ‘`x/[0-9]+/`’ will select all numbers:
+
+```sh
+echo 'foo12bar34baz' | grab 'x/[0-9]+/'
+# ⇒ 12
+# ⇒ 34
+```
+
+The ‘y’ operator works in reverse, selecting everything that _doesn’t_
+match the given regex:
+
+```sh
+echo 'foo12bar34baz' | grab 'y/[0-9]+/'
+# ⇒ foo
+# ⇒ bar
+# ⇒ baz
+```
+
+You can additionally use filter operators to keep or discard certain
+results.  The ‘g’ operator will filter out any results that don’t match
+the given regex, while the ‘v’ operator will do the opposite.  To select
+all numbers that contain a ‘3’ we can thus do:
+
+``` sh
+echo 'foo12bar34baz' | grab 'x/[0-9]+/ g/3/'
+# ⇒ 34
+
+# If we had used ‘x’ instead of ‘g’, the result would have just been ‘3’.
+# Filter operators do not modify the selections; they merely filter them.
+```
+
+Likewise to select all numbers that don’t contain a ‘3’:
+
+```sh
+echo 'foo12bar34baz' | grab 'x/[0-9]+/ v/3/'
+# ⇒ 12
+```
+
+You can also chain these together.  To get all numbers in a file that
+contain a ‘3’ but aren’t the specific number ‘1337’, we could do the
+following:
+
+```sh
+grab 'x/[0-9]+/ g/3/ v/^1337$/' /foo/bar
+```
 
 
 ## Examples
 
-Get a list of your CPU flags.
+### Get a list of your CPU flags.
 
 ```sh
 # With Grep
-- 
cgit v1.2.3