home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / vrac / kws144.zip / KWS.DOC < prev    next >
Text File  |  1994-09-02  |  22KB  |  511 lines
  1.  
  2.  
  3.      KWS V1.44 Copyright (c) 1991-1994 Copy Con Incorporated         Page 1
  4.  
  5.  
  6.      DESCRIPTION
  7.      -----------
  8.      KWS (KeyWord Search) is a small, fast program that searches for key-
  9.      words within text and binary files. KWS has many features and options:
  10.  
  11.       * Handles grep, boolean, prefix, suffix, whole word, case-sensitive,
  12.         and adjustable fuzzy searches.
  13.  
  14.       * Supports wildcards and @filelists, and can span subdirectories.
  15.  
  16.       * Can display matches in bold onscreen, and can also display line
  17.         numbers, file offsets, and totals.
  18.  
  19.       * Can read data from standard input, from hidden/system files, and
  20.         from text files created on other platforms.
  21.  
  22.       * Accepts input lines up to 2k in length, and can handle 4DOS/NDOS
  23.         256-character command lines.
  24.  
  25.       * Much more...
  26.  
  27.  
  28.      REQUIREMENTS
  29.      ------------
  30.      KWS will run on any PC compatible using DOS 2.0 or higher.
  31.  
  32.  
  33.      DISCLAIMER
  34.      ----------
  35.      KWS is distributed on an "AS IS" basis without warranty, expressed or
  36.      implied. Considerable testing effort has been expended, but the user
  37.      is advised to check the program's suitability before relying on it.
  38.      The user assumes full risk as to the results of using this program. In
  39.      no event shall the author be liable for any incidental or consequent-
  40.      ial damages arising from the use, or inability to use this program.
  41.  
  42.  
  43.      REGISTRATION
  44.      ------------
  45.      The unregistered version of KWS is freely distributable and fully
  46.      functional, and may be used for a 30-day trial period. If you plan to
  47.      continue using KWS, you are obligated to pay the modest registration
  48.      fee. Registered users will receive a serialized, nag-free version of
  49.      KWS, a free upgrade when available, and $5 upgrades thereafter.
  50.  
  51.      All registration information is contained in the KWS.REG file. If that
  52.      file is missing, register by sending your name and address (please
  53.      print), along with $20 (cash, check, or money order in US funds) to:
  54.  
  55.         Copy Con Incorporated
  56.         PO Box 23255
  57.         Baltimore MD 21203-5255
  58.  
  59.      Please specify 3.5" or 5.25" diskette. MD residents add 5% sales tax.
  60.      Thank you for supporting Shareware.
  61.  
  62.  
  63.      KWS V1.44 Copyright (c) 1991-1994 Copy Con Incorporated         Page 2
  64.  
  65.  
  66.      OPERATION
  67.      ---------
  68.      KWS is a powerful, flexible program; it is also very easy to use. KWS
  69.      is activated from the command line, using the format
  70.  
  71.        KWS filename search_string[...] [options]
  72.  
  73.      The filename portion of the command line consists of one or more valid
  74.      filespecs to be searched. Wildcards are optional. (For a description
  75.      of wildcards and filespecs, see your DOS manual.) If more than one
  76.      filespec is used, filespecs must be separated by plus (+) characters,
  77.      as in "file1.txt+file2.txt".
  78.  
  79.      KWS also has the ability to read filespecs from a file list. For
  80.      example, if the filename is in the format "@filelist.txt" then the
  81.      filespecs will be read from the file "filelist.txt". File lists
  82.      consist of one filespec per line, each optionally followed by a
  83.      semicolon and a comment. Each filespec in the file list is searched
  84.      relative to the current directory.
  85.  
  86.      Search strings are comprised of keywords separated by semicolons. At
  87.      least one keyword from each search string must be present in a given
  88.      line for it to be displayed; for example,
  89.  
  90.         KWS allfiles.lst fixed;hard disk;drive
  91.  
  92.      will display the lines in file ALLFILES.LST that contain either words
  93.      FIXED or HARD (or both), and also contain either words DISK or DRIVE.
  94.  
  95.      If a search string contains a keyword with embedded spaces or with a
  96.      redirection character (>,<, or |), the entire search string must be
  97.      enclosed in quotes; for example,
  98.  
  99.         KWS temp.bat "del *;era *"
  100.  
  101.      will search TEMP.BAT for phrases "del *" or "era *" (without quotes).
  102.  
  103.      A logical 'NOT' search can be conducted by preceding a keyword with
  104.      an exclamation (!) character; for example,
  105.  
  106.         KWS stuff.txt this !that
  107.  
  108.      will display the lines in STUFF.TXT that contain the word THIS and not
  109.      the word THAT. If you wish to search for an exclamation as the first
  110.      (or only) character of a keyword, use two in a row; for example,
  111.  
  112.         KWS stuff.txt this !!that
  113.  
  114.      will display lines that contain both words THIS and !THAT. Exclamation
  115.      characters inside or following keywords (as in "HEY!" or "What!?") do
  116.      not have to be doubled.
  117.  
  118.  
  119.      KWS V1.44 Copyright (c) 1991-1994 Copy Con Incorporated         Page 3
  120.  
  121.  
  122.      OPERATION (continued)
  123.      ---------------------
  124.      A fuzzy search can be conducted by preceding a keyword with a tilde
  125.      (~) character; lines with words that are similar to the keyword will
  126.      be displayed. This option is useful if you aren't sure of a keyword's
  127.      correct spelling, or if a keyword may be spelled incorrectly in the
  128.      files to be searched; for example,
  129.  
  130.         KWS gnu.txt ~copyrite
  131.  
  132.      will display lines with words similar to COPYRITE. (The similarity
  133.      percentage can be adjusted with the /F option.) If you wish to combine
  134.      a fuzzy search with a logical 'NOT' search, use the 'NOT' character
  135.      before the tilde (as in "!~THE"). Fuzzy searches cannot be combined
  136.      with prefix/suffix/whole word searches (described below).
  137.  
  138.      Whole word searches can be conducted by putting underscore (_)
  139.      characters before and after the keyword; for example,
  140.  
  141.         KWS files.lst _c_ source
  142.  
  143.      will display lines in FILES.LST that contain a lone 'C' and the word
  144.      SOURCE. Similarly, prefixes can be searched for by putting an
  145.      underscore before a keyword, and suffixes can be searched for by
  146.      putting an underscore after a keyword. If you wish to search for an
  147.      underscore as the first or last (or only) character of a keyword, use
  148.      two underscores in a row, as with the logical 'NOT' exclamation
  149.      character above. If you wish to combine a prefix/whole word search
  150.      with a logical 'NOT' search, use the 'NOT' character before the
  151.      underscore (as in "!_the_"). Prefix/suffix/whole word searches cannot
  152.      be combined with fuzzy searches (described above).
  153.  
  154.      Up to 10 search strings are allowed, with up to 10 keywords per
  155.      string.
  156.  
  157.  
  158.      OPTIONS
  159.      -------
  160.      Options can appear anywhere on the command line after the filespec.
  161.      They can be in any order, and are not case-sensitive. Options can be
  162.      separated by spaces (/L3 /P /T) or strung together (/L3/P/T or /L3PT).
  163.  
  164.      Option   Description
  165.  
  166.        /A     When this option is used, all binary files will automatically
  167.               be shown with hexadecimal file offsets.
  168.  
  169.        /B,B0  These options make all matches appear in bold type onscreen.
  170.               /B uses direct screen writes; /B0 uses BIOS screen writes,
  171.               which are slower, but compatible with more video systems.
  172.               When using either option, output cannot be routed using DOS
  173.               redirection; use the /O option to redirect output.
  174.  
  175.  
  176.      KWS V1.44 Copyright (c) 1991-1994 Copy Con Incorporated         Page 4
  177.  
  178.  
  179.      OPTIONS (continued)
  180.      -------------------
  181.        /C     Search will be case-sensitive. Case-sensitive searches are
  182.               approximately 20% faster than case-insensitive searches.
  183.  
  184.        /D     Control characters (ASCII value less than 32) in text files
  185.               will be replaced with spaces before being viewed or routed.
  186.  
  187.        /E     The command line will be echoed as the first output line.
  188.               Useful mainly with redirected files to avoid repetition, and
  189.               for testing batch files.
  190.  
  191.        /Fn    This option controls the similarity percentage for fuzzy
  192.               searches. Similarity defaults to 65 percent, and can be
  193.               adjusted from 0 (display almost every line) to 100 (display
  194.               exact matches).
  195.  
  196.        /G     This option puts KWS into regular expression mode, where
  197.               certain characters within keywords have special meaning:
  198.  
  199.               *  An asterisk matches zero or more characters; for example,
  200.                  E*T matches ET, EAT, or EDIT.
  201.  
  202.               ?  A question mark matches any one character; for example,
  203.                  E?T matches EAT, EDT, or EST.
  204.  
  205.               ^  A circumflex at the start of a keyword matches the start
  206.                  of a line.
  207.  
  208.               $  A dollar sign at the end of a keyword matches the end of a
  209.                  line.
  210.  
  211.               [] A string enclosed in brackets matches any character in
  212.                  that string, but no others. If the first character in the
  213.                  string is a circumflex (^), the expression matches any
  214.                  character except the characters in the string. For
  215.                  example, [XYZ] matches X, Y, or Z, while [^XYZ] matches
  216.                  any character except X, Y, or Z. A range of characters can
  217.                  be specified with two characters separated by a hyphen
  218.                  (-); these can be combined to form expressions like
  219.                  [A-BD-Z?], which matches the ? character and any letter
  220.                  except C.
  221.  
  222.               \  A backslash tells KWS to search for the literal character
  223.                  that follows it; for example, \* searches for an asterisk
  224.                  instead of searching for zero or more characters.
  225.  
  226.        /H     Hidden and/or system files will also be searched.
  227.  
  228.        /I     Ignore the config file, if present (see CONFIGURATION FILE).
  229.               If stringing options together, this option must be the first
  230.               in the string; for example, use "/ip" instead of "/pi".
  231.  
  232.  
  233.      KWS V1.44 Copyright (c) 1991-1994 Copy Con Incorporated         Page 5
  234.  
  235.  
  236.      OPTIONS (continued)
  237.      -------------------
  238.        /J[n]  Use the viewer defined in the config file to display matches
  239.               (see CONFIGURATION FILE). The number, if specified, is the
  240.               number of lines before the match to start viewing from.
  241.  
  242.        /Kc    Change the keyword separator character from a semicolon to
  243.               the specified character. This option may be needed to pass
  244.               multiple keyword parameters to a batch file (as some versions
  245.               of DOS remove semicolons from batch parameters), or if a
  246.               semicolon is part of a keyword to be searched.
  247.  
  248.        /L[n]  Line numbers or file offset position will be displayed with
  249.               output. If the specified width begins with a zero, then the
  250.               file offset will be displayed; otherwise, line numbers will
  251.               be displayed. If no width is specified, the numbers will be
  252.               left-justified, with a colon between the number and the text;
  253.               otherwise, the numbers will be right-justified and zero-
  254.               padded to the left, followed by the colon and text. If the
  255.               specified width is too small for a number to fit, the number
  256.               will NOT be truncated.
  257.  
  258.        /M[n]  Stop searching after n matches per file. /M alone will cause
  259.               KWS to print only the filenames of successful searches, and
  260.               these can be redirected to a file to be used as a file list.
  261.  
  262.        /N     Skip over binary files when searching multiple files.
  263.  
  264.        /Ofn   Route output to the specified device/filename. Output will be
  265.               in addition to, not instead of, output displayed onscreen. To
  266.               route output without viewing, use DOS redirection instead of
  267.               this option (see your DOS manual for details). Do not append
  268.               other options on to the end of this option, as they will be
  269.               mistaken as part of the device/filename.
  270.  
  271.        /P[n]  Pause between each screen of text. If no height is specified,
  272.               KWS will autodetect your screen size, and pause accordingly;
  273.               otherwise, KWS will pause after every n lines. While paused,
  274.               pressing the 'C' key will display the current and any
  275.               remaining files continuously. Pressing the Escape key while
  276.               paused will skip the current file and go on to the next.
  277.  
  278.        /R     Instead of reading from text files, KWS will read from
  279.               standard input. When in this mode, the /V option will be
  280.               inactive. Do not specify a filename when using this option.
  281.  
  282.        /S     Subdirectories will also be searched.
  283.  
  284.        /T,T0  Display total lines found per file. /T will display lines and
  285.               totals; /T0 will display totals only. For wildcard and file
  286.               list searches, a grand total will also be displayed.
  287.  
  288.        /U     Unix output format: All lines of output are preceded by the
  289.               name of the file that contained the matching line.
  290.  
  291.  
  292.      KWS V1.44 Copyright (c) 1991-1994 Copy Con Incorporated         Page 6
  293.  
  294.  
  295.      OPTIONS (continued)
  296.      -------------------
  297.        /V     If KWS cannot determine if a file is binary or text, text is
  298.               assumed; using this option will tell KWS to treat all files
  299.               as binary. This option is inactive when using the /R option.
  300.  
  301.        /Wn    Normally, all keywords must be on the same line for the line
  302.               to be displayed; use this option to look at more than one
  303.               line at a time. If all keywords are found within the
  304.               specified window size (maximum of 32767 lines), then the
  305.               lines will be displayed, starting with the first line to
  306.               contain a keyword, and ending with the last line to contain a
  307.               keyword. This option is inactive when searching binary files.
  308.  
  309.        /X     Line numbers and offsets will be displayed in hexadecimal.
  310.  
  311.        /Z     Verbose mode: KWS prints the filename of every file searched,
  312.               each matching line is preceded by its line number, and a
  313.               count of matching lines in each file is given, even if the
  314.               count is zero.
  315.  
  316.  
  317.      CONFIGURATION FILE
  318.      ------------------
  319.      Under DOS 3.0 or higher, a default configuration for KWS can be stored
  320.      in a text file. If a file named KWS.CFG is in the same directory as
  321.      KWS.EXE, KWS will read default configuration values from the CFG file.
  322.      The config file can be ignored by using the /I option.
  323.  
  324.      Each line of the file consists of a configuration item, an equal sign,
  325.      and the item's value.
  326.  
  327.      Item     Description
  328.  
  329.      OPTIONS  For specifying default command line option values. As with
  330.               command line options, case is not important, and the options
  331.               may be strung together. Any options enabled in the config
  332.               file can be disabled on the command line by specifying the
  333.               option with a minus sign appended. For example, with a config
  334.               file that reads
  335.  
  336.                   options=/b /p
  337.  
  338.               bold keywords and screen pausing will be in effect whenever
  339.               KWS is run. To disable bold keywords, "/b-" can be specified
  340.               on the command line.
  341.  
  342.      VIEWER   Determines what program is run when the /J option is used.
  343.               The value specified is the command line to execute. If "!F"
  344.               or "!f" is encountered on the line, it will be replaced with
  345.               the current file name before executing, and "!L" or "!l" will
  346.               be replaced with the current line number. For example, if a
  347.               match is found on line 30 of FILES.LST, and
  348.  
  349.                   viewer=c:\utils\list.com !f /#:!l /l-
  350.  
  351.  
  352.      KWS V1.44 Copyright (c) 1991-1994 Copy Con Incorporated         Page 7
  353.  
  354.  
  355.      CONFIGURATION FILE (continued)
  356.      ------------------------------
  357.               is in your config file, KWS will execute:
  358.  
  359.                   C:\UTILS\LIST.COM FILES.LST /#:30 /l-
  360.  
  361.  
  362.      EXAMPLES
  363.      --------
  364.      KWS catalog.lst dvorak keyboard /p /u
  365.        will take the lines in file CATALOG.LST that contain the words
  366.        DVORAK and KEYBOARD, and display them one screen at a time (P), in
  367.        UNIX output format (U).
  368.  
  369.      KWS catalog.lst arc;lzh shell /l5 /oprn
  370.        will take the lines in file CATALOG.LST that contain either ARC or
  371.        LZH, and also contain SHELL, and display them onscreen with line
  372.        numbers (L5), while sending them to the printer (OPRN).
  373.  
  374.      KWS allfiles.lst /c !.ZIP >nozip.lst
  375.        will make a file called NOZIP.LST, which will contain all of the
  376.        lines in ALLFILES.LST that do NOT contain the word .ZIP in caps (C).
  377.        Output will not be seen onscreen.
  378.  
  379.      KWS \dl\*.lst MIDI /ptc
  380.        will search all .LST files in the DL directory for the word MIDI in
  381.        capital letters (C), and displays the filenames and lines onscreen,
  382.        one screen at a time (P), with totals (T) for each file.
  383.  
  384.      KWS *.bak _the_
  385.        will search the backup files for lines that contain the word THE,
  386.        but will not display them if THE is part of another word (as in
  387.        THESIS or OTHER).
  388.  
  389.      KWS temp.bak _the_; /b
  390.        will display every line in TEMP.BAK, highlighting (B) any occurrence
  391.        of the word THE.
  392.  
  393.      KWS c:\*.bat _del;_era /s/h
  394.        will search all (S) of the batch files on the C: drive, including
  395.        those with their hidden and/or system attributes set (H), to see if
  396.        any of them delete/erase files.
  397.  
  398.      dir | KWS -92 /r
  399.        pipes the output from the DIR command into KWS (R), which will
  400.        display the directory entries from 1992.
  401.  
  402.      KWS ; /r /l3 <one.txt >two.txt
  403.        creates file TWO.TXT which is a duplicate of file ONE.TXT, except
  404.        that TWO.TXT will have 3-digit line numbers (L3). (A search for the
  405.        keyword separator will find every line.) The file ONE.TXT is read
  406.        from the standard input device (R).
  407.  
  408.  
  409.      KWS V1.44 Copyright (c) 1991-1994 Copy Con Incorporated         Page 8
  410.  
  411.  
  412.      EXAMPLES (continued)
  413.      --------------------
  414.      KWS unix.man ; >unix.doc
  415.        converts a Unix format text file (LF delimited) into a DOS format
  416.        text file (CR/LF delimited). KWS can also read CR delimited files.
  417.  
  418.      KWS *.* ~copyrite /nf70b
  419.        will search the text files (N) in the current directory for words
  420.        similar to COPYRITE, highlighting (B) any close calls (F70).
  421.  
  422.      KWS *.* ~copyrite !1993 /nf70b
  423.        will display the same lines as the above example, except for lines
  424.        containing the word 1993.
  425.  
  426.      KWS allfiles.lst _c_;assem;asm src;source /pb
  427.        will display all lines in ALLFILES.LST that have to do with C or
  428.        assembler source code. Keywords will be in bold (B), and output will
  429.        be paused after each screen (P).
  430.  
  431.      KWS allfiles.lst _c_;assem;asm src;source !c++ /pb
  432.        will display the same as above, except C++ files will not be shown.
  433.  
  434.      KWS \*.com+\*.exe ; /hal6p /od:com.txt
  435.        examines all (H) .COM and .EXE files in the root directory, using
  436.        hex (A) file offsets 6 characters wide (L6), pausing at each screen
  437.        (P), while also sending output to file COM.TXT on the D: drive
  438.        (OD:COM.TXT).
  439.  
  440.      KWS telix.use download file /w2
  441.        searches a Telix usage log, looking at two lines at a time (W2), to
  442.        see what files were downloaded.
  443.  
  444.      KWS kws.doc ; /pdolpt2
  445.        displays this file, one screen at a time (P), removing embedded
  446.        formfeed characters (D), while also sending output to printer LPT2
  447.        (OLPT2).
  448.  
  449.      KWS c:\*.bat ; /sm >filelist.txt
  450.        will create a file named FILELIST.TXT containing the names of all
  451.        (S) of the batch files on the C: drive. This file is used in the
  452.        next example.
  453.  
  454.      KWS @filelist.txt label "if %;goto"
  455.        will search the filenames in FILELIST.TXT, and display lines in
  456.        those files that contain the word LABEL and either the word GOTO or
  457.        the phrase "IF %" (without the quotes). Note that this example has
  458.        only two search strings, not three; if any words in a search string
  459.        contain spaces, then the entire search string must be in quotes.
  460.  
  461.      KWS @filelist.txt label "if %;goto" /j3
  462.        will conduct the same search as above, but the program specified in
  463.        the configuration file under VIEWER will be used to show each match.
  464.        Viewing will start 3 lines before the actual match.
  465.  
  466.  
  467.      KWS V1.44 Copyright (c) 1991-1994 Copy Con Incorporated         Page 9
  468.  
  469.  
  470.      RETURN CODES
  471.      ------------
  472.      The DOS errorlevel will be set if a search is unsuccessful:
  473.  
  474.      Level  Description
  475.  
  476.        1    Invalid command line options
  477.  
  478.        2    None of the files contain the search string(s)
  479.  
  480.        3    Ctrl-Break interrupt
  481.  
  482.        4    Invalid directory specified
  483.  
  484.        5    No files match filespec
  485.  
  486.        6    Unable to open output file
  487.  
  488.  
  489.      SUPPORT
  490.      -------
  491.      In the event of a major upgrade, notice will be sent to registered
  492.      users, detailing changes since their last upgrade. Minor evaluation
  493.      upgrades will be released through BBSes, distributors, user groups, et
  494.      cetera. Registered users will receive a free upgrade upon request, and
  495.      subsequent upgrades can be obtained for $5 shipping.
  496.  
  497.      If you have questions, comments, suggestions, bug reports, et cetera,
  498.      feel free to contact me (RD Thomas) by any of the following methods:
  499.  
  500.      Internet: rain@ghawk.com
  501.          RIME: Shareware conference (->837 or ->1520)
  502.          FIDO: Shareware conference
  503.         BBSes: GreyHawk (301-596-7064 or 410-290-3260 or 410-720-5083)
  504.                The Programmer's Corner (301-596-7692 or 410-995-6873)
  505.       US Mail: PO Box 23255, Baltimore MD 21203-5255
  506.  
  507.      Looking forward to hearing from you.
  508.  
  509.  
  510.      To print this document, type "COPY KWS.DOC PRN" at the DOS prompt.
  511.