!=======================================================================
!     
!  Title:        VMSGREP help file
!                
!  Abstract:     This file should be place in a help library.
!                To put VMSGREP in the main help library type:
!                
!                $ LIBRARY/HELP SYS$HELP:HELPLIB VMSGREP.HLP
!                
!  Environment:  VMS
!                
!  Author:       Eric Andresen of General Research Corporation
!                
!  Date:         21-AUG-1986
!                
!-----------------------------------------------------------------------

1 GREP
 The GREP command enables you to search through files for a string that
 matches one or more patterns.  GREP displays all of the lines that match
 the pattern(s). 

 Format:

      GREP file-spec[,...] pattern-string
2 Parameters
 file-spec[,...]   

 Specifies file(s) to be printed.  A list of up to 20 files with wild
 card characters may be specified.  Each file name may have up to 255
 characters. 

 pattern-string

 Specifies a pattern string to search for in the specified files.  If the
 string contains any special characters or lowercase letters then enclose
 the string in quotes.  The /EXACT qualifier causes GREP to differentiate
 between uppercase and lowercase letters.  See the section PATTERNS for
 the syntax of the pattern-string. 
2 Command_Qualifiers
/EXACT

 /[NO]EXACT                default=/NOEXACT
 Controls whether the GREP command matches the search string exactly, or
 treats uppercase and lowercase letters as equivalents.  The default is
 /NOEXACT, causing GREP to ignore case differences. 
/HEADING

 /[NO]HEADING              default=/NOHEADING
 Controls whether file names are printed in the output. With the default
 heading format, file names are printed only when more than one file is
 specified or when wild card characters are used.  The seperator, a line
 of 30 asterisks, is displayed between groups of lines that belong to
 different files. 
/LOG

 /[NO]LOG                  default=/NOLOG
 Controls whether the GREP command produces a line containing the file
 name and the number of records and matches for each file searched.  The
 log information is output to the current SYS$OUTPUT device. 
/NOT

 /[NO]NOT                  default=/NONOT
 Causes lines that do not match the specified pattern(s) to be printed
 rather than those that do match.  The statistics in the /LOG output will
 still correspond to correct matches even if /NOT is used. 
/NUMBERS

 /[NO]NUMBERS              default=/NONUMBERS
 Controls whether the source line number is displayed at the left margin
 of each line.  By default, line numbers are not displayed. 
/OUTPUT

 /[NO]OUTPUT[=file-spec]   default=/OUTPUT
 Controls whether the results of the search are output to a specified
 file.  The output will be sent to the current default output device
 (SYS$OUTPUT) if you omit the /OUTPUT qualifier or omit the file
 specification.  The /NOOUTPUT qualifier means that no matching records
 are output as a result of the GREP command. 
2 Patterns
 Regular expressions are composed of the following:

 ^     matches the beginning of a line
 $     matches the end of a line
 .     matches any character
 \     followed by a single character matches that character.
       The following are special exceptions:
 \b    backspace
 \n    linefeed
 \r    carriage return
 \s    space
 \t    tab
 \\    backslash
 
 Note: The metacharacters ()+? are not supported as in the standard UNIX
       GREP command.

 A single character not otherwise endowed with special meaning matches 
 that character.

 A string enclosed in brackets [] specifies a character class.  Any 
 single character in the string will be matched.  For example, [abc]
 will match an a, b or c.  Ranges of ASCII character codes may be 
 abbreviated, as in [a-z0-9].  If the first symbol following the [ is 
 a ^ then a negative character class is specified.  In this case, the 
 string matches all characters except those enclosed in the brackets
 (that is, [^a-z] matches everything except lowercase letters).  Note 
 that a negative character class must match something, even though that 
 something cannot be any of the characters listed.  For example, ^$ is 
 not the same as ^[^z]$.  The first example matches an empty line
 (beginning of line followed by end of line); the second example matches 
 a beginning of line followed by any character except a z followed by end 
 of line.  In the second example a character must be present on the line,
 but that character cannot be a z.  Note that the characters *.^$ are not
 special characters when inside a character class.
 
 A regular expression followed by a * matches zero or more matches of the 
 regular expression.
 
 Two regular expressions concatenated match a match of the first, 
 followed by a match of the second.
 
 Two regular expressions separated by a | match either a match for the 
 first or a match for the second.

 The order of precedence is [] then * then concatenation then |.
2 Example
 The command line:

 $ GREP/NUMBERS  FILE.C,FILE2.C  "^[a-z][a-z]*[\s\t]*.*([^;]*)[^;]*$"

 creates a cross-reference of the C program FILE1.C and FILE2.C.  GREP's
 output will show all function declarations in the specified files, 
 preceded by the appropriate line number.

 Because of the special characters in the pattern it is necessary to 
 enclose the string in double quotes.

 The regular expression is interpreted as follows: beginning of line (^),
 followed by one or more occurances of any character in the ranges a-z
 ([a-z][a-z]*), followed by either a space or a tab repeated zero or more
 times ([\s\t]*), followed by any character repeated zero or more times
 (.*), followed by an open parenthesis ((), followed by any character
 except a semicolon repeated zero or more times ([^;]*), followed by a
 close parenthesis ()), followed by any character except a semicolon
 repeated zero or more times ([;]*), followed by end of line ($). 
