home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxregexp.zip / rxregexp.ipf < prev    next >
Text File  |  1998-04-14  |  13KB  |  346 lines
  1. .*---------------------------------------------------------------------------
  2. .*                    A.N.Z. Bank Confidential
  3. .*
  4. .*     MODULE NAME:   RxRegExp.IPF
  5. .*
  6. .*         $Author:   Dennis_Bareis  $
  7. .*       $Revision:   1.1  $
  8. .*           $Date:   09 Aug 1996 15:55:54  $
  9. .*        $Logfile:   Q:/PVCSDATA/SUPPORT/SUPPORT/TEMPLATE.IPV  $
  10. .*
  11. .*     DESCRIPTION:
  12. .*
  13. .*---------------------------------------------------------------------------
  14.  
  15.  
  16.  
  17. .im IPFGEN.IPF
  18. :userdoc.
  19. :Title.Regular Expressions For REXX (<$IpfTimeVersion?>)
  20. :docprof toc=123456.
  21.  
  22.  
  23.  
  24. .*===========================================================================
  25. :Heading p1='Introduction' p2='Introduction'.
  26. .*===========================================================================
  27. :i1 id=Introduction.Introduction
  28.  
  29. :BigTitle p1='Introduction'.
  30.  
  31. :p.The "RxRegExp.DLL" code allows any rexx program to make fast
  32. extensive use of
  33. :LinkToText p1='RegularExpression' p2='regular expression'.
  34. searches and replaces.
  35.  
  36. :p.The original regular expession "engine" (which was not modified) was
  37. written by "Henry&rbl.Spencer" (henry@zoo.toronto.edu).  There is no version
  38. number on this source that I can find although the doco is dated
  39. "5&rbl.Sept&rbl.1996".
  40.  
  41. :p.I have provided a
  42. :LinkToText p1='Example' p2='sample rexx program'. which should help
  43. you get started.
  44.  
  45. :p.The DLL was written by "Dennis&rbl.Bareis" (:Bold p1='db0@anz.com'.), the
  46. latest code can be obtained from my web page at
  47. ":Bold p1='http&colon.//www.ozemail.com.au/~dbareis'.".
  48.  
  49.  
  50.  
  51. .*===========================================================================
  52. :Heading p1='RegularExpression' p2='Regular Expressions'.
  53. .*===========================================================================
  54. :i1 id=RegularExpression.Regular Expressions
  55.  
  56. :p.The following description is based on the documentation written by
  57. "Henry&rbl.Spencer" (henry@zoo.toronto.edu).
  58.  
  59. :BigTitle p1='Regular Expressions'.
  60.  
  61. :p.A regular expression is a sequence of characters which describes
  62. what we are searching for.
  63.  
  64. :p.A regular expression is zero or more :DarkGreen p1='branches'.
  65. separated by ":Red p1='|'.".  It matches anything that matches one
  66. of the branches.
  67.  
  68. :p.A branch is zero or more :DarkGreen p1='pieces'., concatenated.
  69. It matches a match for the first, followed by a match for the second, etc.
  70.  
  71. :p.A piece is an :DarkGreen p1='atom'. possibly followed by "*", "+", or
  72. "?" where&colon.
  73. :UnNumberedListCompact.
  74. :li.An atom followed by ":Red p1='*'." matches a sequence of 0 or more matches of the atom.
  75. :li.An atom followed by ":Red p1='+'." matches a sequence of 1 or more matches of the atom.
  76. :li.An atom followed by ":Red p1='?'." matches a match of the atom, or the null string.
  77. :eUnNumberedListCompact.
  78.  
  79. :p.An atom is&colon.
  80.  
  81. :UnNumberedList.
  82. :li.A regular expression in parentheses (matching a match for the
  83. regular expression), a :DarkGreen p1='range'. (see below).
  84.  
  85. :li.":Red p1='&per.'." which matches any single character.
  86.  
  87. :li.":Red p1='^'." which matches the empty string at the start of a
  88. line.
  89.  
  90. :li.":Red p1='$'." which matches the empty string at the end of a
  91. line.
  92.  
  93. :li.":Red p1='\e'." (a slash followed by a character) which matches
  94. the character.  This is needed so search for "$" etc!
  95.  
  96. :li.A single character with no other significance matches that
  97. character.
  98. :eUnNumberedList.
  99.  
  100. :p.A range is a sequence of characters enclosed in ":Red p1='[]'.".
  101. It normally matches any single character from the sequence.
  102. If the sequence begins with ":Red p1='^'.", it matches any single
  103. character :Bold p1='not'. from the rest of the sequence. If two characters
  104. in the sequence are separated by ":Red p1='-'." then this is shorthand
  105. for the full list of ASCII characters between them (e.g. "[0-9]"
  106. matches any decimal digit). To include a literal "]" in the
  107. sequence, make it the first character (following a
  108. possible "^"). To include a literal "-", make it the first
  109. or last character.
  110.  
  111.  
  112. :BigTitle p1='AMBIGUITY'.
  113.  
  114. :p.If a regular expression could match two different parts of the input string,
  115. it will match the one which begins earliest. If both begin in the same place
  116. but match different lengths, or match the same length in different
  117. ways, life gets messier, as follows&colon.
  118.  
  119.  
  120. :UnNumberedList.
  121. :li.In general, the possibilities in a list of branches are considered in
  122. left-to-right order, the possibilities for "*", "+", and "?" are
  123. considered longest-first, nested constructs are considered from the
  124. outermost in, and concatenated constructs are considered leftmost-first.
  125. The match that will be chosen is the one that uses the earliest
  126. possibility in the first choice that has to be made.
  127. If there is more than one choice, the next will be made in the same manner
  128. (earliest possibility) subject to the decision on the first choice.
  129. And so forth.
  130. :p.For example, "(ab|a)b*c" could match "abc" in one of two ways.
  131. The first choice is between "ab" and "a"; since "ab" is earlier, and does
  132. lead to a successful overall match, it is chosen.
  133. Since the "b" is already spoken for,
  134. the "b*" must match its last possibility (the empty string) since
  135. it must respect the earlier choice.
  136.  
  137. :li.In the particular case where the regular expression does not use
  138. "|" and does not apply "*", "+", or "?" to parenthesized subexpressions,
  139. the net effect is that the longest possible match will be chosen.
  140. So "ab*", presented with "xabbbby", will match "abbbb".
  141. Note that if "ab*" is tried against "xabyabbbz", it
  142. will match "ab" just after "x", due to the begins-earliest rule.
  143. In effect, the decision on where to start the match is the first choice
  144. to be made, hence subsequent choices must respect it even if this leads them
  145. to less-preferred alternatives.
  146. :eUnNumberedList.
  147.  
  148.  
  149.  
  150.  
  151. .*===========================================================================
  152. :Heading p1='Commands' p2='Commands'.
  153. :HeadingLevelDown.
  154. .*===========================================================================
  155. :i1 id=Commands.Commands
  156. :BigTitle p1='Commands'.
  157.  
  158. :p.The following functions are available&colon.
  159.  
  160. :UnNumberedListCompact.
  161. :li.:LinkTo p1='RegExpVersion'.
  162. :li.:LinkTo p1='RegExpCompile'.
  163. :li.:LinkTo p1='RegExpMatch'.
  164. :li.:LinkTo p1='RegExpReplace'.
  165. :eUnNumberedListCompact.
  166.  
  167. :p.Note that you can't trust the return codes from rexx
  168. add/query/drop functions so if you wish to detect (instead of dying)
  169. that the DLL is unavailable you should check my
  170. :LinkToText p1='Example' p2='sample rexx program'. which contains a
  171. subroutine which does this.
  172.  
  173. .dm SampleAndReturnCodeInfo on
  174. :p.Please see my :LinkToText p1='Example' p2='sample rexx program'.
  175. for an example of this call in use.
  176.  
  177. :BigTitle p1='Returns'.
  178. :p.This routine returns ":Red p1='OK'." if the call succeeds
  179. otherwise it returns text which describes the reason for the failure.
  180. .dm off
  181.  
  182.  
  183.  
  184. .*===========================================================================
  185. :Heading p1='RegExpVersion' p2='RegExpVersion'.
  186. .*===========================================================================
  187. :i2 refid=Commands.RegExpVersion
  188. :BigTitle p1='RegExpVersion'.
  189.  
  190. :p.This routine will allow you to determine the version and author
  191. information of the DLL you are using.
  192.  
  193. :p.The routine takes a single parameter as follows&colon.
  194.  
  195. :OrdListCompact.
  196. :li.Name of Variable to update with version Information.
  197. :eOrdListCompact.
  198.  
  199. :p.The information returned (seperated by a single space)&colon.
  200.  
  201. :OrdListCompact.
  202. :li.Version Number such as "98.104".
  203. :li.My Web page URL (where you can get a later version if available).
  204. :li.My email Address.
  205. :li.My Name.
  206. :eOrdListCompact.
  207.  
  208.  
  209. :SampleAndReturnCodeInfo.
  210.  
  211.  
  212. .*===========================================================================
  213. :Heading p1='RegExpCompile' p2='RegExpCompile'.
  214. .*===========================================================================
  215. :i2 refid=Commands.RegExpCompile
  216. :BigTitle p1='RegExpCompile'.
  217.  
  218. :p.To make use of a
  219. :LinkToText p1='RegularExpression' p2='regular expression'.
  220. it must first be compiled.
  221. This routine will either compile a regular expression or release any
  222. memory associated with the last compiled regular expression.
  223.  
  224. :p.The routine takes a single parameter as follows&colon.
  225.  
  226. :OrdListCompact.
  227. :li.The regular expression to be compiled.  There is one exception,
  228. if you pass exactly ":Red p1='ReClose'." then this is taken to be a
  229. close off previous regular expression command.
  230. :eOrdListCompact.
  231.  
  232. :p.The compiled express (plus some other bits) are held in memory
  233. until released.  Rexx programs running in different sessions will not
  234. interfere with each other.  Not sure if there can be any problems
  235. within a session but I suspect not.
  236.  
  237. :SampleAndReturnCodeInfo.
  238.  
  239.  
  240. .*===========================================================================
  241. :Heading p1='RegExpMatch' p2='RegExpMatch'.
  242. .*===========================================================================
  243. :i2 refid=Commands.RegExpMatch
  244. :BigTitle p1='RegExpMatch'.
  245.  
  246. :p.This routine will attempt to find a
  247. :LinkToText p1='RegularExpression' p2='regular expression'.
  248. which was previously
  249. :LinkToText p1='RegExpCompile' p2='compiled'..
  250.  
  251. :p.The routine takes 2 parameters as follows&colon.
  252.  
  253. :OrdListCompact.
  254. :li.The string to be searched.
  255.  
  256. :li.Name of Variable to update with match details.  If the variable
  257. is blank then there was no match otherwise a set of one or more
  258. ":DarkGreen p1='match&rbl.pairs'." is returned.
  259. :eOrdListCompact.
  260.  
  261.  
  262. :BigTitle p1='Match Pairs'.
  263.  
  264. :p.In a set of match pairs the first describes the location of the
  265. overall regular expression while any others (if they exist) describe
  266. the location of any matches for expressions that
  267. occurred between round brackets in the regular expression.
  268.  
  269. :p.Each match pair describes the starting position (1st byte is 1) and
  270. the length of the match.
  271.  
  272. :p.If you used the regular expression "(A)(B)" on the string "ABCDEF"
  273. then "1&rbl.2&rbl.1&rbl.1&rbl.2&rbl.1" would be returned.
  274.  
  275. :SampleAndReturnCodeInfo.
  276.  
  277.  
  278. .*===========================================================================
  279. :Heading p1='RegExpReplace' p2='RegExpReplace'.
  280. .*===========================================================================
  281. :i2 refid=Commands.RegExpReplace
  282. :BigTitle p1='RegExpReplace'.
  283.  
  284. :p.This routine will modify a string you supply based on the
  285. :LinkToText p1='RegExpMatch' p2='match information'. from
  286. a previous
  287. :LinkToText p1='RegularExpression' p2='regular expression'..
  288.  
  289. :p.The routine takes 2 parameters as follows&colon.
  290.  
  291. :OrdListCompact.
  292. :li.The replace specification.
  293.  
  294. :li.Name of Variable which will contain the modified string.
  295. :eOrdListCompact.
  296.  
  297.  
  298. :BigTitle p1='Replace Specification'.
  299.  
  300. :p.The first thing you should understand is that we are not
  301. performing and sort of normal search and replace here, we are taking
  302. a specification and building a new string.  If you wanted to perform
  303. a search and replace type operation you would need to use round
  304. brackets and ensure that the before and after match strings were
  305. described.  Note that doing this can vary the match location of the
  306. string you are trying to match!
  307.  
  308. :p.The replace specification is basically a string where any
  309. occurrance of ":Red p1='&.'." or ":Red p1='\0'." is replaced with the overall matched
  310. characters.  ":Red p1='\1'." to ":Red p1='\9'." are replaced with the
  311. appropriate match information for each round bracketed expression
  312. ('\1' is first one).
  313.  
  314. :p.For example you may wish to replace "SET" with "set" in which case
  315. you could have used the regular expression "SET" to search for the
  316. string with ":LinkTo p1='RegExpMatch'.", however this would not be
  317. useful unless you manually wrote code to do the replacement (not
  318. hard), to use this "replace" routine you would search with something
  319. like "(^.*)SET(.*$)" and then your replace specification could be
  320. "\1set\2".
  321.  
  322.  
  323. :SampleAndReturnCodeInfo.
  324.  
  325.  
  326.  
  327. .*===========================================================================
  328. :HeadingLevelUp.
  329. :Heading p1='Example' p2='Rexx Example'.
  330. .*===========================================================================
  331. :i1 id=Example.Rexx Example
  332. :BigTitle p1='Rexx Example'.
  333.  
  334. $DefineTextChanges `RegExpVersion`    `:LinkTo p1='RegExpVersion'.`
  335. $DefineTextChanges `RegExpCompile`    `:LinkTo p1='RegExpCompile'.`
  336. $DefineTextChanges `RegExpMatch`      `:LinkTo p1='RegExpMatch'.`
  337. $DefineTextChanges `RegExpReplace`    `:LinkTo p1='RegExpReplace'.`
  338. :Example.
  339. .im TestRe.CMD
  340. :eExample.
  341.  
  342. :euserdoc.
  343.  
  344.  
  345.  
  346.