/[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 391 by ph10, Mon Apr 28 15:10:02 2008 UTC revision 392 by ph10, Tue Mar 17 21:30:30 2009 UTC
# Line 53  DESCRIPTION Line 53  DESCRIPTION
53         greater.  BUFSIZ is defined in <stdio.h>. When there is more  than  one         greater.  BUFSIZ is defined in <stdio.h>. When there is more  than  one
54         pattern (specified by the use of -e and/or -f), each pattern is applied         pattern (specified by the use of -e and/or -f), each pattern is applied
55         to each line in the order in which they are defined,  except  that  all         to each line in the order in which they are defined,  except  that  all
56         the  -e  patterns are tried before the -f patterns. As soon as one pat-         the -e patterns are tried before the -f patterns.
57         tern matches (or fails to match when -v is used), no  further  patterns  
58         are considered.         By  default,  as soon as one pattern matches (or fails to match when -v
59           is used), no further patterns are considered. However, if --colour  (or
60         When  --only-matching,  --file-offsets,  or --line-offsets is used, the         --color) is used to colour the matching substrings, or if --only-match-
61         output is the part of the line that matched (either shown literally, or         ing, --file-offsets, or --line-offsets is used to output only the  part
62         as an offset). In this case, scanning resumes immediately following the         of  the  line  that  matched (either shown literally, or as an offset),
63         match, so that further matches on the same line can be found.  If there         scanning resumes immediately  following  the  match,  so  that  further
64         are multiple patterns, they are all tried on the remainder of the line.         matches  on the same line can be found. If there are multiple patterns,
65         However, patterns that follow the one that matched are not tried on the         they are all tried on the remainder of the line, but patterns that fol-
66         earlier part of the line.         low the one that matched are not tried on the earlier part of the line.
67    
68           This is the same behaviour as GNU grep, but it does mean that the order
69           in which multiple patterns are specified can affect the output when one
70           of the above options is used.
71    
72           Patterns  that can match an empty string are accepted, but empty string
73           matches are not recognized. An example is the pattern "(super)?(man)?",
74           in  which  all  components  are optional. This pattern finds all occur-
75           rences of both "super" and "man"; the output differs from matching with
76           "super|man" when only the matching substrings are being shown.
77    
78         If  the  LC_ALL  or LC_CTYPE environment variable is set, pcregrep uses         If  the  LC_ALL  or LC_CTYPE environment variable is set, pcregrep uses
79         the value to set a locale when calling the PCRE library.  The  --locale         the value to set a locale when calling the PCRE library.  The  --locale
# Line 124  OPTIONS Line 134  OPTIONS
134                   the same shell item, separated by an equals sign.                   the same shell item, separated by an equals sign.
135    
136         --colour=value, --color=value         --colour=value, --color=value
137                   This option specifies under what circumstances the part of  a                   This option specifies under what circumstances the parts of a
138                   line that matched a pattern should be coloured in the output.                   line that matched a pattern should be coloured in the output.
139                   The value may be "never" (the default), "always", or  "auto".                   By default, the output is not coloured. The value  (which  is
140                   In  the  latter  case, colouring happens only if the standard                   optional,  see above) may be "never", "always", or "auto". In
141                   output is connected to a terminal. The colour can  be  speci-                   the latter case, colouring happens only if the standard  out-
142                   fied  by  setting the environment variable PCREGREP_COLOUR or                   put  is connected to a terminal. More resources are used when
143                   PCREGREP_COLOR. The value of this variable should be a string                   colouring is enabled, because pcregrep has to search for  all
144                   of  two  numbers,  separated by a semicolon.  They are copied                   possible  matches in a line, not just one, in order to colour
145                   directly into the control string for setting colour on a ter-                   them all.
146                   minal,  so it is your responsibility to ensure that they make  
147                   sense. If neither of the environment variables  is  set,  the                   The colour that is used can be specified by setting the envi-
148                   default is "1;31", which gives red.                   ronment variable PCREGREP_COLOUR or PCREGREP_COLOR. The value
149                     of this variable should be a string of two numbers, separated
150                     by  a  semicolon.  They  are copied directly into the control
151                     string for setting colour  on  a  terminal,  so  it  is  your
152                     responsibility  to ensure that they make sense. If neither of
153                     the environment variables is  set,  the  default  is  "1;31",
154                     which gives red.
155    
156         -D action, --devices=action         -D action, --devices=action
157                   If  an  input  path  is  not  a  regular file or a directory,                   If  an  input  path  is  not  a  regular file or a directory,
158                   "action" specifies how it is to be  processed.  Valid  values                   "action" specifies how it is to be  processed.  Valid  values
159                   are  "read" (the default) or "skip" (silently skip the path).                   are "read" (the default) or "skip" (silently skip the path).
160    
161         -d action, --directories=action         -d action, --directories=action
162                   If an input path is a directory, "action" specifies how it is                   If an input path is a directory, "action" specifies how it is
163                   to  be  processed.   Valid  values  are "read" (the default),                   to be processed.  Valid  values  are  "read"  (the  default),
164                   "recurse" (equivalent to the -r option), or "skip"  (silently                   "recurse"  (equivalent to the -r option), or "skip" (silently
165                   skip  the path). In the default case, directories are read as                   skip the path). In the default case, directories are read  as
166                   if they were ordinary files. In some  operating  systems  the                   if  they  were  ordinary files. In some operating systems the
167                   effect  of reading a directory like this is an immediate end-                   effect of reading a directory like this is an immediate  end-
168                   of-file.                   of-file.
169    
170         -e pattern, --regex=pattern, --regexp=pattern         -e pattern, --regex=pattern, --regexp=pattern
171                   Specify a pattern to be matched. This option can be used mul-                   Specify a pattern to be matched. This option can be used mul-
172                   tiple times in order to specify several patterns. It can also                   tiple times in order to specify several patterns. It can also
173                   be used as a way of specifying a single pattern  that  starts                   be  used  as a way of specifying a single pattern that starts
174                   with  a hyphen. When -e is used, no argument pattern is taken                   with a hyphen. When -e is used, no argument pattern is  taken
175                   from the command line; all  arguments  are  treated  as  file                   from  the  command  line;  all  arguments are treated as file
176                   names.  There is an overall maximum of 100 patterns. They are                   names. There is an overall maximum of 100 patterns. They  are
177                   applied to each line in the order in which they  are  defined                   applied  to  each line in the order in which they are defined
178                   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
179                   used with -e, the command line patterns  are  matched  first,                   used  with  -e,  the command line patterns are matched first,
180                   followed  by  the  patterns from the file, independent of the                   followed by the patterns from the file,  independent  of  the
181                   order in which these options are specified. Note that  multi-                   order  in which these options are specified. Note that multi-
182                   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-
183                   natives. For example, X|Y finds the first character in a line                   natives. For example, X|Y finds the first character in a line
184                   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-
185                   rately, pcregrep finds X if it is present, even if it follows                   rately, pcregrep finds X if it is present, even if it follows
186                   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.
187                   This really matters only if you are  using  -o  to  show  the                   This  really  matters  only  if  you are using -o to show the
188                   part(s) of the line that matched.                   part(s) of the line that matched.
189    
190         --exclude=pattern         --exclude=pattern
191                   When pcregrep is searching the files in a directory as a con-                   When pcregrep is searching the files in a directory as a con-
192                   sequence of the -r (recursive  search)  option,  any  regular                   sequence  of  the  -r  (recursive search) option, any regular
193                   files whose names match the pattern are excluded. Subdirecto-                   files whose names match the pattern are excluded. Subdirecto-
194                   ries are not excluded  by  this  option;  they  are  searched                   ries  are  not  excluded  by  this  option; they are searched
195                   recursively,  subject  to the --exclude_dir and --include_dir                   recursively, subject to the --exclude_dir  and  --include_dir
196                   options. The pattern is a PCRE  regular  expression,  and  is                   options.  The  pattern  is  a PCRE regular expression, and is
197                   matched against the final component of the file name (not the                   matched against the final component of the file name (not the
198                   entire path). If a  file  name  matches  both  --include  and                   entire  path).  If  a  file  name  matches both --include and
199                   --exclude,  it  is excluded.  There is no short form for this                   --exclude, it is excluded.  There is no short form  for  this
200                   option.                   option.
201    
202         --exclude_dir=pattern         --exclude_dir=pattern
203                   When pcregrep is searching the contents of a directory  as  a                   When  pcregrep  is searching the contents of a directory as a
204                   consequence  of  the -r (recursive search) option, any subdi-                   consequence of the -r (recursive search) option,  any  subdi-
205                   rectories whose names match the pattern are  excluded.  (Note                   rectories  whose  names match the pattern are excluded. (Note
206                   that  the  --exclude  option does not affect subdirectories.)                   that the --exclude option does  not  affect  subdirectories.)
207                   The pattern is a PCRE  regular  expression,  and  is  matched                   The  pattern  is  a  PCRE  regular expression, and is matched
208                   against  the  final  component  of  the  name (not the entire                   against the final component  of  the  name  (not  the  entire
209                   path). If a subdirectory name matches both --include_dir  and                   path).  If a subdirectory name matches both --include_dir and
210                   --exclude_dir,  it  is  excluded.  There is no short form for                   --exclude_dir, it is excluded. There is  no  short  form  for
211                   this option.                   this option.
212    
213         -F, --fixed-strings         -F, --fixed-strings
214                   Interpret each pattern as a list of fixed strings,  separated                   Interpret  each pattern as a list of fixed strings, separated
215                   by  newlines,  instead  of  as  a  regular expression. The -w                   by newlines, instead of  as  a  regular  expression.  The  -w
216                   (match as a word) and -x (match whole line)  options  can  be                   (match  as  a  word) and -x (match whole line) options can be
217                   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
218                   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-
219                   ject to -w or -x, if present).                   ject to -w or -x, if present).
220    
221         -f filename, --file=filename         -f filename, --file=filename
222                   Read  a  number  of patterns from the file, one per line, and                   Read a number of patterns from the file, one  per  line,  and
223                   match them against each line of input. A data line is  output                   match  them against each line of input. A data line is output
224                   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
225                   "-" to refer to the standard input. When -f is used, patterns                   "-" to refer to the standard input. When -f is used, patterns
226                   specified  on  the command line using -e may also be present;                   specified on the command line using -e may also  be  present;
227                   they are tested before the file's patterns. However, no other                   they are tested before the file's patterns. However, no other
228                   pattern  is  taken  from  the command line; all arguments are                   pattern is taken from the command  line;  all  arguments  are
229                   treated as file names. There is an  overall  maximum  of  100                   treated  as  file  names.  There is an overall maximum of 100
230                   patterns. Trailing white space is removed from each line, and                   patterns. Trailing white space is removed from each line, and
231                   blank lines are ignored. An empty file contains  no  patterns                   blank  lines  are ignored. An empty file contains no patterns
232                   and  therefore  matches  nothing. See also the comments about                   and therefore matches nothing. See also  the  comments  about
233                   multiple patterns versus a single pattern  with  alternatives                   multiple  patterns  versus a single pattern with alternatives
234                   in the description of -e above.                   in the description of -e above.
235    
236         --file-offsets         --file-offsets
237                   Instead  of  showing lines or parts of lines that match, show                   Instead of showing lines or parts of lines that  match,  show
238                   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
239                   length,  separated  by  a  comma. In this mode, no context is                   length, separated by a comma. In this  mode,  no  context  is
240                   shown. That is, the -A, -B, and -C options  are  ignored.  If                   shown.  That  is,  the -A, -B, and -C options are ignored. If
241                   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
242                   separately. This option is mutually  exclusive  with  --line-                   separately.  This  option  is mutually exclusive with --line-
243                   offsets and --only-matching.                   offsets and --only-matching.
244    
245         -H, --with-filename         -H, --with-filename
246                   Force  the  inclusion  of the filename at the start of output                   Force the inclusion of the filename at the  start  of  output
247                   lines when searching a single file. By default, the  filename                   lines  when searching a single file. By default, the filename
248                   is  not  shown in this case. For matching lines, the filename                   is not shown in this case. For matching lines,  the  filename
249                   is followed by a colon and a  space;  for  context  lines,  a                   is followed by a colon; for context lines, a hyphen separator
250                   hyphen separator is used. If a line number is also being out-                   is used. If a line number is also being  output,  it  follows
251                   put, it follows the file name without a space.                   the file name.
252    
253         -h, --no-filename         -h, --no-filename
254                   Suppress the output filenames when searching multiple  files.                   Suppress  the output filenames when searching multiple files.
255                   By  default,  filenames  are  shown  when  multiple files are                   By default, filenames  are  shown  when  multiple  files  are
256                   searched. For matching lines, the filename is followed  by  a                   searched.  For  matching lines, the filename is followed by a
257                   colon  and  a space; for context lines, a hyphen separator is                   colon; for context lines, a hyphen separator is used.   If  a
258                   used. If a line number is also being output, it  follows  the                   line number is also being output, it follows the file name.
                  file name without a space.  
