home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / snip9707.zip / MATCH.DOC < prev    next >
Text File  |  1997-07-05  |  5KB  |  129 lines
  1. +++Date last modified: 05-Jul-1997
  2.  
  3.  
  4.                     REGEX Globber (Wild Card Matching)
  5.  
  6.                A *IX SH style pattern matcher written in C
  7.                    V1.10 Dedicated to the Public Domain
  8.  
  9.                                 March  12, 1991
  10.                                  J. Kercheval
  11.                          [72450,3702] -- johnk@wrq.com
  12.  
  13.  
  14.  
  15.  
  16. *IX SH style Regular Expressions
  17. ================================
  18.  
  19. The *IX command SH is a working shell similar in feel to the MSDOS
  20. shell COMMAND.COM.  In point of fact much of what we see in our
  21. familiar DOS PROMPT was gleaned from the early UNIX shells available
  22. for many of machines the people involved in the computing arena had
  23. at the time of the development of DOS and it's much maligned
  24. precursor CP/M (although the UNIX shells were and are much more
  25. flexible and powerful than those on the current flock of micro
  26. machines).  The designers of DOS and CP/M did some fairly strange
  27. things with their command processor and OS.  One of those things was
  28. to only selectively adopt the regular expressions allowed within the
  29. *IX shells.  Only '?' and '*' were allowed in filenames and even with
  30. these the '*' was allowed only at the end of a pattern and in fact
  31. when used to specify the filename the '*' did not apply to extension.
  32. This gave rise to the all too common expression "*.*".
  33.  
  34. REGEX Globber is a SH pattern matcher.  This allows such
  35. specifications as *75.zip or * (equivalent to *.* in DOS lingo).
  36. Expressions such as [a-e]*t would fit the name "apple.crt" or
  37. "catspaw.bat" or "elegant".  This allows considerably wider
  38. flexibility in file specification, general parsing or any other
  39. circumstance in which this type of pattern matching is wanted.
  40.  
  41. A match would mean that the entire string TEXT is used up in matching
  42. the PATTERN and conversely the matched TEXT uses up the entire
  43. PATTERN.
  44.  
  45. In the specified pattern string:
  46.      `*' matches any sequence of characters (zero or more)
  47.      `?' matches any character
  48.      `\' suppresses syntactic significance of a special character
  49.      [SET] matches any character in the specified set,
  50.      [!SET] or [^SET] matches any character not in the specified set.
  51.  
  52. A set is composed of characters or ranges; a range looks like
  53. 'character hyphen character' (as in 0-9 or A-Z).  [0-9a-zA-Z_] is the
  54. minimal set of characters allowed in the [..] pattern construct.
  55. Other characters are allowed (ie. 8 bit characters) if your system
  56. will support them (it almost certainly will).
  57.  
  58. To suppress the special syntactic significance of any of `[]*?!^-\',
  59. and match the character exactly, precede it with a `\'.
  60.  
  61. To view several examples of good and bad patterns and text see the
  62. output of MATCHTST.BAT
  63.  
  64.  
  65.  
  66. MATCH() and MATCHE()
  67. ====================
  68.  
  69. The match module as written has two parsing routines, one is matche()
  70. and the other is match().  Since match() is a call to matche() which
  71. simply has its output mapped to a BOOLEAN value (ie TRUE if pattern
  72. matches or FALSE otherwise), I will concentrate my explanations here
  73. on matche().
  74.  
  75. The purpose of matche() is to match a pattern against a string of
  76. text (usually a file name or specification).  The match routine has
  77. extensive pattern validity checking built into it as part of the
  78. parser and allows for a robust pattern match.
  79.  
  80. The parser gives an error code on return of type int.  The error code
  81. will be one of the following defined values (defined in match.h):
  82.  
  83.     MATCH_PATTERN  - bad pattern or misformed pattern
  84.     MATCH_LITERAL  - match failed on character match (standard
  85.                      character)
  86.     MATCH_RANGE    - match failure on character range ([..] construct)
  87.     MATCH_ABORT    - premature end of text string (pattern longer
  88.                      than text string)
  89.     MATCH_END      - premature end of pattern string (text longer
  90.                      than pattern called for)
  91.     MATCH_VALID    - valid match using pattern
  92.  
  93. The functions are declared as follows:
  94.  
  95.     BOOLEAN match (char *pattern, char *text);
  96.  
  97.     int     matche(register char *pattern, register char *text);
  98.  
  99.  
  100.  
  101. IS_VALID_PATTERN() and IS_PATTERN()
  102. ===================================
  103.  
  104. There are two routines for determining properties of a pattern
  105. string.  The first, is_pattern(), is designed simply to determine if
  106. some character exists within the text which is consistent with a SH
  107. regular expression (this function returns TRUE if so and FALSE if
  108. not).  The second, is_valid_pattern() is designed to check the
  109. validity of a given pattern string (TRUE return if valid, FALSE if
  110. not).  By 'validity', I mean well formed or syntactically correct.
  111.  
  112. In addition, is_valid_pattern() has as one of it's parameters a
  113. return code for determining the type of error found in the pattern if
  114. one exists.  The error codes are as follows and defined in match.h:
  115.  
  116.     PATTERN_VALID - pattern is well formed
  117.     PATTERN_ESC   - pattern has invalid literal escape ('\' at end of
  118.                     pattern)
  119.     PATTERN_RANGE - [..] construct has a no end range in a '-' pair
  120.                     (ie [a-])
  121.     PATTERN_CLOSE - [..] construct has no end bracket (ie [abc-g )
  122.     PATTERN_EMPTY - [..] construct is empty (ie [])
  123.  
  124. The functions are declared as follows:
  125.  
  126.     BOOLEAN is_valid_pattern (char *pattern, int *error_type);
  127.  
  128.     BOOLEAN is_pattern (char *pattern);
  129.