.Dd January 16 2024
.Dt GRAB 1
.Os
.Sh NAME
.Nm grab
.Nd search for patterns in files
.Sh SYNOPSIS
.Nm
.Op Fl cfnz
.Ar pattern
.Op Ar
.Nm
.Fl h
.Pp
.Nm "git grab"
.Op Fl cnz
.Ar pattern
.Op Ar glob ...
.Nm "git grab"
.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
The
.Nm git-grab
utility is identical to the
.Nm
utility in all ways except for two exceptions.
The first is that if no files
.Pq globs in this case to be precise
are specified,
input is not read from the standard-input but instead all files returned
by an invocation of
.Xr git-ls-files 1
are processed.
If the user provides one or more globs,
only the files returned by
.Xr git-ls-files 1
that match one or more of the given globs will be processed.
Secondly, the
.Fl f
option is not available;
its behavior is always assumed and cannot be disabled.
.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 c , Fl Fl color
Force colored output,
even if the output device is not a TTY.
This is useful when piping the output of
.Nm
into a pager such as
.Xr less 1 .
.Pp
Even when this option is specified,
if the
.Ev TERM
environment variable is set to
.Sq dumb ,
no color will be output.
.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.
.It Ev TERM
If set to
.Sq dumb
disables colored output,
even when the
.Fl c
option is provided.
.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
.Pp
Search for a pattern in multiple files without printing filenames:
.Pp
.Dl $ cat file1 file2 file3 | grab 'x/pattern/'
.Pp
Search for usages of an
.Ql <hb-form-text>
Vue component —
but only those which are being passed a
.Ql placeholder
property —
searching all files in the current git-repository:
.Pp
.Dl $ git grab 'x/<hb-form-text[^>]+>/ g/\ebplaceholder\eb/' '*.vue'
.Sh SEE ALSO
.Xr git-ls-files 1 ,
.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