aboutsummaryrefslogtreecommitdiff
path: root/man/grab.1
diff options
context:
space:
mode:
authorThomas Voss <mail@thomasvoss.com> 2024-01-18 19:32:00 +0100
committerThomas Voss <mail@thomasvoss.com> 2024-01-18 19:32:07 +0100
commit5540a3e46978fcd6dd1003479000b77b15ede5e2 (patch)
tree42fbe39152205b4af656bcdfc8c570c61f58e284 /man/grab.1
parent5344ff3d5f58593f749a2b36cf11b5d4f8485d88 (diff)
Update the manual page
Diffstat (limited to 'man/grab.1')
-rw-r--r--man/grab.192
1 files changed, 82 insertions, 10 deletions
diff --git a/man/grab.1 b/man/grab.1
index 1a4ab53..332ae35 100644
--- a/man/grab.1
+++ b/man/grab.1
@@ -1,4 +1,4 @@
-.Dd January 16 2024
+.Dd January 18 2024
.Dt GRAB 1
.Os
.Sh NAME
@@ -6,14 +6,14 @@
.Nd search for patterns in files
.Sh SYNOPSIS
.Nm
-.Op Fl cfnz
+.Op Fl cfnUz
.Ar pattern
.Op Ar
.Nm
.Fl h
.Pp
.Nm "git grab"
-.Op Fl cnz
+.Op Fl cnUz
.Ar pattern
.Op Ar glob ...
.Nm "git grab"
@@ -95,15 +95,30 @@ no color will be output.
Always prefix matches with the names of the files in which the matches
were made,
even if only 1 file was provided.
+.Pp
+This option is always enabled when using
+.Nm "git grab" .
.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
+Treat the newline as a special character by disallowing the dot
.Pq Sq \&.
-operator in patterns,
-or in negated character-classes.
+wildcard from matching newlines in regular expressions.
+.Pp
+This option may behave strangely when
+.Nm
+is not compiled with PCRE support.
+See
+.Sx CAVEATS
+for more information.
+.It Fl U , Fl Fl no-unicode
+Don’t use Unicode properties when matching \ed, \ew, etc.
+Recognize only ASCII values instead.
+.Pp
+If
+.Nm
+is not compiled with PCRE support this option will cause the program to
+terminate with exit status 2.
.It Fl z , Fl Fl zero
Separate output data by null bytes
.Pq Sq \e0
@@ -116,6 +131,22 @@ 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 Regular Expression Syntax
+By default
+.Nm
+supports Perl-compatible regular expressions
+.Pq Sq PCREs ,
+however it is possible to build and install
+.Nm
+without support for PCREs.
+When build without PCRE support,
+POSIX extended-regular-expressions are used instead.
+.Pp
+You should always assume that PCRE support is available,
+but if you would like to be absolutely sure you can check if the program
+terminates unsuccessfully when using the
+.Fl U
+option.
.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,
@@ -201,10 +232,26 @@ but only those which are being passed a
property —
searching all files in the current git-repository:
.Pp
-.Dl $ git grab 'x/<hb-form-text[^>]+>/ g/\ebplaceholder\eb/' '*.vue'
+.Dl $ git grab 'x/<hb-form-text.+?>/ g/\ebplaceholder\eb/' '*.vue'
+.Pp
+Extract bibliographic references from
+.Xr mdoc 7
+formatted manual pages:
+.Pp
+.Dl $ grab -n 'x/(^\e.%.*\en)+/' foo.1 bar.1
+.Pp
+Extract the
+.Sx SYNOPSIS
+section from the given
+.Xr mdoc 7
+formatted manual pages:
+.Pp
+.Dl $ grab -n 'x/^\.Sh SYNOPSIS\en(^.*\en(?!^\e.Sh))+/' foo.1 bar.1
.Sh SEE ALSO
.Xr git-ls-files 1 ,
-.Xr grep 1
+.Xr grep 1 ,
+.Xr pcre2syntax 3 ,
+.Xr regex 7
.Rs
.%A Rob Pike
.%D 1987
@@ -215,3 +262,28 @@ searching all files in the current git-repository:
.Lk https://en.wikipedia.org/wiki/ANSI_escape_code#SGR "SGR Parameters"
.Sh AUTHORS
.An Thomas Voss Aq Mt mail@thomasvoss.com
+.Sh CAVEATS
+The behavior of negated character classes in regular expressions will
+vary when given the
+.Fl n
+option depending on if PCRE support is or isn’t available.
+.Pp
+When PCRE support is available and the
+.Fl n
+option is provided,
+the regular expression
+.Ql [^a]
+will nontheless match the newline character.
+When PCRE support is not available and the
+.Fl n
+option is provided,
+the newline will
+.Em not
+be matched by
+.Ql [^a] .
+.Sh BUGS
+When writing pattern matches to the standard output,
+.Nm
+appends a newline to the end of the match.
+This often results in non-ideal output as matched patterns are often
+already suffixed by a newline.