home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / utlos2.zip / Doc / grep.doc < prev    next >
Text File  |  1998-02-07  |  11KB  |  278 lines
  1. $Id: grep.doc 1.8 1998/02/08 02:01:06 brian Exp $
  2.  
  3.                      grep.doc : The 'grep' command
  4.                            By: Brian E. Yoder
  5.  
  6.         (c) Copyright International Business Machines Corporation 1998
  7.         All rights reserved.
  8.  
  9. The grep (get regular expression and print) command is an adaptation of
  10. the Unix grep command. It searches one or more files for a pattern.
  11.  
  12. ========================================================================
  13. Usage
  14. ========================================================================
  15.  
  16.         grep [ -flags ] [ -- ] "pattern" [ fspec ... ]
  17.  
  18. The grep command searches for the specified pattern. It writes each line
  19. that contains the pattern to standard output. The pattern is a regular
  20. expression as described later in this document.
  21.  
  22. One or more file specifications may be present on the command line. If
  23. no file specifications are present, then grep reads lines from standard
  24. input.
  25.  
  26. A file specification consists of an optional drive, optional path
  27. information, and a filename. The filename may consist of AIX shell
  28. pattern-matching characters. See pattern.doc for more details.
  29.  
  30. Binary files (such as *.obj and *.exe) can be searched in addition to
  31. text files.
  32.  
  33. The flags that are supported are a subset of those supported by the
  34. standard Unix or GNU grep:
  35.  
  36.     -c  Display only a count of matching lines.
  37.  
  38.     -i  Ignore case when making comparisons (same as -y).
  39.  
  40.     -l  List just the names of files (once) with matching lines. Each
  41.         file name is separated by a new-line character.
  42.  
  43.     -n  Preceed each line with the file name and line number, in the
  44.         following default form:  fname(line)
  45.  
  46.     -0 through -9
  47.         If -n is also specified, then a specifying a digit will select a
  48.         pattern to use when showing the file name, line number, and
  49.         starting column. If no digit is specified, then 0 is assumed.
  50.  
  51.     -s  Descend subdirectories, also.
  52.  
  53.     -v  Display lines that don't contain the pattern.
  54.  
  55.     -y  Ignore case when making comparisons (compatible with RS/6000).
  56.  
  57. ========================================================================
  58. Showing the filename, line number, and column number
  59. ========================================================================
  60.  
  61. If the -n flag is specified, then a format pattern number may also be
  62. specified. If no pattern number is specified, then -0 is used as the
  63. default.
  64.  
  65. The grep program looks in the GREPn environment variable, where n is the
  66. pattern number. If there is no GREPn variable in the environment (for
  67. instance, if -n5 is specified but there is no GREP5 environment variable
  68. defined), then the "$n($l) : " pattern is assumed.
  69.  
  70. The characters from the formatting pattern defined by the environment
  71. variable are copied to the output and then the text from the line is
  72. added. If a dollar sign '$' meta character is encountered, then it and
  73. the next character are interpreted as follows:
  74.  
  75.         $n specifies the name of the file.
  76.         $l (letter el) specifies the line number within the file.
  77.         $c specifies the starting column within the line.
  78.         $$ specifies the dollar sign itself.
  79.         $" specifies a double quote character.
  80.  
  81. With the exception of $", double quotes within or surrounding a format
  82. pattern are ignored.
  83.  
  84. If no format pattern is found, the "$n($l) : " pattern is assumed. This
  85. causes the following information to be shown:
  86.  
  87.         filename(line_number) : text from line
  88.  
  89. Some useful format patterns that may be specified are:
  90.  
  91.         set GREP0="$n($l) : "
  92.         set GREP1="$n($l:$c) : "
  93.         set GREP2="$n:$l:"
  94.         set GREP3="$n/$l/$c "
  95.         set GREP4="$n,$l,$c "
  96.  
  97. When specified with the -n flag, they are used as follows:
  98.  
  99.         -n0 is the default that this package's grep has shown from the
  100.         beginning. It mimics the format of error messages from many PC
  101.         compilers:
  102.  
  103.                 filename(linenumber) : text from line
  104.  
  105.         The GREP0 environment variable can be changed to another pattern
  106.         so that -n by itself uses that pattern instead.
  107.  
  108.         -n1 mimics the format of error messages from some modern C/C++
  109.         compilers that also include the column number:
  110.  
  111.                 filename(line:column) : text from line
  112.  
  113.         -n2 is the Unix and GNU grep's style:
  114.  
  115.                 filename:linenumber:text from line
  116.  
  117.         -n3 and -n4 mimic the format that the UltraEdit32 editor uses to
  118.         allow you to select a filename, open it, and put the cursor at
  119.         the specified line and column within the file. UltraEdit is a
  120.         very capable shareware editor available from the www.idmcomp.com
  121.         Web site. It's a spectacular bargain with a shareware price of
  122.         only U.S. $30 but with capabilities, ease-of-use, and company
  123.         responsiveness far beyond that of most other editors at any
  124.         price.
  125.  
  126. ========================================================================
  127. Notes
  128. ========================================================================
  129.  
  130. Lines are limited to a length of 512 characters. Longer lines are split
  131. in pieces of 512 characters or less.
  132.  
  133. A dot within a filename is treated as just another character and not
  134. assumed to be the beginning of a file extension. Therefore, you should
  135. specify * instead of *.* when searching all files in a specific
  136. directory. Again, see pattern.doc or the AIX shell documentation for
  137. more information.
  138.  
  139. Errors are listed on standard error.
  140.  
  141. Lines from the input file are written to standard output as follows:
  142.  
  143.         filename : text from line
  144.  
  145. If the -n flag is specified, then lines from the input file are written
  146. according to the pattern number specified. The default is as follows:
  147.  
  148.         filename(line_number) : text from line
  149.  
  150. ========================================================================
  151. Regular Expressions
  152. ========================================================================
  153.  
  154. The following expressions match a single character:
  155.  
  156.         c          Any ordinary character, other than one of the special
  157.                    pattern-matching characters, matches itself.
  158.  
  159.         .          A . (period) matches any single character.
  160.  
  161.         [string]   A string enclosed in square brackets matches any one
  162.                    character in the string.
  163.  
  164.         [.-.]      A range is two characters separated by a dash and
  165.                    enclosed in square brackets. It matches any
  166.                    character that is within the range.
  167.  
  168.         [^string]  A string (or range) enclosed in square brackets and
  169.                    preceeded by a ^ (circumflex) matches any character
  170.                    except for the characters in the string (or range).
  171.  
  172.                    Strings and ranges may be combined as needed, as in:
  173.                    [a-m0-9xyz], which matches a thru m, 0 thru 9, x, y,
  174.                    or z.
  175.  
  176.         \c         The \ (backslash) followed by any character matches
  177.                    that character. This is useful for matching the
  178.                    following special characters:  . * [ ] { } ^ $ \
  179.  
  180. The single-character expressions can be combined into regular
  181. expressions as follows:
  182.  
  183.         *          Match zero or more occurences of the previous
  184.                    character.
  185.  
  186.         {m}        Matches exactly m occurrences of the previous
  187.                    character.
  188.  
  189.         {m,}       Matches at least m occurrences of the previous
  190.                    character.
  191.  
  192.         {m,n}      Matches at least m but no more than n occurrences of
  193.                    the previous character.
  194.  
  195.                    m and n must be integers from 0 to 255, inclusive.
  196.  
  197. A regular expression can be restricted to match a string that begins on
  198. the first character of the line, ends on the last character of the line,
  199. or both, as follows:
  200.  
  201.         ^pattern   The pattern matches a string that begins on the first
  202.                    character of a line.
  203.  
  204.         pattern$   The pattern matches a string that ends on the last
  205.                    character of a line.
  206.  
  207.         ^pattern$  The pattern matches an entire line.
  208.  
  209.  
  210. ========================================================================
  211. Examples
  212. ========================================================================
  213.  
  214. grep "the cat" *.txt \*.bat
  215.  
  216.         This command searches the files in the current directory that
  217.         end in .txt and the .bat files in the root directory for the
  218.         string "the cat". Only exact case matches are listed on standard
  219.         output: occurrences of "The cat" and "the Cat" are not listed.
  220.  
  221.  
  222. grep -i "the cat" *.txt \*.bat
  223.  
  224.         This command is similar to the previous one except that it
  225.         performs a case-insensitive search. Occurrences of "The cat" and
  226.         "the CAT" would be listed in addition to any occurrences of "the
  227.         cat".
  228.  
  229.  
  230. grep -sn "the {1,}cat" *.txt
  231.  
  232.         This command searches all .txt files in the current directory
  233.         and in all subdirectories (recursively) for the pattern. The
  234.         pattern consists of the word "the", followed by one or more
  235.         spaces, and followed by the word "cat". Therefore, it would
  236.         match lines that contain "the cat" or "the cat". The
  237.         filename(line number) string is prepended to each line of each
  238.         file in which the pattern is found.
  239.  
  240.  
  241. grep -i "[a-z][a-z0-9_]{0,}(" *.c
  242.  
  243.         This command searches all .c files in the current directory for
  244.         function prototypes and function declarations. The pattern
  245.         matches any string that begins with a letter, is followed by
  246.         zero or more letters, numbers, or underscores, and ends with an
  247.         open parenthesis.
  248.  
  249.  
  250. t2bm -i <myfile.txt | grep "&cont\."
  251.  
  252.         This command searches the output of t2bm for the "&cont."
  253.         string. Note that the period in the pattern was escaped with a
  254.         backslash. The grep command would interpret the "&cont." pattern
  255.         as meaning the "&cont" string followed by any character.
  256.  
  257.  
  258. grep "^Usage$" *.doc
  259.  
  260.         This command searches all .doc files in the current directory
  261.         for lines that consist of nothing but the string "Usage".
  262.  
  263.  
  264. grep "streams\[" *.c
  265.  
  266.         This command searches all C files in the current directory for
  267.         lines that contain the "streams[" string. Note that the "["
  268.         character has to be escaped in the pattern so that it is
  269.         interpreted by grep as a bracket and not as the beginning of a
  270.         set or range.
  271.  
  272.  
  273. grep -v "^$" *.doc
  274.  
  275.         This command searches all .doc files in the current directory
  276.         and lists all lines that are not blank. Note that the ^$ pattern
  277.         matches any blank line.
  278.