home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine 1995 / ARCHIVE95.iso / discs / shareware / share_46 / fre / !Help < prev    next >
Text File  |  1992-05-19  |  5KB  |  179 lines
  1. Documentation on FRe v0.20 by Cy Booker 19-May-1992
  2.  
  3. Program and documentation are Copyright ⌐ Cy Booker, 1992. 
  4.  
  5.     This program is distributed in the hope that it will be useful,
  6.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  7.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
  8.  
  9. Permission is granted to you to (ab)use this program to your hearts
  10. contents provided:
  11.  
  12.  1) No part of this software is used in/to develop a program for sale
  13.     without written permission from me
  14.  
  15.  2) All files be included in any distribution
  16.         FRe        - the code
  17.         re         - documentation on regular expressions
  18.         re_formal  - formal definition of a regular expression
  19.         !Help      - this file
  20.         CAssembler - support module
  21.         _fre       - example shell Obey file
  22.         
  23.  
  24. What is FRe ?
  25. =============
  26.  
  27. It stands for "Find Regular Expression(s)", so given a regular
  28. expression (RE) and a list of files, it finds the files that contain
  29. that RE. 
  30.  
  31.  
  32. What's the point ?
  33. ==================
  34.  
  35. OK, get your imagination into overdrive: you, yes YOU, are developing /
  36. maintaining a fantastic program - the source code is split up into 20+
  37. files over X directories.  You haven't attacked this program for a
  38. while.  You see a reference to a variable "foo" and you want to find out
  39. what other parts of the program refer to this variable.  How do you do
  40. it? You have to load in each file separately to your favourite source
  41. editor (or set up a macro) and do a search...  what a drag.  This
  42. program automates the searching. 
  43.  
  44.  
  45. Syntax
  46. ======
  47.  
  48. FRe [-Re] <regex> [[-Files] <files>] [[-Verbosity] <n>] [Options]
  49.  
  50. Options:
  51. Verbosity <n> 0-3, 0=> no output, 3=>list all lines (2)
  52. All           parse all files as Text (OFF)
  53. Basic         pre-process Basic tokenised files (OFF)
  54. Help          display this information
  55. HourGlass <n> 0 off, 1 on, 2 percentage each file (1)
  56. ICase         ignore case of all letters during match (OFF)
  57. ISpace        translate all whitespaces to " " (OFF)
  58. Not           success is a line NOT matching the <regex> (OFF)
  59. Recurse       go into sub-directories (OFF)
  60. Scan          show files as being parsed (OFF)
  61. Via <files>   the name of file(s) containing more file names to check
  62.  
  63. <files> is a comma separated list of wildcarded file names
  64. Note that by default only parse Text and Basic files
  65.  
  66. Also note that when scanning a Basic file, the character "`" is
  67. automatically included as a symbol character.
  68.  
  69.  
  70. Via files
  71. =========
  72.  
  73. These are just plain Text files where each line is a <files> (a comma
  74. separated list of wildcarded filenames).  Comments are lines starting
  75. with "-", "#", or ";".
  76.  
  77. For example:-
  78.  
  79. # This is a via line for the wimp$app
  80. #
  81. - Source
  82. <Wimp$App>.c.*
  83. <Wimp$App>.h.*
  84. - Docs
  85. <Wimp$App>.docs, <Wimp$App>.doc.*, <Wimp$App>.!Help
  86. - System
  87. <Wimp$App>.!Run, <Wimp$App>.!Run
  88. #
  89. # End of file
  90.         
  91.  
  92. Examples
  93. ========
  94.  
  95. Find the sequence "printf" in all text files in the current directory
  96.  
  97.   FRe printf *
  98.  
  99.  
  100. Display all lines that contain the word "the", capitalised or not in
  101. the two files $.!Help and foo.bar
  102.  
  103.   FRe \<(T|t)he\> $.!Help,foo.bar 3
  104. or,
  105.   FRe -Re \<(T|t)he\> -Files "$.!Help, foo.bar" -Verbosity 3
  106.  
  107.  
  108. List files that contain at least one matching re
  109.  
  110.   FRe "Frank Zappa" -Verbosity 1 -Via filelist -Scan
  111.  
  112. The -Scan shows each file as it is being processed, which is handy for
  113. interactive work.  However, if you are re-directing the output to a
  114. file, it is not recommended!
  115.  
  116.  
  117. Find references to the procedure "_hello" in a basic file "world".
  118.  
  119.   FRe \½PROC_hello\╗ world -Basic
  120. or,
  121.   FRe \xF2_hello\╗ world
  122.  
  123. The former works because each tokenised basic line gets expanded
  124. before matching starts.  The later works because the token for PROC is
  125. 252, or &F2.
  126.  
  127.  
  128. Bad
  129. ===
  130.  
  131. o  Well, since it is an application you can't run it from another
  132.    application that doesnt spawn child processes (ie basic).
  133. o  It requires the CAssembler module to be resident at time of
  134.    execution.
  135. o  Using the -Basic switch makes basic file parsing very slow.
  136. o  The expansion of Basic tokens only works for BasicV v1.04 English.
  137.  
  138.  
  139. Good
  140. ====
  141.  
  142. o  It handles Basic files properly
  143. o  Can expand tokenised basic files
  144. o  It is fast
  145. o  Handles wildcard filenames
  146. o  Handles lists of filenames
  147. o  Recurses into sub-directories
  148. o  Takes up very little application space
  149. o  The "symbol" matching in the RE's
  150. o  It returns with the number of matching files
  151.  
  152.  
  153. Updates
  154. =======
  155. 23-Apr-1992  First release
  156. 19-May-1992  Second release, uses less memory at run-time: Improved Obey file
  157.  
  158.  
  159. Credits
  160. =======
  161.  
  162. The regular expression parsing was based on (somewhat inconsistent) code
  163. that is Copyright the Free Software Foundation, 1985.  And so if anyone
  164. wants the source code to my version / the original then send us a
  165. disc... 
  166.  
  167.  
  168. Author
  169. ======
  170.  
  171. Cy Booker
  172. 86 Church View
  173. Main Road
  174. Crockenhill
  175. Swanley
  176. Kent
  177. BR8 8JW
  178. United Kingdom
  179.