home *** CD-ROM | disk | FTP | other *** search
/ CD Shareware Magazine 1997 January / CD_shareware_1-97.iso / DOS / UTL-DSK / BFIND610.ZIP / BFIND.DOC < prev    next >
Encoding:
Text File  |  1996-10-18  |  14.2 KB  |  341 lines
  1. BFIND.DOC                            1                         Revised: 10-18-96
  2.  
  3. The BFIND.EXE program adds Boolean logic to DOS's FIND command.  In  most  ways,
  4. it's identical to the FIND command except:
  5.  
  6.   * Adds AND, OR, NOT, and XOR options to searches (finding all lines with
  7.     "Apples" or "Bananas", for example).
  8.   * Allows you to specify the starting column of the desired string.
  9.   * Adds a pause (/P) option to have the output pause every 24 lines.
  10.   * Avoids need to include the search string in quotation marks so you can
  11.     use the program more easily in batch commands.
  12.   * The input file specification can include standard DOS wildcards or an
  13.     external file (@listfile) containing the files to be processed, e.g:
  14.         BFIND /I "SOUND" *.DOC > TEMP.X
  15.   * Allows you to skip the by-file heading information ("----- filename").
  16.   * Can avoid showing file name header if no hits in the file (/-EMPTY option).
  17.   * Handles DOS text files (lines end with CR/LF), Mac text files (lines end
  18.     with CR), or Unix text files (lines end with LF).
  19.   * Should be able to handle input files with line lengths of 5000 characters
  20.     or more.  Should skip the remainder, allowing you to use the wildcards
  21.     more easily.
  22.   * Allows you to remove non-text characters from the output or even specify
  23.     your own character-translation file for them.
  24.  
  25. The only FIND feature that BFIND does *not* support is the  ability  to  specify
  26. multilple single input  files  without  using  wildcards  ("FIND  ...  BRUCE.TXT
  27. BRUCE.DOC" works--"BFIND ... BRUCE.TXT BRUCE.DOC" does not).  In  addition,  you
  28. cannot do piping into BFIND (e.g. DIR | BFIND ...).
  29.  
  30. The DOS FIND command allows you to find lines in a text  file  which  contain  a
  31. given string.  You can also have the program tell you how  many  lines  met  the
  32. search criteria without actually viewing them which is an ideal way to find  out
  33. how many times a given string appears in your file.  You can even  use  FIND  to
  34. tell you how many total lines are in a given file just by  requesting  a  string
  35. that you know will never appear in your file  like  "#X$S$"  and  using  the  /C
  36. (count) parameter.
  37.  
  38. BFIND adds to these capabilities.  It gives you the power of AND, OR,  NOT,  and
  39. XOR, allowing you to find any line, for example, that contains both "Apples" and
  40. "Oranges" or to present any lines that contain either "Bananas" and "Pears".  In
  41. addition, you can do column-specific searching, finding only those  lines,  say,
  42. that contain "PRINT" beginning in column 10.
  43.  
  44. BFIND allows you to specify wildcards for the input file.  You can also put  the
  45. list of file names to process in a text file and tell BFIND to process the files
  46. listed therein.
  47.  
  48.  
  49. Specifying parameters:
  50.  
  51. Parameters for this program can be set in the following ways.  The last  setting
  52. encountered always wins:
  53.   - Read from an *.INI file (see BRUCEINI.DOC file),
  54.   - Through the use of an environmental variable (SET BFIND=whatever), or
  55.   - From the command line (see "Syntax" below)
  56.  
  57.  
  58.  
  59. BFIND.DOC                            2                         Revised: 10-18-96
  60.  
  61. Syntax:
  62.  
  63.     BFIND [ /V | /-V ] [ /C | /-C ] [ /N | /-N ] [ /I | /-I ] [ /P | /-P ]
  64.       [ /-HEADER ] [ /-EMPTY ] [ /FILTER | /FILTER=filename ]
  65.       [ /LINES { line1-line2 | line1 linect } ... ]
  66.       [ /MONO ] [ /Iinitfile | /INULL ] [ /W | /W0 | /-W ] [ /? ] [ /?&H ]
  67.       { search } { filespec | @listfile } [ >filename ]
  68.  
  69. where:
  70.  
  71. "/V" says to find those items that do NOT match  the  specification.   Initially
  72. defaults to "/-V".
  73.  
  74. "/-V" says to find those  items  that  DO  match  the  specification.   This  is
  75. initially the default.
  76.  
  77. "/C" says to show the count of the items found (no individual lines).  Initially
  78. defaults to "/-C".  One use for the "/C" parameter is to  count  the  number  of
  79. lines in a file; search for all lines that  do  *not*  (/V)  contain  a  totally
  80. improbable string and then tally them.  E.g.
  81.  
  82.         BFIND /V /C "&^&^&#" MYFILE.TXT
  83.  
  84. "/-C" says to skip counting the items.  This is initially the default.
  85.  
  86. "/N" says to number the output lines.  Initially defaults to "/-N".
  87.  
  88. "/-N" says to skip numbering the output lines.  This is initially the default.
  89.  
  90. "/I" says to make it a case-insensitive search.  So a search  for  "Apple"  will
  91. find "APPLE", "apple", ApPle", etc.
  92.  
  93. "/-I" is the opposite of /I and is typically the default.  A search for  "Apple"
  94. will not find "APPLE".
  95.  
  96. "/P" says to have the display pause  every  24  lines.   Initially  defaults  to
  97. "/-P".
  98.  
  99. "/-P" says to not bother pausing the output  display.   This  is  initially  the
  100. default.
  101.  
  102. "/-HEADER" says to skip the normal -----infile output line that  appears  before
  103. the results of the output.
  104.  
  105. "/HEADER" says to include the headers.  This  is  initially  the  default.   The
  106. header lines look like this:
  107.  
  108.      --------- C:\VBDOS\BFIND.BAS
  109.  
  110. "/EMPTY" says that the -----infile header information is to be shown even if the
  111. file doesn't have any hits in it.  This is initially the default.
  112.  
  113. "/-EMPTY" says to only show the -----infile header information if the  file  has
  114. hits.  Initially defaults to "/EMPTY".
  115.  
  116.  
  117. BFIND.DOC                            3                         Revised: 10-18-96
  118.  
  119. "/FILTER" says to remove all nonprintable characters from the output.  Initially
  120. defaults to "/-FILTER".
  121.  
  122. "/-FILTER" says to not bother removing  the  nonprintable  characters  from  the
  123. output.  This is initially the default.
  124.  
  125. "/FILTER=filename" specifies that a filter is to be  applied  and  all  non-same
  126. character replacements are in the file "filename".   This  feature  is  of  very
  127. limited usefulness in the  BFIND  program  unless  you're  reading  native  word
  128. processing files.  If this excites you for some reason, get the ZIP  READymm.ZIP
  129. and read the documentation for the READY program.  The feature works identically
  130. in both programs.
  131.  
  132. "/LINES line1-line2" says to restrict the search to lines between  line  numbers
  133. line1 and line2 inclusive.  You can have multiple line  requests  in  any  order
  134. such as "/LINES 1-10 90-100 30-50".  The  routine  skips  all  lines  after  the
  135. largest line number is encountered.  Defaults to "/LINES 1-9999999".
  136.  
  137. "/LINES line1 linect" says to restrict the search to lines beginning with  line1
  138. and continuing for a total of linect lines.  So "/LINES 10 20" is  actually  the
  139. same as "/LINES 10-29".
  140.  
  141. "/MONO" (or "/-COLOR") does  not  try  to  override  screen  colors.   Initially
  142. defaults to "/COLOR".
  143.  
  144. "/COLOR" (or "/-MONO") allows screen colors to be overridden.  This is initially
  145. the default.
  146.  
  147. "/Iinitfile" says to read an initialization file with the file name  "initfile".
  148. The file specification *must* contain a period.  Initfiles are described in  the
  149. BRUCEINI.DOC file.  Initially defaults to "/IBFIND.INI".
  150.  
  151. "/INULL" says to skip loading the initialization file.
  152.  
  153. "/W" says to pause with a "Press any key to continue" message after the  program
  154. finishes if any hits were  found.   Note  that  this  parameter  is  ignored  if
  155. redirection out is being used.
  156.  
  157. "/W0" says to pause afterward whether any hits  were  found  or  not.   This  is
  158. initially the default if the program is  run  under  Windows.   Note  that  this
  159. parameter is ignored if redirection out is being used.
  160.  
  161. "/-W" says to not pause afterward at all.  This is initially the default if  the
  162. program is run under DOS.
  163.  
  164. "/?" or "/HELP" or "HELP" shows you the syntax for the command.
  165.  
  166. "/?&H" gives you a hexadecimal and decimal conversion table.
  167.  
  168. "search" is described below.
  169.  
  170.  
  171. BFIND.DOC                            4                         Revised: 10-18-96
  172.  
  173. "filespec" tells the routine which file or  files  are  to  be  processed.   The
  174. specification can include path and wildcards  if  desired.   One  thing  I  find
  175. useful with wildcards is that is allows me to create an output that concatenates
  176. all of the input files together with the typical headers (/HEADER) that separate
  177. each portion.  This requires searching for all lines in a file so  you  need  to
  178. use the  /V  option  and  look  for  an  improbable  string.   For  example,  to
  179. concatenate all *.TXT files together as a new file called TEMP.NEW and have  the
  180. little header between each, say this:
  181.  
  182.         BFIND /V "&#$#" *.TXT > TEMP.NEW
  183.  
  184. "@listfile" allows you to have a variety of file specifications saved in a  text
  185. file named "listfile".  Each line  in  the  file  should  consist  of  one  file
  186. specification, each of which can include a path and wildcards if desired.  Blank
  187. lines and lines beginning with semi-colons, colons, or quotes are  ignored.   An
  188. example using this is provided at the end of this documentation.
  189.  
  190. ">filename" redirects the output to a text file.  This automatically invokes the
  191. /-P option.  This is useful for saving the found lines into another  file.   For
  192. example:
  193.  
  194.         BFIND "Bruce" TEMP.TXT > TEMP2.TXT
  195.  
  196.  
  197.  
  198. BFIND.DOC                            5                         Revised: 10-18-96
  199.  
  200. For search, the syntax is:
  201.  
  202.   [ ( ]... search_item [ boolean [ ( ]... search_item [ ) ]...] [ ) ]...
  203.  
  204. where:
  205.  
  206.   ( and )     are used to group items
  207.   search_item is shown below
  208.   boolean     is AND, OR, or XOR (NOT is included with search_item)
  209.  
  210. for search_item, the syntax is:
  211.  
  212.   [ NOT ]  "string" [ column ]
  213.  
  214. where:
  215.  
  216.   NOT         is obvious
  217.   string      the string to search; the quotation marks are typically not
  218.               required unless the string contains a space or a reserved word
  219.   column      is the column in which the string must be found.
  220.  
  221. So, let's cover some examples:
  222.  
  223.         BFIND "Bugs Bunny" OR "Elmer Fudd" TEST.TXT
  224.  
  225. Finds any lines in the file TEST.TXT containing either "Bugs  Bunny"  or  "Elmer
  226. Fudd" in them.
  227.  
  228.         BFIND (Apples or Oranges) AND NOT Pears TEST2.TXT
  229.  
  230. Finds any lines in the file  TEST2.TXT  which  contain  the  words  "Apples"  or
  231. "Oranges" in them and ignores any  lines  containing  "Pears".   Note  that  the
  232. quotes around the search words are not required unless the words include  spaces
  233. or unless they could be confused with some other keywords.   "BFIND  OR  OR  AND
  234. TEST3.TXT" might cause the program to get confused since "OR" and  "AND",  which
  235. you want to look for, are also keywords.
  236.  
  237.         BFIND /C "Bugs Bunny" AND Martians TEST.TXT
  238.  
  239. Gives you a total for the number of  lines  containing  both  "Bugs  Bunny"  and
  240. "Martians".
  241.  
  242. The search string can include any text characters.  It can  also  contain  ASCII
  243. codes, created either using the Alt key in combination with the  numeric  keypad
  244. (e.g. Alt-228 to get a Sigma character) or else by embedding a hexadecimal  code
  245. (in the form &Hxx) or a decimal code (in the form  \nnn)  in  the  text.   These
  246. codes are described in the BRUCEHEX.DOC file.  For example, to find  the  smiley
  247. face character in a file called TEST.TXT, either of the following work:
  248.  
  249.         BFIND "" TEST.TXT
  250.         BFIND \001 TEST.TXT
  251.  
  252.  
  253. BFIND.DOC                            6                         Revised: 10-18-96
  254.  
  255. If you search for more than one word without using  a  Boolean  operator,  BFIND
  256. presumes you wanted the words searched with an "AND" Boolean operator.  So this:
  257.  
  258.         BFIND Print Form *.TXT
  259.  
  260. is the same thing as saying:
  261.  
  262.         BFIND Print AND Form *.TXT
  263.  
  264. If you wanted to search for the *phrase* "Print Form", you'd have to say:
  265.  
  266.         BFIND "Print Form" *.TXT
  267.  
  268. You can press the Esc key to abort the search early.
  269.  
  270. BFIND, unlike FIND, typically doesn't require the search string to be in quotes.
  271. As a result, you can create a text file (presume it's  called  C:\BAT\PHONE.TXT)
  272. containing phone numbers or  something  and  then  create  a  batch  file  (like
  273. PHONE.BAT) that looks like this:
  274.  
  275.         BFIND %1 %2 %3 %4 %5 C:\BAT\PHONE.TXT
  276.  
  277. When you want to find a phone number, you just say  "PHONE  name".   This  is  a
  278. little more natural that using FIND which would require  that  you  enclose  the
  279. name in quotes.  You can still use the Boolean operators  in  BFIND;  the  batch
  280. file above would allow up to five parameters.
  281.  
  282. If you have multiple phone books, use the @listfile option in  the  batch  file.
  283. For example, I have four phone files I search; a personal  one  (PHONES.TXT),  a
  284. list of e-mail addresses (PHONMAIL.TXT), a list of  work-related  phone  numbers
  285. that  are  distributed  to  the  office  (EBBPHONE.TXT),  and  an  office   list
  286. (OBAPHONE.TXT).  My @listfile is called  C:\MINE\PHONE.LST  and  contains  these
  287. lines:
  288.  
  289.         c:\mine\phones.txt
  290.         c:\mine\phonmail.txt
  291.         c:\mine\ebbphone.txt
  292.         c:\mine\obaphone.txt
  293.  
  294. My PHONE.BAT file contains this line:
  295.  
  296.         BFIND /I /P /-EMPTY %1 %2 %3 %4 @C:\MINE\PHONE.LST
  297.  
  298.  
  299.  
  300. BFIND.DOC                            7                         Revised: 10-18-96
  301.  
  302. Return codes:
  303.  
  304. BFIND returns the following ERRORLEVEL codes:
  305.         0 = no problems, string found
  306.         1 = no problems, string not found
  307.       250 = operation aborted by pressing Escape
  308.       255 = syntax problems, file not found, or /? requested
  309.  
  310.  
  311. Author:
  312.  
  313. This program was written by Bruce Guthrie of Wayne Software.  It is free for use
  314. and redistribution provided relevant documentation is kept with the program,  no
  315. changes are made to the program or documentation, and it  is  not  bundled  with
  316. commercial programs or charged for separately.  People who need to bundle it  in
  317. for-sale packages must pay a $50 registration fee to  "Wayne  Software"  at  the
  318. following address.
  319.  
  320. Additional information about this and other Wayne Software programs can be found
  321. in the file BRUCEymm.DOC which should be included  in  the  original  ZIP  file.
  322. ("ymm" is replaced by the last digit of the year and the two digit month of  the
  323. release.  BRUCE512.DOC came out in December 1995.  This same  naming  convention
  324. is used in naming the ZIP file that this program was included in.) Comments  and
  325. suggestions can also be sent to:
  326.  
  327.                 Bruce Guthrie
  328.                 Wayne Software
  329.                 113 Sheffield St.
  330.                 Silver Spring, MD 20910
  331.  
  332.                 fax: (301) 588-8986
  333.                 e-mail: bguthrie@nmaa.org
  334.                 http://hjs.geol.uib.no/guthrie/
  335.  
  336. See BRUCEymm.DOC file for revision history.
  337.  
  338. Please provide an Internet e-mail address on all correspondence.
  339.  
  340. 
  341.