home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / elvis184.zip / doc / regexp.ms < prev    next >
Text File  |  1995-05-26  |  8KB  |  201 lines
  1. .Go 4 "REGULAR EXPRESSIONS"
  2.  
  3. .PP
  4. \*E uses regular expressions for searching and substitutions.
  5. A regular expression is a text string in which some characters have
  6. special meanings.
  7. This is much more powerful than simple text matching.
  8. .LP
  9. .SH
  10. Syntax
  11. .PP
  12. \*E' regexp package treats the following one- or two-character
  13. strings (called meta-characters) in special ways:
  14. .sp
  15. .IP "\e(\fIsubexpression\fP\e)" 0.8i
  16. The \e( and \e) metacharacters are used to delimit subexpressions.
  17. When the regular expression matches a particular chunk of text,
  18. \*E will remember which portion of that chunk matched the \fIsubexpression\fP.
  19. The :s/regexp/newtext/ command makes use of this feature.
  20. .IP "^" 0.8i
  21. The ^ metacharacter matches the beginning of a line.
  22. If, for example, you wanted to find "foo" at the beginning of a line,
  23. you would use a regular expression such as /^foo/.
  24. Note that ^ is only a metacharacter if it occurs
  25. at the beginning of a regular expression;
  26. anyplace else, it is treated as a normal character.
  27. .IP "$" 0.8i
  28. The $ metacharacter matches the end of a line.
  29. It is only a metacharacter when it occurs at the end of a regular expression;
  30. elsewhere, it is treated as a normal character.
  31. For example, the regular expression /$$/ will search for a dollar sign at
  32. the end of a line.
  33. .IP "\e<" 0.8i
  34. The \e< metacharacter matches a zero-length string at the beginning of
  35. a word.
  36. A word is considered to be a string of 1 or more letters and digits.
  37. A word can begin at the beginning of a line
  38. or after 1 or more non-alphanumeric characters.
  39. .IP "\e>" 0.8i
  40. The \e> metacharacter matches a zero-length string at the end of a word.
  41. A word can end at the end of the line
  42. or before 1 or more non-alphanumeric characters.
  43. For example, /\e<end\e>/ would find any instance of the word "end",
  44. but would ignore any instances of e-n-d inside another word
  45. such as "calendar".
  46. .IP "\e=" 0.8i
  47. This matches any zero-length string; i.e., it has no effect on the text that
  48. a regular expression will match.
  49. However, it has a useful side-effect for the forward visual search command:
  50. Instead of leaving the cursor at the front of the matching text, it will
  51. leave the cursor at the position that matched the \e= metacharacter.
  52. For example, "/zo\e=t^M" will locate the next "zot" and leave the cursor
  53. on the 't' instead of the 'z'.
  54. .IP "\&." 0.8i
  55. The . metacharacter matches any single character.
  56. .IP "[\fIcharacter-list\fP]" 0.8i
  57. This matches any single character from the \fIcharacter-list\fP.
  58. Inside the \fIcharacter-list\fP, you can denote a span of characters
  59. by writing only the first and last characters, with a hyphen between
  60. them.
  61. If the \fIcharacter-list\fP is preceded by a ^ character, then the
  62. list is inverted -- it will match character that \fIisn't\fP mentioned
  63. in the list.
  64. For example, /[a-zA-Z]/ matches any letter, and /[^ ]/ matches anything
  65. other than a blank.
  66. .IP "\e@" 0.8i
  67. If you are in visual mode, and the cursor is on a word in the edit buffer
  68. before you start typing the regular expression, then \e@ will match the
  69. word at the cursor.
  70. For example, ":map #1 /\e<\e@\e>^M" will cause the <F1> key to search for
  71. the next occurrence of the word under the cursor.
  72. .IP "\e{\fIn\fP\e}" 0.8i
  73. This is a closure operator,
  74. which means that it can only be placed after something that matches a
  75. single character.
  76. It controls the number of times that the single-character expression
  77. should be repeated.
  78. .IP "" 0.8i
  79. The \e{\fIn\fP\e} operator, in particular, means that the preceding
  80. expression should be repeated exactly \fIn\fP times.
  81. For example, /^-\e{80\e}$/ matches a line of eighty hyphens, and
  82. /\e<[a-zA-Z]\e{4\e}\e>/ matches any four-letter word.
  83. .IP "\e{\fIn\fP,\fIm\fP\e}" 0.8i
  84. This is a closure operator which means that the preceding single-character
  85. expression should be repeated between \fIn\fP and \fIm\fP times, inclusive.
  86. If the \fIm\fP is omitted (but the comma is present) then \fIm\fP is
  87. taken to be infinity.
  88. For example, /"[^"]\e{3,5\e}"/ matches any pair of quotes which contains
  89. three, four, or five non-quote characters.
  90. .IP "*" 0.8i
  91. The * metacharacter is a closure operator which means that the preceding
  92. single-character expression can be repeated zero or more times.
  93. It is equivalent to \e{0,\e}.
  94. For example, /.*/ matches a whole line.
  95. .IP "\e+" 0.8i
  96. The \e+ metacharacter is a closure operator which means that the preceding
  97. single-character expression can be repeated one or more times.
  98. It is equivalent to \e{1,\e}.
  99. For example, /.\e+/ matches a whole line, but only if the line contains
  100. at least one character.
  101. It doesn't match empty lines.
  102. .IP "\e?" 0.8i
  103. The \e? metacharacter is a closure operator which indicates that the
  104. preceding single-character expression is optional -- that is, that it
  105. can occur 0 or 1 times.
  106. It is equivalent to \e{0,1\e}.
  107. For example, /no[ -]\e?one/ matches "no one", "no-one", or "noone".
  108. .PP
  109. Anything else is treated as a normal character which must exactly match
  110. a character from the scanned text.
  111. The special strings may all be preceded by a backslash to
  112. force them to be treated normally.
  113. .LP
  114. .SH
  115. Substitutions
  116. .PP
  117. The :s command has at least two arguments: a regular expression,
  118. and a substitution string.
  119. The text that matched the regular expression is replaced by text
  120. which is derived from the substitution string.
  121. .br
  122. .ne 15 \" so we don't mess up the table
  123. .PP
  124. Most characters in the substitution string are copied into the
  125. text literally but a few have special meaning:
  126. .LD
  127. .ta 0.75i 1.3i
  128.     &    Insert a copy of the original text
  129.     ~    Insert a copy of the previous replacement text
  130.     \e1    Insert a copy of that portion of the original text which
  131.         matched the first set of \e( \e) parentheses
  132.     \e2-\e9    Do the same for the second (etc.) pair of \e( \e)
  133.     \eU    Convert all chars of any later & or \e# to uppercase
  134.     \eL    Convert all chars of any later & or \e# to lowercase
  135.     \eE    End the effect of \eU or \eL
  136.     \eu    Convert the first char of the next & or \e# to uppercase
  137.     \el    Convert the first char of the next & or \e# to lowercase
  138. .TA 8
  139. .DE
  140. .PP
  141. These may be preceded by a backslash to force them to be treated normally.
  142. If "nomagic" mode is in effect,
  143. then & and ~ will be treated normally,
  144. and you must write them as \e& and \e~ for them to have special meaning.
  145. .LP
  146. .SH
  147. Options
  148. .PP
  149. \*E has two options which affect the way regular expressions are used.
  150. These options may be examined or set via the :set command.
  151. .PP
  152. The first option is called "[no]magic".
  153. This is a boolean option, and it is "magic" (TRUE) by default.
  154. While in magic mode, all of the meta-characters behave as described above.
  155. In nomagic mode, only ^ and $ retain their special meaning.
  156. .PP
  157. The second option is called "[no]ignorecase".
  158. This is a boolean option, and it is "noignorecase" (FALSE) by default.
  159. While in ignorecase mode, the searching mechanism will not distinguish between
  160. an uppercase letter and its lowercase form.
  161. In noignorecase mode, uppercase and lowercase are treated as being different.
  162. .PP
  163. Also, the "[no]wrapscan" option affects searches.
  164. .LP
  165. .SH
  166. Examples
  167. .PP
  168. This example changes every occurrence of "utilize" to "use":
  169. .sp
  170. .ti +1i
  171. :%s/utilize/use/g
  172. .PP
  173. This example deletes all whitespace that occurs at the end of a line anywhere
  174. in the file.
  175. (The brackets contain a single space and a single tab.):
  176. .sp
  177. .ti +1i
  178. :%s/[   ]\e+$//
  179. .PP
  180. This example converts the current line to uppercase:
  181. .sp
  182. .ti +1i
  183. :s/.*/\eU&/
  184. .PP
  185. This example underlines each letter in the current line,
  186. by changing it into an "underscore backspace letter" sequence.
  187. (The ^H is entered as "control-V backspace".):
  188. .sp
  189. .ti +1i
  190. :s/[a-zA-Z]/_^H&/g
  191. .PP
  192. This example locates the last colon in a line,
  193. and swaps the text before the colon with the text after the colon.
  194. The first \e( \e) pair is used to delimit the stuff before the colon,
  195. and the second pair delimit the stuff after.
  196. In the substitution text, \e1 and \e2 are given in reverse order
  197. to perform the swap:
  198. .sp
  199. .ti +1i
  200. :s/\e(.*\e):\e(.*\e)/\e2:\e1/
  201.