diff options
Diffstat (limited to 'doc/html/pcregrep.html')
| -rw-r--r-- | doc/html/pcregrep.html | 166 |
1 files changed, 141 insertions, 25 deletions
diff --git a/doc/html/pcregrep.html b/doc/html/pcregrep.html index 922487d..614034d 100644 --- a/doc/html/pcregrep.html +++ b/doc/html/pcregrep.html @@ -17,12 +17,13 @@ man page, in case the conversion went wrong. <li><a name="TOC2" href="#SEC2">DESCRIPTION</a> <li><a name="TOC3" href="#SEC3">OPTIONS</a> <li><a name="TOC4" href="#SEC4">LONG OPTIONS</a> -<li><a name="TOC5" href="#SEC5">DIAGNOSTICS</a> -<li><a name="TOC6" href="#SEC6">AUTHOR</a> +<li><a name="TOC5" href="#SEC5">OPTIONS WITH DATA</a> +<li><a name="TOC6" href="#SEC6">DIAGNOSTICS</a> +<li><a name="TOC7" href="#SEC7">AUTHOR</a> </ul> <br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br> <P> -<b>pcregrep [-Vcfhilnrsuvx] [long options] [pattern] [file1 file2 ...]</b> +<b>pcregrep [options] [long options] [pattern] [file1 file2 ...]</b> </P> <br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br> <P> @@ -38,21 +39,50 @@ A pattern must be specified on the command line unless the <b>-f</b> option is used (see below). </P> <P> -If no files are specified, <b>pcregrep</b> 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 <b>pcregrep</b> behaves. +If no files are specified, <b>pcregrep</b> reads the standard input. The +standard input can also be referenced by a name consisting of a single hyphen. +For example: +<pre> + pcregrep some-pattern /file1 - /file3 +</pre> +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 +<b>pcregrep</b> behaves. In particular, the <b>-M</b> option makes it possible to +search for patterns that span line boundaries. </P> <P> -Lines are limited to BUFSIZ characters. BUFSIZ is defined in <b><stdio.h></b>. -The newline character is removed from the end of each line before it is matched -against the pattern. +Patterns are limited to 8K or BUFSIZ characters, whichever is the greater. +BUFSIZ is defined in <b><stdio.h></b>. </P> <br><a name="SEC3" href="#TOC1">OPTIONS</a><br> <P> -<b>-V</b> -Write the version number of the PCRE library being used to the standard error -stream. +<b>--</b> +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. +</P> +<P> +<b>-A</b> <i>number</i> +Print <i>number</i> 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 <i>number</i> is expected to be relatively small. However, <b>pcregrep</b> +guarantees to have up to 8K of following text available for context printing. +</P> +<P> +<b>-B</b> <i>number</i> +Print <i>number</i> 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 <i>number</i> is expected to be relatively small. However, <b>pcregrep</b> +guarantees to have up to 8K of preceding text available for context printing. +</P> +<P> +<b>-C</b> <i>number</i> +Print <i>number</i> lines of context both before and after each matching line. +This is equivalent to setting both <b>-A</b> and <b>-B</b> to the same value. </P> <P> <b>-c</b> @@ -61,6 +91,14 @@ lines that would otherwise have been printed. If several files are given, a count is printed for each of them. </P> <P> +<b>--exclude</b>=<i>pattern</i> +When <b>pcregrep</b> is searching the files in a directory as a consequence of +the <b>-r</b> (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 <b>--include</b> and <b>--exclude</b>, it is excluded. There is no short +form for this option. +</P> +<P> <b>-f</b><i>filename</i> Read a number of patterns from the file, one per line, and match all of them against each line of input. A line is output if any of the patterns match it. @@ -78,24 +116,64 @@ Suppress printing of filenames when searching multiple files. Ignore upper/lower case distinctions during comparisons. </P> <P> +<b>--include</b>=<i>pattern</i> +When <b>pcregrep</b> is searching the files in a directory as a consequence of +the <b>-r</b> (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 <b>--include</b> and <b>--exclude</b>, it is excluded. There is no +short form for this option. +</P> +<P> +<b>-L</b> +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 separate line. +</P> +<P> <b>-l</b> 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. </P> <P> +<b>--label</b>=<i>name</i> +This option supplies a name to be used for the standard input when file names +are being printed. If not supplied, "(standard input)" is used. There is no +short form for this option. +</P> +<P> +<b>-M</b> +Allow patterns to match more than one line. When this option is given, patterns +may usefully contain literal newline characters 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 "multiline" mode. +There is a limit to the number of lines that can be matched, imposed by the way +that <b>pcregrep</b> buffers the input file as it scans it. However, +<b>pcregrep</b> ensures that at least 8K characters or the rest of the document +(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. +</P> +<P> <b>-n</b> Precede each line by its line number in the file. </P> <P> +<b>-q</b> +Work quietly, that is, display nothing except error messages. +The exit status indicates whether or not any matches were found. +</P> +<P> <b>-r</b> -If any file is a directory, recursively scan the files it contains. Without +If any given path is a directory, recursively scan the files it contains, +taking note of any <b>--include</b> and <b>--exclude</b> settings. Without <b>-r</b> a directory is scanned as a normal file. </P> <P> <b>-s</b> -Work silently, that is, display nothing except error messages. -The exit status indicates whether any matches were found. +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. </P> <P> <b>-u</b> @@ -104,9 +182,19 @@ with UTF-8 support. Both the pattern and each subject line must be valid strings of UTF-8 characters. </P> <P> +<b>-V</b> +Write the version numbers of <b>pcregrep</b> and the PCRE library that is being +used to the standard error stream. +</P> +<P> <b>-v</b> Invert the sense of the match, so that lines which do <i>not</i> match the -pattern are now the ones that are found. +pattern are the ones that are found. +</P> +<P> +<b>-w</b> +Force the pattern to match only whole words. This is equivalent to having \b +at the start and end of the pattern. </P> <P> <b>-x</b> @@ -120,39 +208,67 @@ alternative branch in the regular expression. Long forms of all the options are available, as in GNU grep. They are shown in the following table: <pre> + -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 -v --invert-match -x --line-regex -x --line-regexp +</PRE> +</P> +<br><a name="SEC5" href="#TOC1">OPTIONS WITH DATA</a><br> +<P> +There are four different ways in which an option with data can be specified. +If a short form option is used, the data may follow immediately, or in the next +command line item. For example: +<pre> + -f/some/file + -f /some/file </pre> -In addition, --file=<i>filename</i> is equivalent to -f<i>filename</i>, and ---help shows the list of options and then exits. +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: +<pre> + --file=/some/file + --file /some/file + +</PRE> </P> -<br><a name="SEC5" href="#TOC1">DIAGNOSTICS</a><br> +<br><a name="SEC6" href="#TOC1">DIAGNOSTICS</a><br> <P> 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). +for syntax errors and non-existent or inacessible files (even if matches were +found in other files). Using the <b>-s</b> option to suppress error messages +about inaccessble files does not affect the return code. </P> -<br><a name="SEC6" href="#TOC1">AUTHOR</a><br> +<br><a name="SEC7" href="#TOC1">AUTHOR</a><br> <P> -Philip Hazel <ph10@cam.ac.uk> +Philip Hazel <br> University Computing Service <br> Cambridge CB2 3QG, England. </P> <P> -Last updated: 09 September 2004 +Last updated: 16 May 2005 <br> -Copyright © 1997-2004 University of Cambridge. +Copyright © 1997-2005 University of Cambridge. <p> Return to the <a href="index.html">PCRE index page</a>. </p> |