/[pcre]/code/trunk/doc/html/pcregrep.html

Diff of /code/trunk/doc/html/pcregrep.html

Parent Directory | Revision Log | View Patch Patch

-revision 76 by nigel,
Sat Feb 24 21:40:37 2007 UTC
+revision 77 by nigel,
Sat Feb 24 21:40:45 2007 UTC
 Line 17 
 man page, in case the conversion went wr
  <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="TOC5" href="#SEC5">OPTIONS WITH DATA</a>
- <li><a name="TOC6" href="#SEC6">AUTHOR</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>
-Line 38 
 A pattern must be specified on the comma
+Line 39 
 A pattern must be specified on the comma
  used (see below).
  </P>
  <P>
- If no files are specified, <b>pcregrep</b> reads the standard input. By default,
+ If no files are specified, <b>pcregrep</b> reads the standard input. The
- each line that matches the pattern is copied to the standard output, and if
+ standard input can also be referenced by a name consisting of a single hyphen.
- there is more than one file, the file name is printed before each line of
+ For example:
- output. However, there are options that can change how <b>pcregrep</b> behaves.
+ <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>&#60;stdio.h&#62;</b>.
+ Patterns are limited to 8K or BUFSIZ characters, whichever is the greater.
- The newline character is removed from the end of each line before it is matched
+ BUFSIZ is defined in <b>&#60;stdio.h&#62;</b>.
- against the pattern.
  </P>
  <br><a name="SEC3" href="#TOC1">OPTIONS</a><br>
  <P>
- <b>-V</b>
+ <b>--</b>
- Write the version number of the PCRE library being used to the standard error
+ This terminate the list of options. It is useful if the next item on the
- stream.
+ 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>
-Line 61 
 lines that would otherwise have been pri
+Line 91 
 lines that would otherwise have been pri
  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.
-Line 78 
 Suppress printing of filenames when sear
+Line 116 
 Suppress printing of filenames when sear
  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.
+ Suppress error messages about non-existent or unreadable files. Such files are
- The exit status indicates whether any matches were found.
+ quietly skipped. However, the return code is still 2, even if matches were
+ found in other files.
  </P>
  <P>
  <b>-u</b>
-Line 104 
 with UTF-8 support. Both the pattern and
+Line 182 
 with UTF-8 support. Both the pattern and
  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>
-Line 120 
 alternative branch in the regular expres
+Line 208 
 alternative branch in the regular expres
  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
+ If a long form option is used, the data may appear in the same command line
- --help shows the list of options and then exits.
+ 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 &#60;ph10@cam.ac.uk&#62;
+ 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 &copy; 1997-2004 University of Cambridge.
+ Copyright &copy; 1997-2005 University of Cambridge.
  <p>
  Return to the <a href="index.html">PCRE index page</a>.
  </p>

 Legend:



Removed from v.76
 


changed lines


 
Added in v.77
 Legend:



Removed from v.76
 


changed lines


 
Added in v.77
-Removed from v.76
+Added in v.77

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12