home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / ENTERPRS / CPM / UTILS / S / SEARCH22.LBR / SEARCH22.DZC / SEARCH22.DOC
Text File  |  2000-06-30  |  18KB  |  348 lines
  1.                 SEARCH: A Free-format Text Retrieval System
  2.  
  3.         SEARCH is a file-searching program that allows you to search 
  4. multiple text files for various words or phrases.  Unlike simpler search 
  5. programs, SEARCH can deal with "items" of text larger than single lines, 
  6. and can search for several words or phrases at a time.  SEARCH  can 
  7. directly search files within libraries, as well as SQUEEZED and CRUNCHED 
  8. files.  It is a relative of the ESEARCH  utility available on some RCP/M 
  9. systems (it began as a somewhat-stripped down version of the commercial 
  10. ESEARCH; user-requested enhancements have since resulted in its taking up 
  11. at least as much code as ESEARCH).
  12.  
  13.                               THE FINE PRINT
  14.  
  15.         Copyright (c) 1987,1988 by Eric Bohlman.  SEARCH and its 
  16. documentation may be  freely copied and used for non-commercial purposes.  
  17. Commercial use or distribution for profit requires permission of the 
  18. author.  Address any inquiries to:
  19.  
  20.     Eric Bohlman
  21.     1921 Highland Ave.
  22.     Wilmette, IL 60091
  23.     (312)251-5787
  24.  
  25.         I can also be reached at the Advocate/NOWAR RCP/M at 312-939-3300 
  26. or the COPH-2 OPUS at 312-286-0608 (both 24 hrs, 300/1200/2400).
  27.  
  28.         When distributing SEARCH, please be sure to include the following 
  29. files (preferably in crunched form):
  30.  
  31.     SEARCHxx.DOC     This file
  32.     SEARCHxx.QRF     Quick reference guide
  33.     SEARCHxx.HIS     History
  34.     SEARCHxx.COM     The actual program
  35.  
  36.                             SYSTEM REQUIREMENTS
  37.  
  38.         SEARCH requires CP/M 2.2 or higher and at least 43K of TPA to use 
  39. all features.  More memory speeds up searches by eliminating the need to 
  40. buffer text items on disk.
  41.  
  42.                                  OPERATION
  43.  
  44.         There are two ways to invoke SEARCH.  The first is to simply type 
  45. SEARCH.  In this case you will be prompted repeatedly for the files you 
  46. wish to search after you have told it what to search for.  The second is to 
  47. specify the files, search string(s) and optional modifier switches on the 
  48. command line (see below).  If you use the prompting method, the first thing 
  49. SEARCH will do is ask you for what to search for.  You may enter a word or 
  50. phrase.  After you enter it, you will be asked "AND?".  You may enter 
  51. another word or phrase at this point; if so, an item will be retrieved only 
  52. if it contains both words or phrases.  You can AND up to 16 words or 
  53. phrases.  When you're done ANDing, press return in response to the AND 
  54. prompt.  You will then be asked "OR?".  At this point you can enter another 
  55. word or phrase, possibly including more AND's.  An item will match if 
  56. either of the ORed words or phrases is present.
  57.  
  58.                                   EXAMPLE
  59.  
  60.     Search for? TEXT
  61.     AND? RETRIEVAL
  62.     AND?
  63.     OR? SEARCH
  64.     AND?
  65.     OR?
  66.  
  67. Would retrieve all text items containing both "text" and "retrieval" as 
  68. well as those containing "SEARCH" (case is not significant in search 
  69. terms).  Answering the OR? prompt with a return completes specification of 
  70. what to search for.
  71.  
  72.         You can also tell SEARCH to look for items that DO NOT contain a 
  73. given word.  To do this, just type "!" in front of a word at any of the 
  74. prompts.
  75.  
  76.                                   EXAMPLE
  77.  
  78.     Search for? TEXT
  79.     And? !GRAPHICS
  80.  
  81. Would retrieve those items that contain "text" and also don't contain 
  82. "graphics."  Note that "!" has a special meaning only when it appears at 
  83. the beginning of a word or phrase; otherwise it is used literally.  If you 
  84. need to search for a word that begins with a "!" precede it with a 
  85. backslash.
  86.  
  87.         When searching, SEARCH treats any number of spaces as equivalent to 
  88. one space, and treats CR/LF pairs as a single space, so a multi-word phrase 
  89. will be matched even if it falls across a line boundary in text with a left 
  90. margin.  If a line ends with a dash, SEARCH will ignore the dash and the 
  91. CR/LF, so that hyphenated words will be matched properly.
  92.  
  93.         In addition, you can use the caret "^" character to control left- 
  94. and right-embedding of words.  A caret at the beginning or end of a word 
  95. (or phrase) means that the word will not be matched if it is embedded in 
  96. another word.  For example, "ion" would match "ion," "ionized," "emotion" 
  97. and "emotionally." "^ion" would match only words beginning with "ion," 
  98. "ion^" would match only words ending with "ion" and "^ion^" would match 
  99. "ion" exclusively.
  100.  
  101.         At this point SEARCH will prompt you for a file to search.  If you 
  102. just enter return, you will exit SEARCH (you come back to this prompt when 
  103. you are done searching a file).  You may enter a file specification, which 
  104. may include a ZCPR-style drive/user specification or named directory 
  105. reference.  You may use wildcards in your file name.  You can also specify 
  106. a library member by following the filename with a space and a second 
  107. filename (obviously without the duspec).  The library member name may 
  108. contain wildcards, and you can mix wildcards in both filenames.  You can't 
  109. use wildcard user numbers, though.
  110.  
  111.                                  EXAMPLES
  112.  
  113.     myfile.doc
  114.     b12:myfile.doc
  115.     doc:myfile.doc         (if you have ZCPR3)
  116.     a2:*.doc
  117.     mylbr list.doc
  118.     mylbr.lbr list.doc
  119.     mylbr.txt list.doc (treated as mylbr.lbr list.doc)
  120.     mylbr *.doc
  121.     *.lbr *.doc
  122.     *.* *.doc (treated as *.lbr *.doc)
  123.  
  124.         Next you will be asked what separator to use for the file.  A 
  125. separator is a line that breaks the file into items. The first item in the 
  126. file begins with the first line and ends with the first separator line; the 
  127. next item starts after the separator and ends with the next separator or 
  128. end-of-file, whichever comes first.  If the separator is not present in the 
  129. file, the entire file is treated as one item.  A line must match the 
  130. separator literally except for case and trailing spaces; if the separator 
  131. were "----" only lines consisting ONLY of four dashes would be treated as 
  132. separators.  Just entering return at the prompt means use a blank line for 
  133. the separator; the special value "l" (or anything beginning with "l") 
  134. (either case is ok) means to treat each line as one item.  As you can see, 
  135. an item has to be composed of lines (text followed by CRLF); for example, a 
  136. period as separator implies that items are separated by lines containing 
  137. just a period rather than implying that each sentence of text is an item.
  138.  
  139.         Note that the comparison for the separator is case-sensitive.  Of 
  140. course, this matters only if the separator contains letters.  However, 
  141. either an "l" or "L" indicates line-by-line matching.
  142.  
  143.         Now SEARCH will open each file that matches your filename 
  144. specification.  If one of the files can't be opened for some reason, it 
  145. will say so.  SEARCH reads the first two characters of each file (or 
  146. library member) to determine whether it is normal, SQUEEZED or CRUNCHED; it 
  147. does not require a Q or Z in the extension.  If SEARCH encounters a 
  148. matching item, the filename will be displayed (for the first item only) and 
  149. the item will be displayed.  When the end of the file is reached, SEARCH 
  150. will go on to the next file if any.  When there are no more files, SEARCH 
  151. will go back to the FILE?  prompt, at which point you may specify more 
  152. files to be searched (for the same words or phrases), or you may exit.  (by 
  153. pressing return at the prompt).
  154.  
  155.         While a file is being searched, you can abort back to CP/M with 
  156. ctrl-c.  If an item is being displayed, you can use ctrl-x to stop 
  157. displaying that item and start searching for the next item in the file.  If 
  158. nothing is being displayed, i.e. SEARCH is searching for the next item, 
  159. ctrl-x will stop searching the current file and start searching the next 
  160. one.  You can use ctrl-s and ctrl-q to pause and resume the display of 
  161. items.
  162.  
  163.                  SPECIFYING ARGUMENTS ON THE COMMAND LINE
  164.  
  165.         The second way to use SEARCH is to specify your arguments on the 
  166. command line.  The syntax for this is:
  167.     SEARCH <FILESPEC> <SEPARATOR> -<SWITCHES> =<SEARCH STRINGS>
  168. The switches and the search strings can appear in any position on the 
  169. command line because they begin with distinguishing characters.  The first 
  170. argument that doesn't begin with either special character is the filespec, 
  171. and the second one is the separator.  Note that arguments are normally 
  172. separated by spaces; if an argument contains a space (such as a library 
  173. member filespec), it must be enclosed in quotes (or see "escape sequences" 
  174. below).  Note also that the proper way to specify a blank line as a 
  175. separator is "".  If you so desire, you can omit any of the filespec, 
  176. separator, and search strings; if so you will be prompted for the missing 
  177. items.  Remember that if you enter the separator on the command line and it 
  178. contains any letters, they will be entered in upper case because of the way 
  179. CP/M processes command lines.  If you need to enter lower case characters 
  180. in a separator, use an escape sequence or omit it from the command line and 
  181. enter it at the prompt.  You don't need to worry about case in search 
  182. strings; the matching there is case-insensitive.
  183.  
  184.                              ESCAPE SEQUENCES
  185.  
  186.         To avoid having to put quotes around separators or search strings 
  187. that contain spaces, you can use "\S" to represent a space.  You can avoid 
  188. quoting library specs by using a '/' rather than a space between the file 
  189. name and member name.  In addition, there are three special escape 
  190. sequences that can be used in separators:
  191.  
  192.     \L  Treat the following characters as lower-case.
  193.     \U  Treat the following characters as upper-case.
  194.     \nn Insert nn repetitions of the following character, e.g. \8- for 
  195.         eight dashes.
  196.                                  SWITCHES
  197.  
  198.         You can change the behavior of SEARCH by using command-line 
  199. switches.  All switches consist of a - followed by a letter.  You can also 
  200. specify several switches by using a - followed by several letters.  The 
  201. following switches can be used:
  202.  
  203.     -B  Don't display matching items until one containing a specified 
  204.         string is encountered.  The string must immediately (no spaces) 
  205.         follow the -B.  The match is case-insensitive.  This is useful 
  206.         if you're searching a long file in two or more sessions and don't 
  207.         want to wade through items that you saw the first time.
  208.  
  209.     -F  Don't display the names of files with matches.  This is useful if 
  210.         you are redirecting output into a file (see below).
  211.  
  212.     -I  Specify inspect mode (see below)
  213.  
  214.     -K  Before each displayed item, show the query alternative (OR-group) 
  215.         that matched.  If more than one alternative matched, only the first 
  216.         one will be shown.
  217.  
  218.     -M  Pause output every 23 lines.
  219.  
  220.     -N  When displaying items, show the line number within the file on each 
  221.         line of each item.
  222.  
  223.     -S  Show filenames only.  If this option is selected, SEARCH will stop 
  224.         searching each file as soon as it detects a match.  You would use 
  225.         this if you wanted only a list of files that contained a word or 
  226.         phrase.
  227.  
  228.     -U  Show filenames for unsuccesful searches.  If you select this, 
  229.         SEARCH will display the filename of each file searched.  If no 
  230.         matches can be found, a message to that effect will be displayed
  231.         next to the filename.  Note that the F option overrides this.
  232.  
  233.                               SEARCH STRINGS
  234.  
  235.         When you enter search strings on the command line, you separate 
  236. them with & for AND and | for OR.  Remember that if any of your search 
  237. strings contains a space, you must enclose the entire search-string 
  238. argument, starting with the =, in quotes (or use "\S" in place of spaces).  
  239. Also note that you should NOT type spaces before or after the & or | 
  240. symbols unless you really want to match a literal space before or after a 
  241. word.
  242.  
  243.         If you need to include a literal '&' or '|' in a search string, 
  244. precede it with a backslash ('\').  If you need a literal backslash, use 
  245. '\\'.  This is known as an escape character.
  246.  
  247.         & takes precedence over |.  Search expressions cannot be 
  248. parenthesized.  If you need the effect of "this&(that|those)" you have to 
  249. write it out as "this&that|this&those."
  250.  
  251.                                  EXAMPLES
  252.  
  253.     SEARCH B3:MYFILE L -MF =CP/M&EDITOR|MS-DOS&COMPILER
  254.  
  255.     (Note that if the search string had been written as
  256.     =CP/M & EDITOR | MS-DOS & COMPILER
  257.     two things would be wrong.  First, the space after CP/M would terminate 
  258.     the argument (this is a property of the C compiler with which SEARCH 
  259.     was written).  Second, even if the argument were enclosed in quotes, 
  260.     the spaces would be treated literally, with the result that, for 
  261.     example, EDITOR would be matched ONLY if it were both preceded and 
  262.     followed by spaces, e.g. "EDITOR." wouldn't match.
  263.  
  264.     SEARCH "B15:MYLBR *.TXT" "" "=TEXT SEARCHING&COMPUTER PROGRAMS"
  265. (or with escapes)
  266.     SEARCH B15:MYLBR/*.TXT "" =TEXT\SSEARCHING&COMPUTER\SPROGRAMS
  267.  
  268.                              OUTPUT REDIRECTION
  269.  
  270.         You can redirect the output of SEARCH into a file by including on 
  271. the command line an argument of the form ">file." For example,
  272.     SEARCH >LOG.TXT
  273. would send the "Searching..." messages and the text of the matched items 
  274. (but not prompts to you) into a file called LOG.TXT.
  275.     SEARCH >LST:
  276. would send the output to the printer.  User specs are not allowed in the 
  277. redirection argument (which is implemented by the C compiler used to 
  278. compile SEARCH; the program itself thinks it's writing to the screen).  The 
  279. output file will be silently overwritten if it already exists.
  280.  
  281.                               "INSPECT" MODE
  282.  
  283.         SEARCH has a special option which allows you to inspect each 
  284. retrieved item and decide whether or not to append it to the end of a text 
  285. file.  For example, you could search the .FOR file of an RCPM system, and 
  286. make a list of those programs that you don't already have but would like to 
  287. get.
  288.  
  289.         To activate inspect mode, you need to use the switch "-I" 
  290. immediately (no spaces) followed by a file name.  Then as soon as an item 
  291. has been displayed, you will be prompted with "Append (y/N)?"  If you 
  292. answer yes, the item will be appended to the end of the file that you 
  293. named.
  294.  
  295.                                   EXAMPLE
  296.  
  297.     SEARCH B1:MYRCPM.FOR ---- -IIWANT.LST =CP/M&!MS-DOS
  298.  
  299.                               USAGE REMINDER
  300.  
  301.         Typing "SEARCH ?" or "SEARCH //" will give you a quick summary of 
  302. SEARCH's command-line syntax.
  303.  
  304.                                 PATCH AREA
  305.  
  306.         SEARCH includes an area which you can alter with a program like 
  307. PATCH or DU.  The locations there allow you to change certain defaults:
  308.  
  309. 010BH:  Filename display.  If this is nonzero, it reverses the F option, 
  310.         i.e. filenames will not be displayed unless the F option is used.
  311. 010CH:  "More" option.  A nonzero here reverses the M option.
  312. 010DH:  Numbering option.  A nonzero here reverses the N option.
  313. 010EH:  Skip option.  A nonzero here reverses the S option.
  314. 010FH:  Unsuccessful file display option.  A nonzero here reverses the U
  315.         option.
  316. 0110H:  Character that represents AND in search strings.  Default is '&'.
  317. 0111H:  Character that represents OR in search strings.  Default is '|'.
  318. 0112H:  Character that introduces search strings.  Default is '='.
  319. 0113H:  Character that introduces switches.  Default is '-'.
  320. 0114H:  Escape character for search strings.  Default is '\'.
  321. 0115H:  Character that represents NOT in search strings.  Default is '!'.
  322. 0116H:    What to do if no separator is given on the command line.  0=assume 
  323.         blank line, 1=assume line-by-line, anything else=ask.  Default is 
  324.     ask.
  325. 0117H:    Library separator character.  Default is '/'.
  326. 0118H:    Matched query display.  A nonzero here reverses the K option.
  327.  
  328.                            TEMPORARY FILE USAGE
  329.  
  330.         SEARCH may need to create a temporary file for buffering purposes.  
  331. SEARCH maintains an item text buffer which is either 8K or the largest 
  332. amount of memory it can find less than 8K (this can be VERY small in 
  333. systems with small TPA).  If an item won't fit, it "spills over" to the 
  334. temporary disk file, which is called A15:ESEARCH.TMP.  Search takes care of 
  335. deleting the temporary file when it no longer needs it.  All this detail 
  336. has very little relevance to the user of SEARCH, except that with all the 
  337. publicity about "viruses" going around, it's a good idea to point out why a 
  338. program does disk writes when you wouldn't think it would have to.
  339.  
  340.                                    NOTE
  341.  
  342.         The LZW uncrunching algorithm used in Version 2.2 cuts some corners 
  343. in order to achieve increased speed.  I would appreciate being informed if 
  344. this results in problems, i.e. crashes or mangled text when using certain 
  345. crunched files.  Technically, the change involves allocating a fixed area 
  346. for expanding string codes; the algorithm may fail if a particular LZW code 
  347. represents a string (after run-length encoding) of more than 256 bytes 
  348. (somewhat unlikely in a text file, but...).