Documentation for GREP.DLL
     Written by: Chris Roberts 03/16/92


     The Grep DLL was written to  enhance Huw Millington's WinGrep program.
     It allows the  program  access  to  a  more  robust  set  of GREP type
     searches. But, it may be used as a grep engine to any program that has
     the ability to call a DLL.


     Version 1.0  of  GREP.DLL  has  three  functions.  The  first function
     returns the version number.  This  is  not  of  any importance... yet.
     High-byte is major version number,  low-byte  is minor version number.
     IE. 0x0100 = version 1.0, 0x0210 = 2.10.

          WORD FAR PASCAL GrepVersion( void );


     The second is the  CompileGrep()  function.  This  function is used to
     compile a search string into  a  string  used  more efficiently by the
     Grep Engine. It is passed a GrepString to compile, which it returns in
     CompiledGrep. Passing a non-zero value  for  IgnoreCase will cause the
     searches to ignore case, while a zero will force case-sensitivity.

         int FAR PASCAL  CompileGrep(char  *GrepString, char *CompiledGrep,
     char IgnoreCase );

     It returns a  zero  (0)  if  the  GrepString  was  valid, otherwise it
     returns an error code reporting that the GrepString was NOT valid:

     GCOMP_NO_ERROR                 No error occurred.

     GCOMP_ILLEGAL_OCCURANCE_OP     An *, +, or  -  appeared in an invalid
                                    place. These cannot follow a ^ or a $.

     GCOMP_UNKNOWN_TYPE             Illegal type given for  a ':' command.
                                    The only  valid  types  are  'a', 'd',
                                    'n', and ' '.

     GCOMP_NO_TYPE                  The ':' command was  given as the last
                                    character in a search string.
     GCOMP_BAD_CLASS_TERMINATION    A quoted character coammnd '\' without
                                    a character to  quote  (ie.  it is the
                                    end of the  string)  was  listed  in a
                                    class '[]'. ie. '[abc\'.
     GCOMP_UNTERMINATED_CLASS       There is no  corresponding  ']' with a
                                    '['.
     GCOMP_CLASS_TOO_LARGE          A class is larger than 256 characters.

     GCOMP_EMPTY_CLASS              An  empty  class  was  specified.  ie.
                                    'AB[]YZ'.

     The error code constants are  defined  in  GREP.H.  If the compile was
     successful CompiledGrep now contains a  grep  string  that may be used
     for searches.


     The third function  in  GREP.DLL  is  simply  called  Grep(). This, of
     course, does all of the work of checking for a match.

         int FAR PASCAL Grep( char *StringToSearch, char *CompiledGrep );

     Grep() returns the position of the first character of the match (ie. 1
     = first character), or zero (0) if there was no match.

     The following commands are supported GREP commands:


     \       The backslash quotes any character.  This allows a search that
             contains a character that is usually a GREP command.
             Example:

             \$ matches a dollar-sign.

     ^       A circumflex at the  beginning  of  an  expression matches the
             beginning of a line.

     $       A dollar-sign at the end of an expression matches the end of a
             line.

     ?       A question mark  matches  any  SINGLE  character (except "new-
             line").

     :_      A colon  matches  a  class  of  characters  described  by  the
             following character:

             :a matches any alphabetic (always ignores case)
             :d matches digits
             :n matches alphanumerics  (always ignores case)
             :  matches spaces, tabs, and other control characters, such as
             new-line.

     *       An expression followed by  an  asterisk  matches  ZERO or more
             occurrances of that expression:

             fo* matches f, fo, foo, etc
             a*z matches az, abz, akfuhidfgnidhgz, etc

     +       An expression followed by  a  plus  sign  matches  ONE or more
             occurrances of that expression:

             fo+ matches fo, etc

     -       An expression followed by a  minus sign optionally matches the
             expression.

     []      A string enclosed in square  brackets matches any character in
             that string, but no  others.  If  the  first  character in the
             string is a circumflex,  the  expression matches any character
             except "new-line" and the characters in the string.
             Example:

             [xyz]  matches  xx,   and  zyx,  while
             [^xyz] matches abc but not axb.

             A range of  characters  may  be  specified  by  two characters
             separated by -.  Note that,     [a-z]   matches   alphabetics,
             while [z-a] never matches.