/[pcre]/code/trunk/doc/pcregrep.txt
ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 953 by ph10, Sun Sep 11 14:31:21 2011 UTC revision 954 by ph10, Sat Mar 31 18:09:26 2012 UTC
# Line 98  SUPPORT FOR COMPRESSED FILES Line 98  SUPPORT FOR COMPRESSED FILES
98         so treated.         so treated.
99    
100    
101    BINARY FILES
102    
103           By default, a file that contains a binary zero byte  within  the  first
104           1024  bytes is identified as a binary file, and is processed specially.
105           (GNU grep also  identifies  binary  files  in  this  manner.)  See  the
106           --binary-files  option for a means of changing the way binary files are
107           handled.
108    
109    
110  OPTIONS  OPTIONS
111    
112         The order in which some of the options appear can  affect  the  output.         The order in which some of the options appear can  affect  the  output.
# Line 121  OPTIONS Line 130  OPTIONS
130                   pcregrep guarantees to have up to 8K of following text avail-                   pcregrep guarantees to have up to 8K of following text avail-
131                   able for context output.                   able for context output.
132    
133           -a, --text
134                     Treat binary files as text. This is equivalent  to  --binary-
135                     files=text.
136    
137         -B number, --before-context=number         -B number, --before-context=number
138                   Output number lines of context before each matching line.  If                   Output  number lines of context before each matching line. If
139                   filenames and/or line numbers are being output, a hyphen sep-                   filenames and/or line numbers are being output, a hyphen sep-
140                   arator is used instead of a colon for the  context  lines.  A                   arator  is  used  instead of a colon for the context lines. A
141                   line  containing  "--" is output between each group of lines,                   line containing "--" is output between each group  of  lines,
142                   unless they are in fact contiguous in  the  input  file.  The                   unless  they  are  in  fact contiguous in the input file. The
143                   value  of number is expected to be relatively small. However,                   value of number is expected to be relatively small.  However,
144                   pcregrep guarantees to have up to 8K of preceding text avail-                   pcregrep guarantees to have up to 8K of preceding text avail-
145                   able for context output.                   able for context output.
146    
147           --binary-files=word
148                     Specify how binary files are to be processed. If the word  is
149                     "binary"  (the  default),  pattern  matching  is performed on
150                     binary files, but the only  output  is  "Binary  file  <name>
151                     matches"  when a match succeeds. If the word is "text", which
152                     is equivalent to the -a or --text option,  binary  files  are
153                     processed  in  the  same way as any other file. In this case,
154                     when a match succeeds, the  output  may  be  binary  garbage,
155                     which  can  have  nasty effects if sent to a terminal. If the
156                     word is  "without-match",  which  is  equivalent  to  the  -I
157                     option,  binary  files  are  not  processed  at all; they are
158                     assumed not to be of interest.
159    
160         --buffer-size=number         --buffer-size=number
161                   Set  the  parameter that controls how much memory is used for                   Set the parameter that controls how much memory is  used  for
162                   buffering files that are being scanned.                   buffering files that are being scanned.
163    
164         -C number, --context=number         -C number, --context=number
165                   Output number lines of context both  before  and  after  each                   Output  number  lines  of  context both before and after each
166                   matching  line.  This is equivalent to setting both -A and -B                   matching line.  This is equivalent to setting both -A and  -B
167                   to the same value.                   to the same value.
168    
169         -c, --count         -c, --count
170                   Do not output individual lines from the files that are  being                   Do  not output individual lines from the files that are being
171                   scanned; instead output the number of lines that would other-                   scanned; instead output the number of lines that would other-
172                   wise have been shown. If no lines are  selected,  the  number                   wise  have  been  shown. If no lines are selected, the number
173                   zero  is  output.  If  several files are are being scanned, a                   zero is output. If several files are  are  being  scanned,  a
174                   count is output for each of them. However,  if  the  --files-                   count  is  output  for each of them. However, if the --files-
175                   with-matches  option  is  also  used,  only those files whose                   with-matches option is also  used,  only  those  files  whose
176                   counts are greater than zero are listed. When -c is used, the                   counts are greater than zero are listed. When -c is used, the
177                   -A, -B, and -C options are ignored.                   -A, -B, and -C options are ignored.
178    
179         --colour, --color         --colour, --color
180                   If this option is given without any data, it is equivalent to                   If this option is given without any data, it is equivalent to
181                   "--colour=auto".  If data is required, it must  be  given  in                   "--colour=auto".   If  data  is required, it must be given in
182                   the same shell item, separated by an equals sign.                   the same shell item, separated by an equals sign.
183    
184         --colour=value, --color=value         --colour=value, --color=value
185                   This option specifies under what circumstances the parts of a                   This option specifies under what circumstances the parts of a
186                   line that matched a pattern should be coloured in the output.                   line that matched a pattern should be coloured in the output.
187                   By  default,  the output is not coloured. The value (which is                   By default, the output is not coloured. The value  (which  is
188                   optional, see above) may be "never", "always", or "auto".  In                   optional,  see above) may be "never", "always", or "auto". In
189                   the  latter case, colouring happens only if the standard out-                   the latter case, colouring happens only if the standard  out-
190                   put is connected to a terminal. More resources are used  when                   put  is connected to a terminal. More resources are used when
191                   colouring  is enabled, because pcregrep has to search for all                   colouring is enabled, because pcregrep has to search for  all
192                   possible matches in a line, not just one, in order to  colour                   possible  matches in a line, not just one, in order to colour
193                   them all.                   them all.
194    
195                   The colour that is used can be specified by setting the envi-                   The colour that is used can be specified by setting the envi-
196                   ronment variable PCREGREP_COLOUR or PCREGREP_COLOR. The value                   ronment variable PCREGREP_COLOUR or PCREGREP_COLOR. The value
197                   of this variable should be a string of two numbers, separated                   of this variable should be a string of two numbers, separated
198                   by a semicolon. They are copied  directly  into  the  control                   by  a  semicolon.  They  are copied directly into the control
199                   string  for  setting  colour  on  a  terminal,  so it is your                   string for setting colour  on  a  terminal,  so  it  is  your
200                   responsibility to ensure that they make sense. If neither  of                   responsibility  to ensure that they make sense. If neither of
201                   the  environment  variables  is  set,  the default is "1;31",                   the environment variables is  set,  the  default  is  "1;31",
202                   which gives red.                   which gives red.
203    
204         -D action, --devices=action         -D action, --devices=action
205                   If an input path is  not  a  regular  file  or  a  directory,                   If  an  input  path  is  not  a  regular file or a directory,
206                   "action"  specifies  how  it is to be processed. Valid values                   "action" specifies how it is to be  processed.  Valid  values
207                   are "read" (the default) or "skip" (silently skip the path).                   are "read" (the default) or "skip" (silently skip the path).
208    
209         -d action, --directories=action         -d action, --directories=action
210                   If an input path is a directory, "action" specifies how it is                   If an input path is a directory, "action" specifies how it is
211                   to  be  processed.   Valid  values  are "read" (the default),                   to be processed.  Valid  values  are  "read"  (the  default),
212                   "recurse" (equivalent to the -r option), or "skip"  (silently                   "recurse"  (equivalent to the -r option), or "skip" (silently
213                   skip  the path). In the default case, directories are read as                   skip the path). In the default case, directories are read  as
214                   if they were ordinary files. In some  operating  systems  the                   if  they  were  ordinary files. In some operating systems the
215                   effect  of reading a directory like this is an immediate end-                   effect of reading a directory like this is an immediate  end-
216                   of-file.                   of-file.
217    
218         -e pattern, --regex=pattern, --regexp=pattern         -e pattern, --regex=pattern, --regexp=pattern
219                   Specify a pattern to be matched. This option can be used mul-                   Specify a pattern to be matched. This option can be used mul-
220                   tiple times in order to specify several patterns. It can also                   tiple times in order to specify several patterns. It can also
221                   be used as a way of specifying a single pattern  that  starts                   be  used  as a way of specifying a single pattern that starts
222                   with  a hyphen. When -e is used, no argument pattern is taken                   with a hyphen. When -e is used, no argument pattern is  taken
223                   from the command line; all  arguments  are  treated  as  file                   from  the  command  line;  all  arguments are treated as file
224                   names.  There is an overall maximum of 100 patterns. They are                   names. There is an overall maximum of 100 patterns. They  are
225                   applied to each line in the order in which they  are  defined                   applied  to  each line in the order in which they are defined
226                   until one matches (or fails to match if -v is used). If -f is                   until one matches (or fails to match if -v is used). If -f is
227                   used with -e, the command line patterns  are  matched  first,                   used  with  -e,  the command line patterns are matched first,
228                   followed  by  the  patterns from the file, independent of the                   followed by the patterns from the file,  independent  of  the
229                   order in which these options are specified. Note that  multi-                   order  in which these options are specified. Note that multi-
230                   ple use of -e is not the same as a single pattern with alter-                   ple use of -e is not the same as a single pattern with alter-
231                   natives. For example, X|Y finds the first character in a line                   natives. For example, X|Y finds the first character in a line
232                   that  is  X or Y, whereas if the two patterns are given sepa-                   that is X or Y, whereas if the two patterns are  given  sepa-
233                   rately, pcregrep finds X if it is present, even if it follows                   rately, pcregrep finds X if it is present, even if it follows
234                   Y  in the line. It finds Y only if there is no X in the line.                   Y in the line. It finds Y only if there is no X in the  line.
235                   This really matters only if you are  using  -o  to  show  the                   This  really  matters  only  if  you are using -o to show the
236                   part(s) of the line that matched.                   part(s) of the line that matched.
237    
238         --exclude=pattern         --exclude=pattern
239                   When pcregrep is searching the files in a directory as a con-                   When pcregrep is searching the files in a directory as a con-
240                   sequence of the -r (recursive  search)  option,  any  regular                   sequence  of  the  -r  (recursive search) option, any regular
241                   files whose names match the pattern are excluded. Subdirecto-                   files whose names match the pattern are excluded. Subdirecto-
242                   ries are not excluded  by  this  option;  they  are  searched                   ries  are  not  excluded  by  this  option; they are searched
243                   recursively,  subject  to the --exclude-dir and --include_dir                   recursively, subject to the --exclude-dir  and  --include_dir
244                   options. The pattern is a PCRE  regular  expression,  and  is                   options.  The  pattern  is  a PCRE regular expression, and is
245                   matched against the final component of the file name (not the                   matched against the final component of the file name (not the
246                   entire path). If a  file  name  matches  both  --include  and                   entire  path).  If  a  file  name  matches both --include and
247                   --exclude,  it  is excluded.  There is no short form for this                   --exclude, it is excluded.  There is no short form  for  this
248                   option.                   option.
249    
250         --exclude-dir=pattern         --exclude-dir=pattern
251                   When pcregrep is searching the contents of a directory  as  a                   When  pcregrep  is searching the contents of a directory as a
252                   consequence  of  the -r (recursive search) option, any subdi-                   consequence of the -r (recursive search) option,  any  subdi-
253                   rectories whose names match the pattern are  excluded.  (Note                   rectories  whose  names match the pattern are excluded. (Note
254                   that  the  --exclude  option does not affect subdirectories.)                   that the --exclude option does  not  affect  subdirectories.)
255                   The pattern is a PCRE  regular  expression,  and  is  matched                   The  pattern  is  a  PCRE  regular expression, and is matched
256                   against  the  final  component  of  the  name (not the entire                   against the final component  of  the  name  (not  the  entire
257                   path). If a subdirectory name matches both --include-dir  and                   path).  If a subdirectory name matches both --include-dir and
258                   --exclude-dir,  it  is  excluded.  There is no short form for                   --exclude-dir, it is excluded. There is  no  short  form  for
259                   this option.                   this option.
260    
261         -F, --fixed-strings         -F, --fixed-strings
262                   Interpret each pattern as a list of fixed strings,  separated                   Interpret  each pattern as a list of fixed strings, separated
263                   by  newlines,  instead  of  as  a  regular expression. The -w                   by newlines, instead of  as  a  regular  expression.  The  -w
264                   (match as a word) and -x (match whole line)  options  can  be                   (match  as  a  word) and -x (match whole line) options can be
265                   used with -F. They apply to each of the fixed strings. A line                   used with -F. They apply to each of the fixed strings. A line
266                   is selected if any of the fixed strings are found in it (sub-                   is selected if any of the fixed strings are found in it (sub-
267                   ject to -w or -x, if present).                   ject to -w or -x, if present).
268    
269         -f filename, --file=filename         -f filename, --file=filename
270                   Read  a  number  of patterns from the file, one per line, and                   Read a number of patterns from the file, one  per  line,  and
271                   match them against each line of input. A data line is  output                   match  them against each line of input. A data line is output
272                   if any of the patterns match it. The filename can be given as                   if any of the patterns match it. The filename can be given as
273                   "-" to refer to the standard input. When -f is used, patterns                   "-" to refer to the standard input. When -f is used, patterns
274                   specified  on  the command line using -e may also be present;                   specified on the command line using -e may also  be  present;
275                   they are tested before the file's patterns. However, no other                   they are tested before the file's patterns. However, no other
276                   pattern  is  taken  from  the command line; all arguments are                   pattern is taken from the command  line;  all  arguments  are
277                   treated as file names. There is an  overall  maximum  of  100                   treated  as  the  names  of paths to be searched. There is an
278                   patterns. Trailing white space is removed from each line, and                   overall maximum of 100  patterns.  Trailing  white  space  is
279                   blank lines are ignored. An empty file contains  no  patterns                   removed from each line, and blank lines are ignored. An empty
280                   and  therefore  matches  nothing. See also the comments about                   file contains no patterns and therefore matches nothing.  See
281                   multiple patterns versus a single pattern  with  alternatives                   also  the  comments  about  multiple patterns versus a single
282                   in the description of -e above.                   pattern with alternatives in the description of -e above.
283    
284           --file-list=filename
285                     Read a list of files to be searched from the given file,  one
286                     per line. Trailing white space is removed from each line, and
287                     blank lines are ignored. These files are searched before  any
288                     others  that  may be listed on the command line. The filename
289                     can be given as "-" to refer to the standard input. If --file
290                     and  --file-list are both specified as "-", patterns are read
291                     first. This is useful only when the standard input is a  ter-
292                     minal,  from  which  further lines (the list of files) can be
293                     read after an end-of-file indication.
294    
295         --file-offsets         --file-offsets
296                   Instead  of  showing lines or parts of lines that match, show                   Instead of showing lines or parts of lines that  match,  show
297                   each match as an offset from the start  of  the  file  and  a                   each  match  as  an  offset  from the start of the file and a
298                   length,  separated  by  a  comma. In this mode, no context is                   length, separated by a comma. In this  mode,  no  context  is
299                   shown. That is, the -A, -B, and -C options  are  ignored.  If                   shown.  That  is,  the -A, -B, and -C options are ignored. If
300                   there is more than one match in a line, each of them is shown                   there is more than one match in a line, each of them is shown
301                   separately. This option is mutually  exclusive  with  --line-                   separately.  This  option  is mutually exclusive with --line-
302                   offsets and --only-matching.                   offsets and --only-matching.
303    
304         -H, --with-filename         -H, --with-filename
305                   Force  the  inclusion  of the filename at the start of output                   Force the inclusion of the filename at the  start  of  output
306                   lines when searching a single file. By default, the  filename                   lines  when searching a single file. By default, the filename
307                   is  not  shown in this case. For matching lines, the filename                   is not shown in this case. For matching lines,  the  filename
308                   is followed by a colon; for context lines, a hyphen separator                   is followed by a colon; for context lines, a hyphen separator
309                   is  used.  If  a line number is also being output, it follows                   is used. If a line number is also being  output,  it  follows
310                   the file name.                   the file name.
311    
312         -h, --no-filename         -h, --no-filename
313                   Suppress the output filenames when searching multiple  files.                   Suppress  the output filenames when searching multiple files.
314                   By  default,  filenames  are  shown  when  multiple files are                   By default, filenames  are  shown  when  multiple  files  are
315                   searched. For matching lines, the filename is followed  by  a                   searched.  For  matching lines, the filename is followed by a
316                   colon;  for  context lines, a hyphen separator is used.  If a                   colon; for context lines, a hyphen separator is used.   If  a
317                   line number is also being output, it follows the file name.                   line number is also being output, it follows the file name.
318    
319         --help    Output a help message, giving brief details  of  the  command         --help    Output  a  help  message, giving brief details of the command
320                   options and file type support, and then exit.                   options and file type support, and then exit.
321    
322           -I        Treat binary files as never matching. This is  equivalent  to
323                     --binary-files=without-match.
324    
325         -i, --ignore-case         -i, --ignore-case
326                   Ignore upper/lower case distinctions during comparisons.                   Ignore upper/lower case distinctions during comparisons.
327    
# Line 540  NEWLINES Line 580  NEWLINES
580  OPTIONS COMPATIBILITY  OPTIONS COMPATIBILITY
581    
582         Many  of the short and long forms of pcregrep's options are the same as         Many  of the short and long forms of pcregrep's options are the same as
583         in the GNU grep program (version 2.5.4). Any long option  of  the  form         in the GNU grep program. Any long option of the form --xxx-regexp  (GNU
584         --xxx-regexp  (GNU  terminology) is also available as --xxx-regex (PCRE         terminology)  is also available as --xxx-regex (PCRE terminology). How-
585         terminology). However, the --file-offsets,  --include-dir,  --line-off-         ever, the --file-list, --file-offsets,  --include-dir,  --line-offsets,
586         sets, --locale, --match-limit, -M, --multiline, -N, --newline, --recur-         --locale,  --match-limit,  -M, --multiline, -N, --newline, --recursion-
587         sion-limit, -u, and --utf-8 options are specific to pcregrep, as is the         limit, -u, and --utf-8 options are specific to pcregrep, as is the  use
588         use of the --only-matching option with a capturing parentheses number.         of the --only-matching option with a capturing parentheses number.
589    
590         Although  most  of the common options work the same way, a few are dif-         Although  most  of the common options work the same way, a few are dif-
591         ferent in pcregrep. For example, the --include option's argument  is  a         ferent in pcregrep. For example, the --include option's argument  is  a
# Line 626  AUTHOR Line 666  AUTHOR
666    
667  REVISION  REVISION
668    
669         Last updated: 06 September 2011         Last updated: 04 March 2012
670         Copyright (c) 1997-2011 University of Cambridge.         Copyright (c) 1997-2012 University of Cambridge.

Legend:
Removed from v.953  
changed lines
  Added in v.954

  ViewVC Help
Powered by ViewVC 1.1.5