aboutsummaryrefslogtreecommitdiff
path: root/grab.1
diff options
context:
space:
mode:
authorThomas Voss <mail@thomasvoss.com> 2023-12-10 18:42:01 +0100
committerThomas Voss <mail@thomasvoss.com> 2023-12-10 18:42:01 +0100
commit9b8caac033386c242c1ef774c0cd738c8ff9c09a (patch)
tree32c6d2332ee75ff319fa0cace36cddf119f8e3a5 /grab.1
parent4ab5cfd1efd080b9c5d428679952ba70e7ea77de (diff)
Write initial manual pagev1.0.0
Diffstat (limited to 'grab.1')
-rw-r--r--grab.170
1 files changed, 70 insertions, 0 deletions
diff --git a/grab.1 b/grab.1
index 147fe4f..4d18f9a 100644
--- a/grab.1
+++ b/grab.1
@@ -12,9 +12,79 @@
.Nm
.Fl h
.Sh DESCRIPTION
+The
+.Nm
+utility searches for text in files corresponding to
+.Ar pattern
+and prints the corresponding matches to the standard output.
+Unlike the
+.Xr grep 1
+utility,
+.Nm
+is not strictly line-oriented;
+instead of always matching on complete lines,
+the user defines the structure of the text they would like to match and
+filters on the results.
+For more details on the pattern syntax, see
+.Sx Pattern Syntax .
+.Pp
+.Nm
+will read from the files provided on the command-line.
+If no files are provided, the standard input will be read instead.
+The special filename
+.Sq -
+can also be provided,
+which represents the standard input.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl h
+Display help information by opening this manual page.
+.It Fl z
+Separate output data by null bytes
+.Pq Sq \e0
+instead of newlines.
+This option can be used to process matches containing newlines.
+.El
+.Ss Pattern Syntax
+A pattern is a sequences of commands optionally separated by whitespace.
+A command is an operator followed by a delimiter, a regular expression,
+and then terminated by the same delimiter. The last command of a pattern
+need not have a terminating delimiter.
+.Pp
+The supported operators are as follows:
+.Bl -tag -compact
+.It g
+Keep selections that match the given regex.
+.It v
+Discard selections that match the given regex.
+.It x
+Select everything that matches the given regex.
+.It y
+Select everything that doesn’t match the given regex.
+.El
+.Pp
+An example pattern to match all numbers that contain a ‘3’ but aren’t
+‘1337’ could be
+.Sq x/[0-9]+/ g/3/ v/^1337$/ .
+In that pattern,
+.Sq x/[0-9]+/
+selects all numbers in the input,
+.Sq g/3/
+keeps only those matches that contain the number 3,
+and
+.Sq v/^1337$/
+filters out the specific number 1337.
+.Pp
+As you may use whichever delimiter you like, the following is also valid:
+.Pp
+.Dl x|[0-9]+| g.3. v#^1337#
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
+List all your systems CPU flags, sorted and without duplicates:
+.Pp
+.Dl $ grab 'x/^flags.*/ x/\ew+/ v/flags/' | sort | uniq
.Sh SEE ALSO
.Xr grep 1
.Rs