home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / c / wildf113.zip / WILDFILE.DOC < prev    next >
Text File  |  1991-05-07  |  9KB  |  227 lines
  1.  
  2.  
  3.                        WildFile for MS-DOS systems
  4.  
  5.                  A *IX SH style file globber written in C
  6.                    V1.13 Dedicated to the Public Domain
  7.  
  8.                                 April 22, 1991
  9.                                  J. Kercheval
  10.                          [72450,3702] -- johnk@wrq.com
  11.  
  12.  
  13.  
  14. 05-07-91
  15.  
  16. This is V1.13 of Wildfile a *IX SH style file Globber.
  17.  
  18. The purpose of this code is to enable the programmer to allow *real*
  19. wildcard file specification.  The UNIX (*IX) SH style wildcard system
  20. has been around for decades and there is absolutely no good reason for
  21. it's lack of presence within MS/PC DOS and its associated tools.
  22.  
  23. I submit this without copyright and with the clear understanding that
  24. this code may be used by anyone, for any reason, with any modifications
  25. and without any guarantees, warrantee or statements of usability of any
  26. sort.
  27.  
  28.  
  29.                                 jbk
  30.  
  31.  
  32.  
  33. *IX SH style wildcard file globbing
  34. ===================================
  35.  
  36. The unix style of wildcard globbing (matching files to a wildcard
  37. specification) is quite a bit more flexible than the standard
  38. approach seen on the MS\PC DOS machines.  The full power of *IX SH
  39. style regular expressions are allowed to specify a file name.  For
  40. instance:
  41.     "*t*"           would match to the filenames test.doc, wet.goo,
  42.                     itsy.bib, foo.tic, etc.
  43.     "th?[a-eg]."    would match to any file without an extension,
  44.                     whose first two letters were "th", with any third
  45.                     letter and whose last letter was a,b,c,d,e or g.
  46.                     (ie. thug, thod, thud, etc.)
  47.     "*"             would match all filenames.
  48.     
  49. The regular expression syntax is described in detail in the source
  50. code and below.
  51.  
  52.  
  53. Implementation
  54. ==============
  55.  
  56. The implementation of the wildcard package is similar in type to the
  57. standard MS/PC DOS function calls for file searches.  There is a
  58. find_firstfile call which begins a search initially and a
  59. find_nextfile call which continues a previous search.  This approach
  60. will normally yeild a very quick port from existing *standard*
  61. implementations of wildcard file searching.
  62.  
  63. The include file WILDFILE.H does a good job of describing the
  64. specifics required here.
  65.  
  66.  
  67. WD
  68. ==
  69.  
  70. WD is a very quick implementation of a directory lister to try to
  71. show the usage of the wildfile module as intended.  The program is a
  72. fully functional program complete with usage messages and command
  73. line argument parsing.
  74.  
  75.  
  76. Languages
  77. =========
  78.  
  79. WILDFILE (and its associated module MATCH) were developed and
  80. compiled using both MicroSoft C V6.00A and Borland C++.
  81.  
  82.  
  83.  
  84. ============================================================================
  85.  
  86.  
  87. 05-07-91
  88.  
  89. Wildfile uses MATCH V1.10 modified for the specific nits required
  90. the MS/PC DOS environment.  The documentation for MATCH is included
  91. for convenience.
  92.  
  93.                                 jbk
  94.  
  95.  
  96. ============================================================================
  97.  
  98.  
  99. MATCH110
  100.  
  101.  
  102.                     REGEX Globber (Wild Card Matching)
  103.  
  104.                A *IX SH style pattern matcher written in C
  105.                    V1.10 Dedicated to the Public Domain
  106.  
  107.                                 March  12, 1991
  108.                                  J. Kercheval
  109.                          [72450,3702] -- johnk@wrq.com
  110.  
  111.  
  112.  
  113.  
  114. *IX SH style Regular Expressions
  115. ================================ 
  116.  
  117. The *IX command SH is a working shell similar in feel to the MSDOS
  118. shell COMMAND.COM.  In point of fact much of what we see in our
  119. familiar DOS PROMPT was gleaned from the early UNIX shells available
  120. for many of machines the people involved in the computing arena had
  121. at the time of the development of DOS and it's much maligned
  122. precursor CP/M (although the UNIX shells were and are much more
  123. flexible and powerful then those on the current flock of micro
  124. machines).  The designers of DOS and CP/M did some fairly strange
  125. things with their command processor and OS.  One of those things was
  126. to only selectively adopt the regular expressions allowed within the
  127. *IX shells.  Only '?' and '*' were allowed in filenames and even with
  128. these the '*' was allowed only at the end of a pattern and in fact
  129. when used to specify the filename the '*' did not apply to extension.
  130. This gave rise to the all too common expression "*.*".
  131.  
  132. REGEX Globber is a SH pattern matcher.  This allows such
  133. specifications as *75.zip or * (equivelant to *.* in DOS lingo).
  134. Expressions such as [a-e]*t would fit the name "apple.crt" or
  135. "catspaw.bat" or "elegant".  This allows considerably wider
  136. flexibility in file specification, general parsing or any other
  137. circumstance in which this type of pattern matching is wanted. 
  138.  
  139. A match would mean that the entire string TEXT is used up in matching
  140. the PATTERN and conversely the matched TEXT uses up the entire
  141. PATTERN. 
  142.  
  143. In the specified pattern string:
  144.      `*' matches any sequence of characters (zero or more)
  145.      `?' matches any character
  146.      `\' suppresses syntactic significance of a special character
  147.      [SET] matches any character in the specified set,
  148.      [!SET] or [^SET] matches any character not in the specified set.
  149.  
  150. A set is composed of characters or ranges; a range looks like
  151. 'character hyphen character' (as in 0-9 or A-Z).  [0-9a-zA-Z_] is the
  152. minimal set of characters allowed in the [..] pattern construct.
  153. Other characters are allowed (ie. 8 bit characters) if your system
  154. will support them (it almost certainly will).
  155.  
  156. To suppress the special syntactic significance of any of `[]*?!^-\',
  157. and match the character exactly, precede it with a `\'.
  158.  
  159. To view several examples of good and bad patterns and text see the
  160. output of MATCHTST.BAT
  161.  
  162.  
  163.  
  164. MATCH() and MATCHE()
  165. ====================
  166.  
  167. The match module as written has two parsing routines, one is matche()
  168. and the other is match().  Since match() is a call to matche() which
  169. simply has its output mapped to a BOOLEAN value (ie TRUE if pattern
  170. matches or FALSE otherwise), I will concentrate my explanations here
  171. on matche().
  172.  
  173. The purpose of matche() is to match a pattern against a string of
  174. text (usually a file name or specification).  The match routine has
  175. extensive pattern validity checking built into it as part of the
  176. parser and allows for a robust pattern match.
  177.  
  178. The parser gives an error code on return of type int.  The error code
  179. will be one of the the following defined values (defined in match.h):
  180.  
  181.     MATCH_PATTERN  - bad pattern or misformed pattern
  182.     MATCH_LITERAL  - match failed on character match (standard
  183.                      character)
  184.     MATCH_RANGE    - match failure on character range ([..] construct)
  185.     MATCH_ABORT    - premature end of text string (pattern longer
  186.                      than text string)
  187.     MATCH_END      - premature end of pattern string (text longer
  188.                      than pattern called for)
  189.     MATCH_VALID    - valid match using pattern
  190.  
  191. The functions are declared as follows:
  192.  
  193.     BOOLEAN match (char *pattern, char *text);
  194.  
  195.     int     matche(register char *pattern, register char *text);
  196.  
  197.  
  198.  
  199. IS_VALID_PATTERN() and IS_PATTERN()
  200. ===================================
  201.  
  202. There are two routines for determining properties of a pattern
  203. string.  The first, is_pattern(), is designed simply to determine if
  204. some character exists within the text which is consistent with a SH
  205. regular expression (this function returns TRUE if so and FALSE if
  206. not).  The second, is_valid_pattern() is designed to check the
  207. validity of a given pattern string (TRUE return if valid, FALSE if
  208. not).  By 'validity', I mean well formed or syntactically correct.
  209.  
  210. In addition, is_valid_pattern() has as one of it's parameters a
  211. return code for determining the type of error found in the pattern if
  212. one exists.  The error codes are as follows and defined in match.h:
  213.  
  214.     PATTERN_VALID - pattern is well formed
  215.     PATTERN_ESC   - pattern has invalid literal escape ('\' at end of
  216.                     pattern)
  217.     PATTERN_RANGE - [..] construct has a no end range in a '-' pair
  218.                     (ie [a-])
  219.     PATTERN_CLOSE - [..] construct has no end bracket (ie [abc-g )
  220.     PATTERN_EMPTY - [..] construct is empty (ie [])
  221.  
  222. The functions are declared as follows:
  223.  
  224.     BOOLEAN is_valid_pattern (char *pattern, int *error_type);
  225.  
  226.     BOOLEAN is_pattern (char *pattern);
  227.