1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
.Dd December 9 2023
.Dt GRAB 1
.Os
.Sh NAME
.Nm grab
.Nd search for patterns in files
.Sh SYNOPSIS
.Nm
.Op Fl fnz
.Ar pattern
.Op Ar
.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 default behavior of
.Nm
is to print pattern matches to the standard-output.
If more than one file argument is provided,
matches will be prefixed by their respective filename and a colon.
Note that this behavior is modified by the
.Fl f
and
.Fl z
options.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl f , Fl Fl filenames
Always prefix matches with the names of the files in which the matches
were made,
even if only 1 file was provided.
.It Fl h , Fl Fl help
Display help information by opening this manual page.
.It Fl n , Fl Fl newline
Don’t match newline characters
.Pq Sq \en
with the dot
.Pq Sq \&.
operator in patterns,
or in negated character-classes.
.It Fl z , Fl Fl zero
Separate output data by null bytes
.Pq Sq \e0
instead of newlines.
This option can be used to process matches containing newlines.
.Pp
If combined with the
.Fl f
option,
or if two or more files were provided as arguments,
filenames and matches will be separated by null bytes instead of colons.
.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 ENVIRONMENT
.Bl -tag -width GRAB_COLOR_FNAME
.It Ev GRAB_COLOR_FNAME
The color(s) with which to highlight filenames,
or 35 if unset.
.It Ev GRAB_COLOR_SEPC
The color(s) with which to highlight the colon-separator between
filenames and matches,
or 36 if unset.
.It Ev NO_COLOR
Do not display any colored output when set to a non-empty string,
even if the standard-output is a terminal.
.El
.Pp
The
.Ev GRAB_COLOR_*
environment variables are SGR parameters.
For more information regarding SGR parameters see
.Sx SEE ALSO .
.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
.%A Rob Pike
.%D 1987
.%T Structural Regular Expressions
.%U https://doc.cat-v.org/bell_labs/structural_regexps/se.pdf
.Re
.Pp
.Lk https://en.wikipedia.org/wiki/ANSI_escape_code#SGR "SGR Parameters"
.Sh AUTHORS
.An Thomas Voss Aq Mt mail@thomasvoss.com
|
