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