259    
260         --help    Output  a  help  message, giving brief details of the command         --help    Output  a  help  message, giving brief details of the command
261                   options and file type support, and then exit.                   options and file type support, and then exit.
# Line 346  OPTIONS Line 361  OPTIONS
361    
362         -n, --line-number         -n, --line-number
363                   Precede each output line by its line number in the file, fol-                   Precede each output line by its line number in the file, fol-
364                   lowed by a colon and a space for matching lines or  a  hyphen                   lowed by a colon for matching lines or a hyphen  for  context
365                   and  a space for context lines. If the filename is also being                   lines.  If the filename is also being output, it precedes the
366                   output, it precedes the line number. This option is forced if                   line number. This option is forced if --line-offsets is used.
                  --line-offsets is used.  
367    
368         -o, --only-matching         -o, --only-matching
369                   Show  only  the  part  of the line that matched a pattern. In                   Show only the part of the line that  matched  a  pattern.  In
370                   this mode, no context is shown. That is, the -A, -B,  and  -C                   this  mode,  no context is shown. That is, the -A, -B, and -C
371                   options  are  ignored.  If  there is more than one match in a                   options are ignored. If there is more than  one  match  in  a
372                   line, each of them is shown separately.  If  -o  is  combined                   line,  each  of  them  is shown separately. If -o is combined
373                   with  -v  (invert the sense of the match to find non-matching                   with -v (invert the sense of the match to  find  non-matching
374                   lines), no output is generated, but the return  code  is  set                   lines),  no  output  is generated, but the return code is set
375                   appropriately. This option is mutually exclusive with --file-                   appropriately. This option is mutually exclusive with --file-
376                   offsets and --line-offsets.                   offsets and --line-offsets.
377    
378         -q, --quiet         -q, --quiet
379                   Work quietly, that is, display nothing except error messages.                   Work quietly, that is, display nothing except error messages.
380                   The  exit  status  indicates  whether or not any matches were                   The exit status indicates whether or  not  any  matches  were
381                   found.                   found.
382    
383         -r, --recursive         -r, --recursive
384                   If any given path is a directory, recursively scan the  files                   If  any given path is a directory, recursively scan the files
385                   it  contains, taking note of any --include and --exclude set-                   it contains, taking note of any --include and --exclude  set-
386                   tings. By default, a directory is read as a normal  file;  in                   tings.  By  default, a directory is read as a normal file; in
387                   some  operating  systems this gives an immediate end-of-file.                   some operating systems this gives an  immediate  end-of-file.
388                   This option is a shorthand  for  setting  the  -d  option  to                   This  option  is  a  shorthand  for  setting the -d option to
389                   "recurse".                   "recurse".
390    
391         -s, --no-messages         -s, --no-messages
392                   Suppress  error  messages  about  non-existent  or unreadable                   Suppress error  messages  about  non-existent  or  unreadable
393                   files. Such files are quietly skipped.  However,  the  return                   files.  Such  files  are quietly skipped. However, the return
394                   code is still 2, even if matches were found in other files.                   code is still 2, even if matches were found in other files.
395    
396         -u, --utf-8         -u, --utf-8
397                   Operate  in UTF-8 mode. This option is available only if PCRE                   Operate in UTF-8 mode. This option is available only if  PCRE
398                   has been compiled with UTF-8 support. Both patterns and  sub-                   has  been compiled with UTF-8 support. Both patterns and sub-
399                   ject lines must be valid strings of UTF-8 characters.                   ject lines must be valid strings of UTF-8 characters.
400    
401         -V, --version         -V, --version
402                   Write  the  version  numbers of pcregrep and the PCRE library                   Write the version numbers of pcregrep and  the  PCRE  library
403                   that is being used to the standard error stream.                   that is being used to the standard error stream.
404    
405         -v, --invert-match         -v, --invert-match
406                   Invert the sense of the match, so that  lines  which  do  not                   Invert  the  sense  of  the match, so that lines which do not
407                   match any of the patterns are the ones that are found.                   match any of the patterns are the ones that are found.
408    
409         -w, --word-regex, --word-regexp         -w, --word-regex, --word-regexp
# Line 397  OPTIONS Line 411  OPTIONS
411                   lent to having \b at the start and end of the pattern.                   lent to having \b at the start and end of the pattern.
412    
413         -x, --line-regex, --line-regexp         -x, --line-regex, --line-regexp
414                   Force the patterns to be anchored (each must  start  matching                   Force  the  patterns to be anchored (each must start matching
415                   at  the beginning of a line) and in addition, require them to                   at the beginning of a line) and in addition, require them  to
416                   match entire lines. This is equivalent  to  having  ^  and  $                   match  entire  lines.  This  is  equivalent to having ^ and $
417                   characters at the start and end of each alternative branch in                   characters at the start and end of each alternative branch in
418                   every pattern.                   every pattern.
419    
420    
421  ENVIRONMENT VARIABLES  ENVIRONMENT VARIABLES
422    
423         The environment variables LC_ALL and LC_CTYPE  are  examined,  in  that         The  environment  variables  LC_ALL  and LC_CTYPE are examined, in that
424         order,  for  a  locale.  The first one that is set is used. This can be         order, for a locale. The first one that is set is  used.  This  can  be
425         overridden by the --locale option.  If  no  locale  is  set,  the  PCRE         overridden  by  the  --locale  option.  If  no  locale is set, the PCRE
426         library's default (usually the "C" locale) is used.         library's default (usually the "C" locale) is used.
427    
428    
429  NEWLINES  NEWLINES
430    
431         The  -N (--newline) option allows pcregrep to scan files with different         The -N (--newline) option allows pcregrep to scan files with  different
432         newline conventions from the default.  However,  the  setting  of  this         newline  conventions  from  the  default.  However, the setting of this
433         option  does not affect the way in which pcregrep writes information to         option does not affect the way in which pcregrep writes information  to
434         the standard error and output streams. It uses the  string  "\n"  in  C         the  standard  error  and  output streams. It uses the string "\n" in C
435         printf()  calls  to  indicate newlines, relying on the C I/O library to         printf() calls to indicate newlines, relying on the C  I/O  library  to
436         convert this to an appropriate sequence if the  output  is  sent  to  a         convert  this  to  an  appropriate  sequence if the output is sent to a
437         file.         file.
438    
439    
440  OPTIONS COMPATIBILITY  OPTIONS COMPATIBILITY
441    
442         The majority of short and long forms of pcregrep's options are the same         The majority of short and long forms of pcregrep's options are the same
443         as in the GNU grep program. Any long option of  the  form  --xxx-regexp         as  in  the  GNU grep program. Any long option of the form --xxx-regexp
444         (GNU  terminology) is also available as --xxx-regex (PCRE terminology).         (GNU terminology) is also available as --xxx-regex (PCRE  terminology).
445         However, the --locale, -M, --multiline, -u,  and  --utf-8  options  are         However,  the  --locale,  -M,  --multiline, -u, and --utf-8 options are
446         specific to pcregrep.         specific to pcregrep.
447    
448    
449  OPTIONS WITH DATA  OPTIONS WITH DATA
450    
451         There are four different ways in which an option with data can be spec-         There are four different ways in which an option with data can be spec-
452         ified.  If a short form option is used, the  data  may  follow  immedi-         ified.   If  a  short  form option is used, the data may follow immedi-
453         ately, or in the next command line item. For example:         ately, or in the next command line item. For example:
454    
455           -f/some/file           -f/some/file
456           -f /some/file           -f /some/file
457    
458         If  a long form option is used, the data may appear in the same command         If a long form option is used, the data may appear in the same  command
459         line item, separated by an equals character, or (with one exception) it         line item, separated by an equals character, or (with one exception) it
460         may appear in the next command line item. For example:         may appear in the next command line item. For example:
461    
462           --file=/some/file           --file=/some/file
463           --file /some/file           --file /some/file
464    
465         Note,  however, that if you want to supply a file name beginning with ~         Note, however, that if you want to supply a file name beginning with  ~
466         as data in a shell command, and have the  shell  expand  ~  to  a  home         as  data  in  a  shell  command,  and have the shell expand ~ to a home
467         directory, you must separate the file name from the option, because the         directory, you must separate the file name from the option, because the
468         shell does not treat ~ specially unless it is at the start of an  item.         shell does not treat ~ specially unless it is at the start of an item.
469    
470         The  exception  to  the  above is the --colour (or --color) option, for         The  exception  to  the  above is the --colour (or --color) option, for
471         which the data is optional. If this option does have data, it  must  be         which the data is optional. If this option does have data, it  must  be
# Line 494  AUTHOR Line 508  AUTHOR
508    
509  REVISION  REVISION
510    
511         Last updated: 08 March 2008         Last updated: 01 March 2009
512         Copyright (c) 1997-2008 University of Cambridge.         Copyright (c) 1997-2009 University of Cambridge.

Legend:
Removed from v.391  
changed lines
  Added in v.392

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12