/[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 149 by ph10, Tue Mar 6 12:27:42 2007 UTC revision 150 by ph10, Tue Apr 17 08:22:40 2007 UTC
# Line 245  OPTIONS Line 245  OPTIONS
245                   lookbehind assertions.                   lookbehind assertions.
246    
247         -N newline-type, --newline=newline-type         -N newline-type, --newline=newline-type
248                   The  PCRE  library  supports  four  different conventions for                   The  PCRE  library  supports  five  different conventions for
249                   indicating the ends of lines. They are  the  single-character                   indicating the ends of lines. They are  the  single-character
250                   sequences  CR  (carriage  return) and LF (linefeed), the two-                   sequences  CR  (carriage  return) and LF (linefeed), the two-
251                   character sequence CRLF, and an "any"  convention,  in  which                   character sequence CRLF, an "anycrlf" convention, which  rec-
252                   any  Unicode  line  ending sequence is assumed to end a line.                   ognizes  any  of the preceding three types, and an "any" con-
253                   The Unicode sequences are the three just mentioned,  plus  VT                   vention, in which any Unicode line ending sequence is assumed
254                   (vertical  tab,  U+000B),  FF  (formfeed,  U+000C), NEL (next                   to  end a line. The Unicode sequences are the three just men-
255                   line, U+0085), LS (line separator, U+2028), and PS (paragraph                   tioned,  plus  VT  (vertical  tab,  U+000B),  FF   (formfeed,
256                   separator, U+0029).                   U+000C),   NEL  (next  line,  U+0085),  LS  (line  separator,
257                     U+2028), and PS (paragraph separator, U+2029).
258    
259                   When  the  PCRE  library  is  built,  a  default  line-ending                   When  the  PCRE  library  is  built,  a  default  line-ending
260                   sequence  is  specified.   This  is  normally  the   standard                   sequence   is  specified.   This  is  normally  the  standard
261                   sequence for the operating system. Unless otherwise specified                   sequence for the operating system. Unless otherwise specified
262                   by this option, pcregrep uses  the  library's  default.   The                   by  this  option,  pcregrep  uses the library's default.  The
263                   possible  values  for  this  option are CR, LF, CRLF, or ANY.                   possible values for this option are CR, LF, CRLF, ANYCRLF, or
264                   This makes it possible to use pcregrep  on  files  that  have                   ANY.  This  makes  it  possible to use pcregrep on files that
265                   come  from  other environments without having to modify their                   have come from other environments without  having  to  modify
266                   line endings. If the data that  is  being  scanned  does  not                   their  line  endings.  If the data that is being scanned does
267                   agree  with  the  convention set by this option, pcregrep may                   not agree with the convention set by  this  option,  pcregrep
268                   behave in strange ways.                   may behave in strange ways.
269    
270         -n, --line-number         -n, --line-number
271                   Precede each output line by its line number in the file, fol-                   Precede each output line by its line number in the file, fol-
272                   lowed  by  a colon and a space for matching lines or a hyphen                   lowed by a colon and a space for matching lines or  a  hyphen
273                   and a space for context lines. If the filename is also  being                   and  a space for context lines. If the filename is also being
274                   output, it precedes the line number.                   output, it precedes the line number.
275    
276         -o, --only-matching         -o, --only-matching
277                   Show  only  the  part  of the line that matched a pattern. In                   Show only the part of the line that  matched  a  pattern.  In
278                   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
279                   options are ignored.                   options are ignored.
280    
281         -q, --quiet         -q, --quiet
282                   Work quietly, that is, display nothing except error messages.                   Work quietly, that is, display nothing except error messages.
283                   The exit status indicates whether or  not  any  matches  were                   The  exit  status  indicates  whether or not any matches were
284                   found.                   found.
285    
286         -r, --recursive         -r, --recursive
287                   If  any given path is a directory, recursively scan the files                   If any given path is a directory, recursively scan the  files
288                   it contains, taking note of any --include and --exclude  set-                   it  contains, taking note of any --include and --exclude set-
289                   tings.  By  default, a directory is read as a normal file; in                   tings. By default, a directory is read as a normal  file;  in
290                   some operating systems this gives an  immediate  end-of-file.                   some  operating  systems this gives an immediate end-of-file.
291                   This  option  is  a  shorthand  for  setting the -d option to                   This option is a shorthand  for  setting  the  -d  option  to
292                   "recurse".                   "recurse".
293    
294         -s, --no-messages         -s, --no-messages
295                   Suppress error  messages  about  non-existent  or  unreadable                   Suppress  error  messages  about  non-existent  or unreadable
296                   files.  Such  files  are quietly skipped. However, the return                   files. Such files are quietly skipped.  However,  the  return
297                   code is still 2, even if matches were found in other files.                   code is still 2, even if matches were found in other files.
298    
299         -u, --utf-8         -u, --utf-8
300                   Operate in UTF-8 mode. This option is available only if  PCRE                   Operate  in UTF-8 mode. This option is available only if PCRE
301                   has  been compiled with UTF-8 support. Both patterns and sub-                   has been compiled with UTF-8 support. Both patterns and  sub-
302                   ject lines must be valid strings of UTF-8 characters.                   ject lines must be valid strings of UTF-8 characters.
303    
304         -V, --version         -V, --version
305                   Write the version numbers of pcregrep and  the  PCRE  library                   Write  the  version  numbers of pcregrep and the PCRE library
306                   that is being used to the standard error stream.                   that is being used to the standard error stream.
307    
308         -v, --invert-match         -v, --invert-match
309                   Invert  the  sense  of  the match, so that lines which do not                   Invert the sense of the match, so that  lines  which  do  not
310                   match any of the patterns are the ones that are found.                   match any of the patterns are the ones that are found.
311    
312         -w, --word-regex, --word-regexp         -w, --word-regex, --word-regexp
# Line 313  OPTIONS Line 314  OPTIONS
314                   lent to having \b at the start and end of the pattern.                   lent to having \b at the start and end of the pattern.
315    
316         -x, --line-regex, --line-regexp         -x, --line-regex, --line-regexp
317                   Force  the  patterns to be anchored (each must start matching                   Force the patterns to be anchored (each must  start  matching
318                   at the beginning of a line) and in addition, require them  to                   at  the beginning of a line) and in addition, require them to
319                   match  entire  lines.  This  is  equivalent to having ^ and $                   match entire lines. This is equivalent  to  having  ^  and  $
320                   characters at the start and end of each alternative branch in                   characters at the start and end of each alternative branch in
321                   every pattern.                   every pattern.
322    
323    
324  ENVIRONMENT VARIABLES  ENVIRONMENT VARIABLES
325    
326         The  environment  variables  LC_ALL  and LC_CTYPE are examined, in that         The environment variables LC_ALL and LC_CTYPE  are  examined,  in  that
327         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
328         overridden  by  the  --locale  option.  If  no  locale is set, the PCRE         overridden by the --locale option.  If  no  locale  is  set,  the  PCRE
329         library's default (usually the "C" locale) is used.         library's default (usually the "C" locale) is used.
330    
331    
332  NEWLINES  NEWLINES
333    
334         The -N (--newline) option allows pcregrep to scan files with  different         The  -N (--newline) option allows pcregrep to scan files with different
335         newline  conventions  from  the  default.  However, the setting of this         newline conventions from the default.  However,  the  setting  of  this
336         option does not affect the way in which pcregrep writes information  to         option  does not affect the way in which pcregrep writes information to
337         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
338         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
339         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
340         file.         file.
341    
342    
343  OPTIONS COMPATIBILITY  OPTIONS COMPATIBILITY
344    
345         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
346         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
347         (GNU terminology) is also available as --xxx-regex (PCRE  terminology).         (GNU  terminology) is also available as --xxx-regex (PCRE terminology).
348         However,  the  --locale,  -M,  --multiline, -u, and --utf-8 options are         However, the --locale, -M, --multiline, -u,  and  --utf-8  options  are
349         specific to pcregrep.         specific to pcregrep.
350    
351    
352  OPTIONS WITH DATA  OPTIONS WITH DATA
353    
354         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-
355         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-
356         ately, or in the next command line item. For example:         ately, or in the next command line item. For example:
357    
358           -f/some/file           -f/some/file
359           -f /some/file           -f /some/file
360    
361         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
362         line item, separated by an equals character, or (with one exception) it         line item, separated by an equals character, or (with one exception) it
363         may appear in the next command line item. For example:         may appear in the next command line item. For example:
364    
365           --file=/some/file           --file=/some/file
366           --file /some/file           --file /some/file
367    
368         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 ~
369         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
370         directory, you must separate the file name from the option, because the         directory, you must separate the file name from the option, because the
371         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.
372    
373         The exception to the above is the --colour  (or  --color)  option,  for         The  exception  to  the  above is the --colour (or --color) option, for
374         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
375         given in the first form, using an equals character. Otherwise  it  will         given  in  the first form, using an equals character. Otherwise it will
376         be assumed that it has no data.         be assumed that it has no data.
377    
378    
379  MATCHING ERRORS  MATCHING ERRORS
380    
381         It  is  possible  to supply a regular expression that takes a very long         It is possible to supply a regular expression that takes  a  very  long
382         time to fail to match certain lines.  Such  patterns  normally  involve         time  to  fail  to  match certain lines. Such patterns normally involve
383         nested  indefinite repeats, for example: (a+)*\d when matched against a         nested indefinite repeats, for example: (a+)*\d when matched against  a
384         line of a's with no final digit.  The  PCRE  matching  function  has  a         line  of  a's  with  no  final  digit. The PCRE matching function has a
385         resource  limit that causes it to abort in these circumstances. If this         resource limit that causes it to abort in these circumstances. If  this
386         happens, pcregrep outputs an error message and the line that caused the         happens, pcregrep outputs an error message and the line that caused the
387         problem  to  the  standard error stream. If there are more than 20 such         problem to the standard error stream. If there are more  than  20  such
388         errors, pcregrep gives up.         errors, pcregrep gives up.
389    
390    
391  DIAGNOSTICS  DIAGNOSTICS
392    
393         Exit status is 0 if any matches were found, 1 if no matches were found,         Exit status is 0 if any matches were found, 1 if no matches were found,
394         and  2 for syntax errors and non-existent or inacessible files (even if         and 2 for syntax errors and non-existent or inacessible files (even  if
395         matches were found in other files) or too many matching  errors.  Using         matches  were  found in other files) or too many matching errors. Using
396         the  -s  option to suppress error messages about inaccessble files does         the -s option to suppress error messages about inaccessble  files  does
397         not affect the return code.         not affect the return code.
398    
399    
# Line 410  AUTHOR Line 411  AUTHOR
411    
412  REVISION  REVISION
413    
414         Last updated: 06 March 2007         Last updated: 16 April 2007
415         Copyright (c) 1997-2007 University of Cambridge.         Copyright (c) 1997-2007 University of Cambridge.

Legend:
Removed from v.149  
changed lines
  Added in v.150

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12