walkero
/
pcre2
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Documentation update.

This commit is contained in:
Philip.Hazel 2016-10-31 19:04:22 +00:00
parent 0ea3274a53
commit ee3b0feec0
1 changed files with 38 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
doc/pcre2grep.1
View File

@ -1,4 +1,4 @@
.TH PCRE2GREP 1 "16 October 2016" "PCRE2 10.23" .TH PCRE2GREP 1 "31 October 2016" "PCRE2 10.23"
.SH NAME .SH NAME
pcre2grep - a grep with Perl-compatible regular expressions. pcre2grep - a grep with Perl-compatible regular expressions.
.SH SYNOPSIS .SH SYNOPSIS
@ -139,8 +139,7 @@ processing buffer size has been set too small. If file names and/or line
numbers are being output, a hyphen separator is used instead of a colon for the numbers are being output, a hyphen separator is used instead of a colon for the
context lines. A line containing "--" is output between each group of lines, context lines. A line containing "--" is output between each group of lines,
unless they are in fact contiguous in the input file. The value of \fInumber\fP unless they are in fact contiguous in the input file. The value of \fInumber\fP
is expected to be relatively small. However, \fBpcre2grep\fP guarantees to have is expected to be relatively small. When \fB-c\fP is used, \fB-A\fP is ignored.
up to 8K of following text available for context output.
.TP .TP
\fB-a\fP, \fB--text\fP \fB-a\fP, \fB--text\fP
Treat binary files as text. This is equivalent to Treat binary files as text. This is equivalent to
@ -153,9 +152,8 @@ lines are output if the previous match or the start of the file is within
file names and/or line numbers are being output, a hyphen separator is used file names and/or line numbers are being output, a hyphen separator is used
instead of a colon for the context lines. A line containing "--" is output instead of a colon for the context lines. A line containing "--" is output
between each group of lines, unless they are in fact contiguous in the input between each group of lines, unless they are in fact contiguous in the input
file. The value of \fInumber\fP is expected to be relatively small. However, file. The value of \fInumber\fP is expected to be relatively small. When
\fBpcre2grep\fP guarantees to have up to 8K of preceding text available for \fB-c\fP is used, \fB-B\fP is ignored.
context output.
.TP .TP
\fB--binary-files=\fP\fIword\fP \fB--binary-files=\fP\fIword\fP
Specify how binary files are to be processed. If the word is "binary" (the Specify how binary files are to be processed. If the word is "binary" (the
@ -182,9 +180,9 @@ This is equivalent to setting both \fB-A\fP and \fB-B\fP to the same value.
Do not output lines from the files that are being scanned; instead output the Do not output lines from the files that are being scanned; instead output the
number of lines that would have been shown, either because they matched, or, if number of lines that would have been shown, either because they matched, or, if
\fB-v\fP is set, because they failed to match. By default, this count is \fB-v\fP is set, because they failed to match. By default, this count is
exactly the same as the number of suppressed lines, but if the \fB-M\fP exactly the same as the number of lines that would have been output, but if the
(multiline) option is used (without \fB-v\fP), there may be more suppressed \fB-M\fP (multiline) option is used (without \fB-v\fP), there may be more
lines than the number of matches. suppressed lines than the count (that is, the number of matches).
.sp .sp
If no lines are selected, the number zero is output. If several files are are If no lines are selected, the number zero is output. If several files are are
being scanned, a count is output for each of them and the \fB-t\fP option can being scanned, a count is output for each of them and the \fB-t\fP option can
@ -289,22 +287,22 @@ files; it does not apply to patterns specified by any of the \fB--include\fP or
\fB--exclude\fP options. \fB--exclude\fP options.
.TP .TP
\fB-f\fP \fIfilename\fP, \fB--file=\fP\fIfilename\fP \fB-f\fP \fIfilename\fP, \fB--file=\fP\fIfilename\fP
Read patterns from the file, one per line, and match them against Read patterns from the file, one per line, and match them against each line of
each line of input. What constitutes a newline when reading the file is the input. What constitutes a newline when reading the file is the operating
operating system's default. The \fB--newline\fP option has no effect on this system's default. The \fB--newline\fP option has no effect on this option.
option. Trailing white space is removed from each line, and blank lines are Trailing white space is removed from each line, and blank lines are ignored. An
ignored. An empty file contains no patterns and therefore matches nothing. See empty file contains no patterns and therefore matches nothing. See also the
also the comments about multiple patterns versus a single pattern with comments about multiple patterns versus a single pattern with alternatives in
alternatives in the description of \fB-e\fP above. the description of \fB-e\fP above.
.sp .sp
If this option is given more than once, all the specified files are If this option is given more than once, all the specified files are read. A
read. A data line is output if any of the patterns match it. A file name can data line is output if any of the patterns match it. A file name can be given
be given as "-" to refer to the standard input. When \fB-f\fP is used, patterns as "-" to refer to the standard input. When \fB-f\fP is used, patterns
specified on the command line using \fB-e\fP may also be present; they are specified on the command line using \fB-e\fP may also be present; they are
tested before the file's patterns. However, no other pattern is taken from the tested before the file's patterns. However, no other pattern is taken from the
command line; all arguments are treated as the names of paths to be searched. command line; all arguments are treated as the names of paths to be searched.
.TP .TP
\fB--file-list\fP=\fIfilename\fP \fB--file-list\fP=\fIfilename\fP
Read a list of files and/or directories that are to be scanned from the given Read a list of files and/or directories that are to be scanned from the given
file, one per line. Trailing white space is removed from each line, and blank file, one per line. Trailing white space is removed from each line, and blank
lines are ignored. These paths are processed before any that are listed on the lines are ignored. These paths are processed before any that are listed on the
@ -454,20 +452,17 @@ set by \fB--buffer-size\fP. The maximum buffer size is silently forced to be no
smaller than the starting buffer size. smaller than the starting buffer size.
.TP .TP
\fB-M\fP, \fB--multiline\fP \fB-M\fP, \fB--multiline\fP
Allow patterns to match more than one line. When this option is given, patterns Allow patterns to match more than one line. When this option is set, the PCRE2
may usefully contain literal newline characters and internal occurrences of ^ library is called in "multiline" mode. This allows a matched string to extend
and $ characters. The output for a successful match may consist of more than past the end of a line and continue on one or more subsequent lines. Patterns
one line. The first is the line in which the match started, and the last is the used with \fB-M\fP may usefully contain literal newline characters and internal
line in which the match ended. If the matched string ends with a newline occurrences of ^ and $ characters. The output for a successful match may
sequence the output ends at the end of that line. consist of more than one line. The first line is the line in which the match
.sp started, and the last line is the line in which the match ended. If the matched
When this option is set, the PCRE2 library is called in "multiline" mode. This string ends with a newline sequence, the output ends at the end of that line.
allows a matched string to extend past the end of a line and continue on one or If \fB-v\fP is set, none of the lines in a multi-line match are output. Once a
more subsequent lines. However, \fBpcre2grep\fP still processes the input line match has been handled, scanning restarts at the beginning of the line after
by line. Once a match has been handled, scanning restarts at the beginning of the one in which the match ended.
the next line, just as it does when \fB-M\fP is not present. This means that it
is possible for the second or subsequent lines in a multiline match to be
output again as part of another match.
.sp .sp
The newline sequence that separates multiple lines must be matched as part of The newline sequence that separates multiple lines must be matched as part of
the pattern. For example, to find the phrase "regular expression" in a file the pattern. For example, to find the phrase "regular expression" in a file
@ -481,11 +476,8 @@ and is followed by + so as to match trailing white space on the first line as
well as possibly handling a two-character newline sequence. well as possibly handling a two-character newline sequence.
.sp .sp
There is a limit to the number of lines that can be matched, imposed by the way There is a limit to the number of lines that can be matched, imposed by the way
that \fBpcre2grep\fP buffers the input file as it scans it. However, that \fBpcre2grep\fP buffers the input file as it scans it. With a sufficiently
\fBpcre2grep\fP ensures that at least 8K characters or the rest of the file large processing buffer, this should not be a problem, but the \fB-M\fP option
(whichever is the shorter) are available for forward matching, and similarly
the previous 8K characters (or all the previous characters, if fewer than 8K)
are guaranteed to be available for lookbehind assertions. The \fB-M\fP option
does not work when input is read line by line (see \fP--line-buffered\fP.) does not work when input is read line by line (see \fP--line-buffered\fP.)
.TP .TP
\fB-N\fP \fInewline-type\fP, \fB--newline\fP=\fInewline-type\fP \fB-N\fP \fInewline-type\fP, \fB--newline\fP=\fInewline-type\fP
@ -609,11 +601,12 @@ specified by any of the \fB--include\fP or \fB--exclude\fP options.
.TP .TP
\fB-x\fP, \fB--line-regex\fP, \fB--line-regexp\fP \fB-x\fP, \fB--line-regex\fP, \fB--line-regexp\fP
Force the patterns to be anchored (each must start matching at the beginning of Force the patterns to be anchored (each must start matching at the beginning of
a line) and in addition, require them to match entire lines. This is equivalent a line) and in addition, require them to match entire lines. In multiline mode
to having ^ and $ characters at the start and end of each alternative top-level the match may be more than one line. This is equivalent to having \eA and \eZ
branch in every pattern. This option applies only to the patterns that are characters at the start and end of each alternative top-level branch in every
matched against the contents of files; it does not apply to patterns specified pattern. This option applies only to the patterns that are matched against the
by any of the \fB--include\fP or \fB--exclude\fP options. contents of files; it does not apply to patterns specified by any of the
\fB--include\fP or \fB--exclude\fP options.
. .
. .
.SH "ENVIRONMENT VARIABLES" .SH "ENVIRONMENT VARIABLES"
@ -791,6 +784,6 @@ Cambridge, England.
.rs .rs
.sp .sp
.nf .nf
Last updated: 16 October 2016 Last updated: 31 October 2016
Copyright (c) 1997-2016 University of Cambridge. Copyright (c) 1997-2016 University of Cambridge.
.fi .fi