diff options
Diffstat (limited to 'doc/pcregrep.txt')
| -rw-r--r-- | doc/pcregrep.txt | 173 |
1 files changed, 138 insertions, 35 deletions
diff --git a/doc/pcregrep.txt b/doc/pcregrep.txt index 1dca003..c2374e1 100644 --- a/doc/pcregrep.txt +++ b/doc/pcregrep.txt @@ -6,7 +6,7 @@ NAME pcregrep - a grep with Perl-compatible regular expressions. SYNOPSIS - pcregrep [-Vcfhilnrsuvx] [long options] [pattern] [file1 file2 ...] + pcregrep [options] [long options] [pattern] [file1 file2 ...] DESCRIPTION @@ -20,61 +20,139 @@ DESCRIPTION A pattern must be specified on the command line unless the -f option is used (see below). - If no files are specified, pcregrep reads the standard input. By - default, each line that matches the pattern is copied to the standard - output, and if there is more than one file, the file name is printed - before each line of output. However, there are options that can change - how pcregrep behaves. + If no files are specified, pcregrep reads the standard input. The stan- + dard input can also be referenced by a name consisting of a single + hyphen. For example: - Lines are limited to BUFSIZ characters. BUFSIZ is defined in <stdio.h>. - The newline character is removed from the end of each line before it is - matched against the pattern. + pcregrep some-pattern /file1 - /file3 + By default, each line that matches the pattern is copied to the stan- + dard output, and if there is more than one file, the file name is + printed before each line of output. However, there are options that can + change how pcregrep behaves. In particular, the -M option makes it pos- + sible to search for patterns that span line boundaries. + + Patterns are limited to 8K or BUFSIZ characters, whichever is the + greater. BUFSIZ is defined in <stdio.h>. -OPTIONS +OPTIONS - -V Write the version number of the PCRE library being used to - the standard error stream. + -- This terminate the list of options. It is useful if the next + item on the command line starts with a hyphen, but is not an + option. + + -A number Print number lines of context after each matching line. If + file names and/or line numbers are being printed, a hyphen + separator is used instead of a colon for the context lines. A + line containing "--" is printed between each group of lines, + unless they are in fact contiguous in the input file. The + value of number is expected to be relatively small. However, + pcregrep guarantees to have up to 8K of following text avail- + able for context printing. + + -B number Print number lines of context before each matching line. If + file names and/or line numbers are being printed, a hyphen + separator is used instead of a colon for the context lines. A + line containing "--" is printed between each group of lines, + unless they are in fact contiguous in the input file. The + value of number is expected to be relatively small. However, + pcregrep guarantees to have up to 8K of preceding text avail- + able for context printing. + + -C number Print number lines of context both before and after each + matching line. This is equivalent to setting both -A and -B + to the same value. -c Do not print individual lines; instead just print a count of the number of lines that would otherwise have been printed. If several files are given, a count is printed for each of them. + --exclude=pattern + When pcregrep is searching the files in a directory as a con- + sequence of the -r (recursive search) option, any files whose + names match the pattern are excluded. The pattern is a PCRE + regular expression. If a file name matches both --include and + --exclude, it is excluded. There is no short form for this + option. + -ffilename - Read a number of patterns from the file, one per line, and - match all of them against each line of input. A line is out- - put if any of the patterns match it. When -f is used, no - pattern is taken from the command line; all arguments are - treated as file names. There is a maximum of 100 patterns. + Read a number of patterns from the file, one per line, and + match all of them against each line of input. A line is out- + put if any of the patterns match it. When -f is used, no + pattern is taken from the command line; all arguments are + treated as file names. There is a maximum of 100 patterns. Trailing white space is removed, and blank lines are ignored. - An empty file contains no patterns and therefore matches + An empty file contains no patterns and therefore matches nothing. -h Suppress printing of filenames when searching multiple files. -i Ignore upper/lower case distinctions during comparisons. - -l Instead of printing lines from the files, just print the - names of the files containing lines that would have been - printed. Each file name is printed once, on a separate line. + --include=pattern + When pcregrep is searching the files in a directory as a con- + sequence of the -r (recursive search) option, only files + whose names match the pattern are included. The pattern is a + PCRE regular expression. If a file name matches both + --include and --exclude, it is excluded. There is no short + form for this option. + + -L Instead of printing lines from the files, just print the + names of the files that do not contain any lines that would + have been printed. Each file name is printed once, on a sepa- + rate line. + + -l Instead of printing lines from the files, just print the + names of the files containing lines that would have been + printed. Each file name is printed once, on a separate line. + + --label=name + This option supplies a name to be used for the standard input + when file names are being printed. If not supplied, "(stan- + dard input)" is used. There is no short form for this option. + + -M Allow patterns to match more than one line. When this option + is given, patterns may usefully contain literal newline char- + acters and internal occurrences of ^ and $ characters. The + output for any one match may consist of more than one line. + When this option is set, the PCRE library is called in "mul- + tiline" mode. There is a limit to the number of lines that + can be matched, imposed by the way that pcregrep buffers the + input file as it scans it. However, pcregrep ensures that at + least 8K characters or the rest of the document (whichever is + the shorter) are available for forward matching, and simi- + larly the previous 8K characters (or all the previous charac- + ters, if fewer than 8K) are guaranteed to be available for + lookbehind assertions. -n Precede each line by its line number in the file. - -r If any file is a directory, recursively scan the files it - contains. Without -r a directory is scanned as a normal file. - - -s Work silently, that is, display nothing except error mes- - sages. The exit status indicates whether any matches were + -q Work quietly, that is, display nothing except error messages. + The exit status indicates whether or not any matches were found. + -r If any given path is a directory, recursively scan the files + it contains, taking note of any --include and --exclude set- + tings. Without -r a directory is scanned as a normal file. + + -s Suppress error messages about non-existent or unreadable + files. Such files are quietly skipped. However, the return + code is still 2, even if matches were found in other files. + -u Operate in UTF-8 mode. This option is available only if PCRE has been compiled with UTF-8 support. Both the pattern and each subject line must be valid strings of UTF-8 characters. - -v Invert the sense of the match, so that lines which do not - match the pattern are now the ones that are found. + -V Write the version numbers of pcregrep and the PCRE library + that is being used to the standard error stream. + + -v Invert the sense of the match, so that lines which do not + match the pattern are the ones that are found. + + -w Force the pattern to match only whole words. This is equiva- + lent to having \b at the start and end of the pattern. -x Force the pattern to be anchored (it must start matching at the beginning of the line) and in addition, require it to @@ -88,12 +166,22 @@ LONG OPTIONS Long forms of all the options are available, as in GNU grep. They are shown in the following table: + -A --after-context + -B --before-context + -C --context -c --count + --exclude (no short form) + -f --file -h --no-filename + --help (no short form) -i --ignore-case + --include (no short form) + -L --files-without-match -l --files-with-matches + --label (no short form) -n --line-number -r --recursive + -q --quiet -s --no-messages -u --utf-8 -V --version @@ -101,22 +189,37 @@ LONG OPTIONS -x --line-regex -x --line-regexp - In addition, --file=filename is equivalent to -ffilename, and --help - shows the list of options and then exits. + +OPTIONS WITH DATA + + There are four different ways in which an option with data can be spec- + ified. If a short form option is used, the data may follow immedi- + ately, or in the next command line item. For example: + + -f/some/file + -f /some/file + + If a long form option is used, the data may appear in the same command + line item, separated by an = character, or it may appear in the next + command line item. For example: + + --file=/some/file + --file /some/file DIAGNOSTICS Exit status is 0 if any matches were found, 1 if no matches were found, - and 2 for syntax errors or inacessible files (even if matches were - found). + and 2 for syntax errors and non-existent or inacessible files (even if + matches were found in other files). Using the -s option to suppress + error messages about inaccessble files does not affect the return code. AUTHOR - Philip Hazel <ph10@cam.ac.uk> + Philip Hazel University Computing Service Cambridge CB2 3QG, England. -Last updated: 09 September 2004 -Copyright (c) 1997-2004 University of Cambridge. +Last updated: 16 May 2005 +Copyright (c) 1997-2005 University of Cambridge. |