home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-385-Vol-1of3.iso / k / kwsrc120.zip / KWS.DOC next >
Text File  |  1993-01-22  |  14KB  |  347 lines
  1.  
  2.  
  3.  
  4.      KWS V1.20 Copyright (c) 1991-1993 Copy Con Incorporated         Page 1
  5.  
  6.  
  7.      DESCRIPTION
  8.      -----------
  9.      KWS (KeyWord Search) is a small, fast program that performs logical
  10.      AND/OR/NOT searches for keywords within one or more text files. Output
  11.      can be displayed onscreen, or sent to any output device via standard
  12.      DOS redirection. KWS excels in searching BBS file lists, and works
  13.      equally as well with other types of text files. This flexible program
  14.      also has options for 'fuzzy' searches, case, filters, pipes, line
  15.      numbering, on-screen pause, subdirectory searches, totals, and more.
  16.  
  17.  
  18.      REQUIREMENTS
  19.      ------------
  20.      Hardware: Any PC compatible. Software: DOS 2.0 or higher.
  21.  
  22.  
  23.      DISCLAIMER
  24.      ----------
  25.      KWS is distributed on an "AS IS" basis without warranty, expressed or
  26.      implied. Considerable testing effort has been expended, but the user
  27.      is advised to check the program's suitability before relying on it.
  28.      The user assumes full risk as to the results of using this program. In
  29.      no event shall the author be liable for any incidental or
  30.      consequential damages arising from the use, or inability to use this
  31.      program.
  32.  
  33.  
  34.      REGISTRATION
  35.      ------------
  36.      The unregistered version of KWS is freely distributable and fully
  37.      functional, and may be used for a 30-day trial period. If you plan to
  38.      continue using KWS, you are obligated to pay the modest registration
  39.      fee of $20. Registered users will receive an individually serialized
  40.      nag-free version of KWS, a free upgrade, and $5 subsequent upgrades.
  41.  
  42.      All registration information is contained in the KWS.REG file. If that
  43.      file is missing, register by sending your name and address (please
  44.      print), and a check or money order for $20 to:
  45.  
  46.         Copy Con Incorporated
  47.         PO Box 23255
  48.         Baltimore MD 21203-5255
  49.  
  50.      Please specify 3.5" or 5.25" diskette. MD residents add 5% sales tax.
  51.      Thank you for supporting Shareware.
  52.  
  53.  
  54.  
  55.      KWS V1.20 Copyright (c) 1991-1993 Copy Con Incorporated         Page 2
  56.  
  57.  
  58.      OPERATION
  59.      ---------
  60.      KWS is activated from the command line, using the format
  61.  
  62.         KWS [@]filename search_string[...] [options]
  63.  
  64.      Parameters surrounded by [brackets] are optional.
  65.  
  66.      The @ symbol, if used, must be directly followed by the name of a text
  67.      file containing valid filespecs; the files to be searched will be read
  68.      from that file list. (File lists can be created with KWS using the /M
  69.      option; see OPTIONS.)
  70.  
  71.      If the @ symbol is not used, the filename is the filespec to be
  72.      searched. Wildcards are optional. (For a description of wildcards and
  73.      filespecs, see your DOS manual.)
  74.  
  75.      Each search string is comprised of keywords separated by semicolons.
  76.      At least one keyword from each search string must be present in a
  77.      given line for it to be displayed; for example,
  78.  
  79.         KWS allfiles.lst fixed;hard disk;drive
  80.  
  81.      will display the lines in file ALLFILES.LST that contain either words
  82.      FIXED or HARD (or both), and also contain either words DISK or DRIVE.
  83.  
  84.      If a search string contains a keyword with embedded spaces, the entire
  85.      search string must be enclosed in quotes; for example,
  86.  
  87.         KWS temp.bat "del *;era *"
  88.  
  89.      will search TEMP.BAT for the phrase "del *" or "era *" (without the
  90.      quotes).
  91.  
  92.      A logical 'NOT' search can be conducted by preceding a keyword with
  93.      an exclamation (!) character; for example,
  94.  
  95.         KWS stuff.txt this !that
  96.  
  97.      will display the lines in STUFF.TXT that contain the word THIS and not
  98.      the word THAT. If you wish to search for an exclamation as the first
  99.      (or only) character of a keyword, use two in a row; for example,
  100.  
  101.         KWS stuff.txt this !!that
  102.  
  103.      will display lines that contain both words THIS and !THAT. Exclamation
  104.      characters inside or following keywords (as in " HEY! " or " What!? ")
  105.      do not have to be doubled.
  106.  
  107.      A fuzzy search can be conducted by preceding a keyword with a tilde
  108.      (~) character; lines with words that are similar to the keyword will
  109.      be displayed. This option is useful if you aren't sure of a keyword's
  110.      correct spelling, or if a keyword may be spelled incorrectly in the
  111.      files to be searched. for example,
  112.  
  113.  
  114.  
  115.      KWS V1.20 Copyright (c) 1991-1993 Copy Con Incorporated         Page 3
  116.  
  117.  
  118.      OPERATION (continued)
  119.      ---------------------
  120.  
  121.         KWS gnu.txt ~copyrite
  122.  
  123.      will display lines with words similar to COPYRITE. (The similarity
  124.      percentage can be adjusted with the /F option; see OPTIONS.) If you
  125.      wish to combine a fuzzy search with a logical 'NOT' search, use the
  126.      'NOT' character before the tilde (as in " !~THE "). Fuzzy searches
  127.      cannot be combined with prefix/suffix/whole word searches (described
  128.      below).
  129.  
  130.      Whole word searches can be conducted by putting underscore (_)
  131.      characters before and after the keyword; for example,
  132.  
  133.         KWS files.lst _c_ source
  134.  
  135.      will display lines in FILES.LST that contain a lone 'C' and the word
  136.      SOURCE. Similarly, prefixes can be searched for by putting an
  137.      underscore before a keyword, and suffixes can be searched for by
  138.      putting an underscore after a keyword. If you wish to search for an
  139.      underscore as the first or last (or only) character of a keyword, use
  140.      two underscores in a row, as with the logical 'NOT' exclamation
  141.      character above. If you wish to combine a prefix/whole word search
  142.      with a logical 'NOT' search, use the 'NOT' character before the
  143.      underscore (as in " !_c_ "). Prefix/suffix/whole word searches cannot
  144.      be combined with fuzzy searches (described above).
  145.  
  146.      Up to 10 search strings are allowed, with up to 10 keywords per
  147.      string.
  148.  
  149.  
  150.      OPTIONS
  151.      -------
  152.      Options can appear anywhere on the command line after the filename.
  153.      They can be in any order, and are not case-sensitive. Options can be
  154.      separated by spaces (/L3 /P /T) or strung together (/L3/P/T or /L3PT).
  155.  
  156.      Option   Description
  157.  
  158.        /B     This option makes the keywords stand out from the rest of the
  159.               displayed line. Output cannot be redirected when using this
  160.               option.
  161.  
  162.        /C     Search will be case-sensitive.
  163.  
  164.        /E     The command line will be echoed as the first output line.
  165.               Useful mainly with redirected files to avoid repetition, and
  166.               for testing batch files.
  167.  
  168.        /Fn    This option controls the similarity percentage for fuzzy
  169.               searches. Similarity defaults to 65 percent, and can be
  170.               adjusted from 0 (display almost every line) to 100 (display
  171.               exact matches).
  172.  
  173.  
  174.  
  175.      KWS V1.20 Copyright (c) 1991-1993 Copy Con Incorporated         Page 4
  176.  
  177.  
  178.      OPTIONS (continued)
  179.      -------------------
  180.  
  181.        /H     Hidden and/or system files will also be searched.
  182.  
  183.        /Kc    Change the keyword separator charactor from a semicolon to
  184.               the specified character. This option may be needed to pass
  185.               multiple keyword parameters to a batch file, as some versions
  186.               of DOS remove semicolons from batch parameters.
  187.  
  188.        /L[n]  Line numbers will be displayed with output. If no width is
  189.               specified, the numbers will be left-justified, with a colon
  190.               between the number and the text; otherwise, the numbers will
  191.               be right-justified and zero-padded to the left, followed by
  192.               the colon and text. If the specified width is too small for a
  193.               number to fit, the number will NOT be truncated.
  194.  
  195.        /M[n]  Stop searching after n matches per file. /M alone will cause
  196.               KWS to print only the filenames of successful searches, and
  197.               they can be redirected to a file to be used as a file list.
  198.  
  199.        /P     Pause between each screen of text. KWS will autodetect your
  200.               screen size, and pause accordingly. This option should not be
  201.               used if redirecting output or if using the /R option.
  202.  
  203.        /R     Instead of reading from text files, KWS will act as a filter
  204.               or pipe (input is taken from an input device or from another
  205.               program's output). When in this mode, the /P option will be
  206.               inactive. Do not specify a filename when using this option.
  207.  
  208.        /S     Subdirectories will also be searched. This option is valid
  209.               only with wildcard and file list searches.
  210.  
  211.        /T     Display total lines found per file. For wildcard and file
  212.               list searches, a grand total will also be displayed.
  213.  
  214.  
  215.      EXAMPLES
  216.      --------
  217.      KWS catalog.lst dvorak keyboard /p
  218.        will take the lines in file CATALOG.LST that contain the words
  219.        DVORAK and KEYBOARD, and display them one screen at a time.
  220.  
  221.      KWS catalog.lst arc;lzh shell /l5 >prn
  222.        will take the lines in file CATALOG.LST that contain either ARC or
  223.        LZH, and also contain SHELL, and send them to the printer, along
  224.        with their line numbers.
  225.  
  226.      KWS allfiles.lst /c !.ZIP >nozip.lst
  227.        will make a file called NOZIP.LST, which will contain all of the
  228.        lines in ALLFILES.LST that do NOT contain the word .ZIP in caps.
  229.  
  230.  
  231.  
  232.      KWS V1.20 Copyright (c) 1991-1993 Copy Con Incorporated         Page 5
  233.  
  234.  
  235.      EXAMPLES (continued)
  236.      --------------------
  237.      KWS \dl\*.lst MIDI /ptc
  238.        will search all .LST files in the DL directory for the word MIDI in
  239.        capital letters, and displays the filenames and lines onscreen, one
  240.        screen at a time, with totals for each file.
  241.  
  242.      KWS *.bak _the_
  243.        will search the backup files for lines that contain the word THE,
  244.        but will not display them if THE is part of another word (as in
  245.        THESIS or OTHER).
  246.  
  247.      KWS temp.bak _the_;!_the_ /b
  248.        will display every line in TEMP.BAK, hilighting any occurrance of
  249.        the word THE.
  250.  
  251.      KWS wp.txt _in /p
  252.        searches file WP.TXT for words beginning with IN, pausing at each
  253.        screen.
  254.  
  255.      KWS c:\*.bat _del;_era /s/h
  256.        will search all of the batch files on the C: drive, including those
  257.        with their hidden and/or system attributes set, to see if any of
  258.        them delete/erase files.
  259.  
  260.      KWS this;that /r <con >prn
  261.        reads input from the CON device (the keyboard), filters out lines
  262.        that do not contain words THIS or THAT, and sends the rest to the
  263.        PRN device (the printer, most likely), until Ctrl-Break is pressed.
  264.  
  265.      dir | KWS -92 /r
  266.        pipes the output from the DIR command into KWS, which will display
  267.        the directory entries from 1992.
  268.  
  269.      KWS ; /r /l3 <one.txt >two.txt
  270.        creates file TWO.TXT which is a duplicate of file ONE.TXT, except
  271.        that it has 3-digit line numbers. (A search for the keyword
  272.        separator will find every line.)
  273.  
  274.      KWS *.doc ~copyrite /f70b
  275.        will search the .DOC files for words similar to COPYRITE, hilighting
  276.        any close calls.
  277.  
  278.      KWS *.doc ~copyrite !1993 /f70b
  279.        will display the same lines as the above example, except for lines
  280.        containing the word 1993.
  281.  
  282.      KWS allfiles.lst _c_;assem;asm src;source /pb
  283.        will display all lines in ALLFILES.LST that have to do with C or
  284.        assembler source code. Keywords will be in bold, and output will be
  285.        paused after each screen.
  286.  
  287.      KWS allfiles.lst _c_;assem;asm src;source !c++ /pb
  288.        will display the same as above, except C++ files will not be shown.
  289.  
  290.  
  291.  
  292.      KWS V1.20 Copyright (c) 1991-1993 Copy Con Incorporated         Page 6
  293.  
  294.  
  295.      EXAMPLES (continued)
  296.      --------------------
  297.      KWS c:\*.bat ; /sm >filelist.txt
  298.        will create a file named FILELIST.TXT containing the names of all of
  299.        the batch files on the C: drive. This file is used in the next
  300.        example.
  301.  
  302.      KWS @filelist.txt label "if %;goto"
  303.        will search the filenames in FILELIST.TXT, and display lines in
  304.        those files that contain the word LABEL and either the word GOTO or
  305.        the phrase "IF %" (without the quotes). Note that this example has
  306.        only two search strings, not three; if any words in a search string
  307.        contain spaces, then the entire search string must be in quotes.
  308.  
  309.  
  310.      RETURN CODES
  311.      ------------
  312.      The DOS errorlevel will be set if a search is unsuccessful:
  313.  
  314.      Level  Description
  315.  
  316.        1    Invalid command line options
  317.  
  318.        2    None of the files contain the search string(s)
  319.  
  320.        3    Ctrl-Break interrupt
  321.  
  322.        4    Invalid directory specified
  323.  
  324.        5    No files match filespec
  325.  
  326.  
  327.      SUPPORT
  328.      -------
  329.      If you have questions, comments, suggestions, bug reports, et cetera,
  330.      feel free to contact me by one of the following methods:
  331.  
  332.      1: By modem at The Programmer's Corner (301-596-7692 or 410-995-6873).
  333.         Send a message to RD Thomas in the Shareware or General conference,
  334.         and check back in a couple of days for a reply.
  335.  
  336.      2: By modem in the RIME Shareware conference (RD Thomas ->1520). Allow
  337.         at least one week for a reply.
  338.  
  339.      3: By US Mail at the address given on the first page. If you would
  340.         like a reply, please include a self-addressed, stamped envelope.
  341.  
  342.      Looking forward to hearing from you.
  343.  
  344.  
  345.      This document can be printed by typing "copy kws.doc LPTx" at the DOS
  346.      prompt, where x is the number of the printer port to be used.
  347.