diff options
Diffstat (limited to 'man/grab.1')
| -rw-r--r-- | man/grab.1 | 189 |
1 files changed, 189 insertions, 0 deletions
diff --git a/man/grab.1 b/man/grab.1 new file mode 100644 index 0000000..8bd2e9e --- /dev/null +++ b/man/grab.1 @@ -0,0 +1,189 @@ +.Dd January 12 2024 +.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 +.Pp +.Nm "git grab" +.Op Fl nz +.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 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 +.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 |