home *** CD-ROM | disk | FTP | other *** search
/ PDA Software Library / pdasoftwarelib.iso / HP95_100 / UTILITY / VR100 / TREX.DOC < prev    next >
Encoding:
Text File  |  1993-12-28  |  5.9 KB  |  172 lines
  1.  
  2. Trex documentation and tutorial
  3. ------------------------------------------------------------
  4.  
  5.  
  6. Introduction 
  7. ------------------------------------------------------------
  8.  
  9. Trex (pronounced T-rex, just like the film star) stands for
  10. Tiny REgular eXpression filter. It can be useful on its
  11. own, but is really meant to give you the opportunity of
  12. playing with regular expressions if you're not yet familiar
  13. with them. Trex is a VR companion program.  You may freely
  14. distribute it along with the contents of the VR archive,
  15. and you may use it as long as you wish without ever
  16. registering VR. You may _not_ distribute TREX and this
  17. documentation file without the rest of the files in the VR
  18. distribution archive.
  19.  
  20.  
  21. What does it do ?
  22. ------------------------------------------------------------
  23.  
  24. Trex checks text lines that it gets on input, (typically
  25. via redirection, from a file) and outputs only those parts
  26. that match certain patterns that you specify. It can be
  27. used to perform searches, or to filter out certain elements
  28. from a text.
  29.  
  30.  
  31. Examples and tutorial
  32. ------------------------------------------------------------
  33.  
  34. Trex must be run from the DOS commandline prompt. The normal
  35. way for it to get input is via the DOS redirection
  36. facility, using the '<' character.  Lets have an example.
  37.  
  38. [NOTE: If you have an HP100LX, you can use MEMO or FILER to
  39. view this file (TREX.DOC), and start a DOS shell by hitting
  40. <Ctrl>-<123>.  In this way, you can switch back and fro
  41. between this reading text and actually trying Trex out.]
  42.  
  43. Say you want to search for the string 'you' in this file.
  44. You would issue the following command: 
  45.  
  46.         trex "you" <trex.doc
  47.  
  48. You will notice that Trex outputs a number of 'you' lines.
  49. Now that's not particularly useful - you probably want to
  50. see some context ! Try this:
  51.  
  52.         trex ".*you.*" <trex.doc
  53.  
  54. What's the difference ? Remember, Trex always outputs
  55. exactly what 'matched' your description. If you instructed
  56. it to search for 'you', and it found a line containing this
  57. pattern, it will just output the match. The second line
  58. instructs Trex to match any characters before and after the
  59. string 'you', too. (And to output them consequently)
  60.  
  61. How does it work ? The '.' character is special to Trex.
  62. It matches any character. '*' has special meaning too: it
  63. indicates: match zero or more of the previous 'pattern'.
  64. In this case the 'previous pattern' was the '.', saying
  65. 'any character is OK'. So, '.*' means: 'whatever - I don't
  66. care'. '.*you.*' means: the start and end I don't care, but
  67. there should be 'you' in it, and the whole stuff printed.
  68.  
  69.  
  70. Before we continue with our tutorial, here's an overview of
  71. the characters that have special meaning for Trex:
  72.  
  73.  
  74. Trex special characters
  75. ------------------------------------------------------------
  76.  
  77.    '.'          : any character.
  78.    '*'          : zero or more occurances
  79.    '+'          : one or more occurances
  80.    '?'          : zero or one occurance
  81.    '|'          : 'or', separates alternatives
  82.    '[' and ']'  : used to define ranges
  83.    '(' and ')'  : used for grouping
  84.    '^'          : beginning of line
  85.    '$'          : end of line
  86.    '\'          : next character 'as-is'
  87.    
  88.  
  89. Don't worry if this list looks incomprehensible at first - 
  90. we'll look at them in turn, with more examples. Lets do
  91. some experimenting: try to figure out what this command
  92. does before actually trying it:
  93.  
  94.         trex "^ +.trex.*" <trex.doc
  95.     
  96. That was harder. This matches (and prints) every line that
  97. starts with at least one space, then has the string 'trex'.
  98. It filters out the trex examples we saw up to now. Let's
  99. analyze how it works. The '^' ensures that the beginning of
  100. the line is matched. The '+' following the space character,
  101. indicates that at least one space (possibly more) has to be
  102. present. The '.*' behind 'trex' is not required to _find_
  103. the line, but to output it entirely. (You know that trick by
  104. now)
  105.  
  106. Can you find out what Trex command would print out all lines
  107. ending in ':' in this file ? Here's the solution:
  108.  
  109.         trex ".*:$" <trex.doc
  110.  
  111. Lets have a look at ranges now. Suppose you want to find
  112. numerical values in a file. You could use this:
  113.  
  114.         trex "[0123456789]+" <trex.doc
  115.  
  116. The '[' and ']' simply enclose a list of valid characters.
  117. (Digits, in this case). The trailing '+' indicates that 
  118. Trex should try to match as many of them as possible, but at
  119. least one. 
  120.  
  121. There's an easier way, to do this. You can use a dash in a 
  122. range to specify 'all characters in between'. Like this:
  123.  
  124.         trex "[0-9]+" <trex.doc
  125.  
  126. OK, now suppose we'd like to locate values with a preceding 
  127. dollars sign, like:
  128.  
  129.   $1000 or
  130.   $99.95 etc.
  131.  
  132. Two problems. First, we can't use the '$' or '.' sign - both
  133. are special characters, and in this case we don't want them to
  134. have special action. The '\' sign is the solution - it instructs
  135. Trex to ignore the special meaning - if any - of the following
  136. character. So to match the $1000 line above, you can use:
  137.  
  138.         trex "\$[0-9]+" <trex.doc
  139.  
  140. Ok, so far so good, but what about the $99.95 ? Only the
  141. '$99' part got output - not what we wanted ! We could
  142. change our line to:
  143.  
  144.         trex "\$[0-9]+\.[0-9]+" <trex.doc
  145.  
  146. but now, _only_ '$99.95' will be matched. Not what we want
  147. either. Here's a possible solution:
  148.  
  149.         trex "\$[0-9]+(\.[0-9]+)?" <trex.doc
  150.  
  151. This is the first time that we see both the grouping
  152. parentheses and the '?' character. The question mark says
  153. 'zero or one occurences of the previous patterns', and the
  154. parentheses take care that the 'previous pattern' is what
  155. we want it to be. 
  156.  
  157. We didn't use the '|' character yet. It is used to separate
  158. alternatives. To search for HP95 or HP100, for example, you
  159. could use:
  160.  
  161.    HP95|HP100
  162.  
  163.       or
  164.  
  165.    HP(95|100)
  166.  
  167. This terminates our little Trex tutorial - the best way
  168. to learn more about regular expressions is to experiment
  169. with them using TREX - good luck !
  170.  
  171.  
  172.