home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / regexp.n < prev    next >
Encoding:
Text File  |  1995-02-22  |  6.1 KB  |  148 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) regexp.n 1.6 95/02/22 14:37:26
  9. '\" 
  10. .so man.macros
  11. .HS regexp tcl
  12. .BS
  13. '\" Note:  do not modify the .SH NAME line immediately below!
  14. .SH NAME
  15. regexp \- Match a regular expression against a string
  16. .SH SYNOPSIS
  17. \fBregexp \fR?\fIswitches\fR? \fIexp string \fR?\fImatchVar\fR? ?\fIsubMatchVar subMatchVar ...\fR?
  18. .BE
  19.  
  20. .SH DESCRIPTION
  21. .PP
  22. Determines whether the regular expression \fIexp\fR matches part or
  23. all of \fIstring\fR and returns 1 if it does, 0 if it doesn't.
  24. .LP
  25. If additional arguments are specified after \fIstring\fR then they
  26. are treated as the names of variables in which to return
  27. information about which part(s) of \fIstring\fR matched \fIexp\fR.
  28. \fIMatchVar\fR will be set to the range of \fIstring\fR that
  29. matched all of \fIexp\fR.  The first \fIsubMatchVar\fR will contain
  30. the characters in \fIstring\fR that matched the leftmost parenthesized
  31. subexpression within \fIexp\fR, the next \fIsubMatchVar\fR will
  32. contain the characters that matched the next parenthesized
  33. subexpression to the right in \fIexp\fR, and so on.
  34. .LP
  35. If the initial arguments to \fBregexp\fR start with \fB\-\fR then
  36. .VS
  37. they are treated as switches.  The following switches are
  38. currently supported:
  39. .TP 10
  40. \fB\-nocase\fR
  41. Causes upper-case characters in \fIstring\fR to be treated as
  42. lower case during the matching process.
  43. .TP 10
  44. \fB\-indices\fR
  45. Changes what is stored in the \fIsubMatchVar\fRs. 
  46. Instead of storing the matching characters from \fBstring\fR,
  47. each variable
  48. will contain a list of two decimal strings giving the indices
  49. in \fIstring\fR of the first and last characters in the matching
  50. range of characters.
  51. .TP 10
  52. \fB\-\|\-\fR
  53. Marks the end of switches.  The argument following this one will
  54. be treated as \fIexp\fR even if it starts with a \fB\-.
  55. .VE
  56. .LP
  57. If there are more \fIsubMatchVar\fR's than parenthesized
  58. subexpressions within \fIexp\fR, or if a particular subexpression
  59. in \fIexp\fR doesn't match the string (e.g. because it was in a
  60. portion of the expression that wasn't matched), then the corresponding
  61. \fIsubMatchVar\fR will be set to ``\fB\-1 \-1\fR'' if \fB\-indices\fR
  62. has been specified or to an empty string otherwise.
  63.  
  64. .SH "REGULAR EXPRESSIONS"
  65. .PP
  66. Regular expressions are implemented using Henry Spencer's package
  67. (thanks, Henry!),
  68. and much of the description of regular expressions below is copied verbatim
  69. from his manual entry.
  70. .PP
  71. A regular expression is zero or more \fIbranches\fR, separated by ``|''.
  72. It matches anything that matches one of the branches.
  73. .PP
  74. A branch is zero or more \fIpieces\fR, concatenated.
  75. It matches a match for the first, followed by a match for the second, etc.
  76. .PP
  77. A piece is an \fIatom\fR possibly followed by ``*'', ``+'', or ``?''.
  78. An atom followed by ``*'' matches a sequence of 0 or more matches of the atom.
  79. An atom followed by ``+'' matches a sequence of 1 or more matches of the atom.
  80. An atom followed by ``?'' matches a match of the atom, or the null string.
  81. .PP
  82. An atom is a regular expression in parentheses (matching a match for the
  83. regular expression), a \fIrange\fR (see below), ``.''
  84. (matching any single character), ``^'' (matching the null string at the
  85. beginning of the input string), ``$'' (matching the null string at the
  86. end of the input string), a ``\e'' followed by a single character (matching
  87. that character), or a single character with no other significance
  88. (matching that character).
  89. .PP
  90. A \fIrange\fR is a sequence of characters enclosed in ``[]''.
  91. It normally matches any single character from the sequence.
  92. If the sequence begins with ``^'',
  93. it matches any single character \fInot\fR from the rest of the sequence.
  94. If two characters in the sequence are separated by ``\-'', this is shorthand
  95. for the full list of ASCII characters between them
  96. (e.g. ``[0-9]'' matches any decimal digit).
  97. To include a literal ``]'' in the sequence, make it the first character
  98. (following a possible ``^'').
  99. To include a literal ``\-'', make it the first or last character.
  100.  
  101. .SH "CHOOSING AMONG ALTERNATIVE MATCHES"
  102. .PP
  103. In general there may be more than one way to match a regular expression
  104. to an input string.  For example, consider the command
  105. .DS
  106. \fBregexp  (a*)b*  aabaaabb  x  y
  107. .DE
  108. Considering only the rules given so far, \fBx\fR and \fBy\fR could
  109. end up with the values \fBaabb\fR and \fBaa\fR, \fBaaab\fR and \fBaaa\fR,
  110. \fBab\fR and \fBa\fR, or any of several other combinations.
  111. To resolve this potential ambiguity \fBregexp\fR chooses among
  112. alternatives using the rule ``first then longest''.
  113. In other words, it considers the possible matches in order working
  114. from left to right across the input string and the pattern, and it
  115. attempts to match longer pieces of the input string before shorter
  116. ones.  More specifically, the following rules apply in decreasing
  117. order of priority:
  118. .IP [1]
  119. If a regular expression could match two different parts of an input string
  120. then it will match the one that begins earliest.
  121. .IP [2]
  122. If a regular expression contains \fB|\fR operators then the leftmost
  123. matching sub-expression is chosen.
  124. .IP [3]
  125. In \fB*\fR, \fB+\fR, and \fB?\fR constructs, longer matches are chosen
  126. in preference to shorter ones.
  127. .IP [4]
  128. In sequences of expression components the components are considered
  129. from left to right.
  130. .LP
  131. In the example from above, \fB(a*)b*\fR matches \fBaab\fR:  the \fB(a*)\fR
  132. portion of the pattern is matched first and it consumes the leading
  133. \fBaa\fR; then the \fBb*\fR portion of the pattern consumes the
  134. next \fBb\fR.  Or, consider the following example:
  135. .DS
  136. \fBregexp  (ab|a)(b*)c  abc  x  y  z
  137. .DE
  138. After this command \fBx\fR will be \fBabc\fR, \fBy\fR will be
  139. \fBab\fR, and \fBz\fR will be an empty string.
  140. Rule 4 specifies that \fB(ab|a)\fR gets first shot at the input
  141. string and Rule 2 specifies that the \fBab\fR sub-expression
  142. is checked before the \fBa\fR sub-expression.
  143. Thus the \fBb\fR has already been claimed before the \fB(b*)\fR
  144. component is checked and \fB(b*)\fR must match an empty string.
  145.  
  146. .SH KEYWORDS
  147. match, regular expression, string
  148.