DP Tool Club 8/CDASC08.ISO/VRAC/KWS142.ZIP/KWS.DOC

Text File | 1993-09-17 | 21KB | 502 lines

     KWS V1.42 Copyright (c) 1991-1993 Copy Con Incorporated         Page 1


     DESCRIPTION
     -----------
     KWS (KeyWord Search) is a small, fast program that searches for key-
     words within text and binary files. KWS has many features and options:

      * Handles grep, boolean, prefix, suffix, whole word, case-sensitive,
        and adjustable fuzzy searches.

      * Supports wildcards and @filelists, and can span subdirectories.

      * Can display matches in bold onscreen, and can also display line
        numbers, file offsets, and totals.

      * Can read data from standard input, from hidden/system files, and
        from text files created on other platforms.

      * Accepts input lines up to 2k in length, and can handle 4DOS/NDOS
        256-character command lines.

      * Much more...


     REQUIREMENTS
     ------------
     KWS will run on any PC compatible using DOS 2.0 or higher.


     DISCLAIMER
     ----------
     KWS is distributed on an "AS IS" basis without warranty, expressed or
     implied. Considerable testing effort has been expended, but the user
     is advised to check the program's suitability before relying on it.
     The user assumes full risk as to the results of using this program. In
     no event shall the author be liable for any incidental or consequent-
     ial damages arising from the use, or inability to use this program.


     REGISTRATION
     ------------
     The unregistered version of KWS is freely distributable and fully
     functional, and may be used for a 30-day trial period. If you plan to
     continue using KWS, you are obligated to pay the modest registration
     fee. Registered users will receive a serialized, nag-free version of
     KWS, a free upgrade when available, and $5 subsequent upgrades.

     All registration information is contained in the KWS.REG file. If that
     file is missing, register by sending your name and address (please
     print), along with $20 (cash, check, or money order in US funds) to:

        Copy Con Incorporated
        PO Box 23255
        Baltimore MD 21203-5255

     Please specify 3.5" or 5.25" diskette. MD residents add 5% sales tax.
     Thank you for supporting Shareware.



     KWS V1.42 Copyright (c) 1991-1993 Copy Con Incorporated         Page 2


     OPERATION
     ---------
     KWS is activated from the command line, using the format

        KWS [@]filename search_string[...] [options]

     Parameters surrounded by [brackets] are optional.

     The filename is the filespec to be searched. Wildcards are optional.
     (For a description of wildcards and filespecs, see your DOS manual.)
     If the @ symbol is used, the filename is instead the name of a text
     file containing valid filespecs; the files to be searched will be read
     from that file list. Each filespec in the file list will be searched
     relative to the current directory.

     Each search string is comprised of keywords separated by semicolons.
     At least one keyword from each search string must be present in a
     given line for it to be displayed; for example,

        KWS allfiles.lst fixed;hard disk;drive

     will display the lines in file ALLFILES.LST that contain either words
     FIXED or HARD (or both), and also contain either words DISK or DRIVE.

     If a search string contains a keyword with embedded spaces or with a
     redirection character (>,<, or |), the entire search string must be
     enclosed in quotes; for example,

        KWS temp.bat "del *;era *"

     will search TEMP.BAT for phrases "del *" or "era *" (without quotes).

     A logical 'NOT' search can be conducted by preceding a keyword with
     an exclamation (!) character; for example,

        KWS stuff.txt this !that

     will display the lines in STUFF.TXT that contain the word THIS and not
     the word THAT. If you wish to search for an exclamation as the first
     (or only) character of a keyword, use two in a row; for example,

        KWS stuff.txt this !!that

     will display lines that contain both words THIS and !THAT. Exclamation
     characters inside or following keywords (as in "HEY!" or "What!?") do
     not have to be doubled.

     A fuzzy search can be conducted by preceding a keyword with a tilde
     (~) character; lines with words that are similar to the keyword will
     be displayed. This option is useful if you aren't sure of a keyword's
     correct spelling, or if a keyword may be spelled incorrectly in the
     files to be searched; for example,

        KWS gnu.txt ~copyrite



     KWS V1.42 Copyright (c) 1991-1993 Copy Con Incorporated         Page 3


     OPERATION (continued)
     ---------------------
     will display lines with words similar to COPYRITE. (The similarity
     percentage can be adjusted with the /F option.) If you wish to combine
     a fuzzy search with a logical 'NOT' search, use the 'NOT' character
     before the tilde (as in "!~THE"). Fuzzy searches cannot be combined
     with prefix/suffix/whole word searches (described below).

     Whole word searches can be conducted by putting underscore (_)
     characters before and after the keyword; for example,

        KWS files.lst _c_ source

     will display lines in FILES.LST that contain a lone 'C' and the word
     SOURCE. Similarly, prefixes can be searched for by putting an
     underscore before a keyword, and suffixes can be searched for by
     putting an underscore after a keyword. If you wish to search for an
     underscore as the first or last (or only) character of a keyword, use
     two underscores in a row, as with the logical 'NOT' exclamation
     character above. If you wish to combine a prefix/whole word search
     with a logical 'NOT' search, use the 'NOT' character before the
     underscore (as in "!_the_"). Prefix/suffix/whole word searches cannot
     be combined with fuzzy searches (described above).

     Up to 10 search strings are allowed, with up to 10 keywords per
     string.


     OPTIONS
     -------
     Options can appear anywhere on the command line after the filespec.
     They can be in any order, and are not case-sensitive. Options can be
     separated by spaces (/L3 /P /T) or strung together (/L3/P/T or /L3PT).

     Option   Description

       /A     When this option is used, all binary files will automatically
              be shown with hexadecimal file offsets.

       /B,B0  These options make all matches appear in bold type onscreen.
              /B uses direct screen writes; /B0 uses BIOS screen writes,
              which are slower, but compatible with more video systems.
              When using either option, output cannot be routed using DOS
              redirection; use the /O option to redirect output.

       /C     Search will be case-sensitive. Case-sensitive searches are
              approximately 20% faster than case-insensitive searches.

       /D     Control characters (ASCII value less than 32) in text files
              will be replaced with spaces before being viewed or routed.

       /E     The command line will be echoed as the first output line.
              Useful mainly with redirected files to avoid repetition, and
              for testing batch files.



     KWS V1.42 Copyright (c) 1991-1993 Copy Con Incorporated         Page 4


     OPTIONS (continued)
     -------------------
       /Fn    This option controls the similarity percentage for fuzzy
              searches. Similarity defaults to 65 percent, and can be
              adjusted from 0 (display almost every line) to 100 (display
              exact matches).

       /G     This option puts KWS into regular expression mode, where
              certain characters within keywords have special meaning:

              *  An asterisk matches zero or more characters; for example,
                 E*T matches ET, EAT, or EDIT.

              ?  A question mark matches any one character; for example,
                 E?T matches EAT, EDT, or EST.

              ^  A circumflex at the start of a keyword matches the start
                 of a line.

              $  A dollar sign at the end of a keyword matches the end of a
                 line.

              [] A string enclosed in brackets matches any character in
                 that string, but no others. If the first character in the
                 string is a circumflex (^), the expression matches any
                 character except the characters in the string. For
                 example, [XYZ] matches X, Y, or Z, while [^XYZ] matches
                 any character except X, Y, or Z. A range of characters can
                 be specified with two characters separated by a hyphen
                 (-); these can be combined to form expressions like
                 [A-BD-Z?], which matches the ? character and any letter
                 except C.

              \  A backslash tells KWS to search for the literal character
                 that follows it; for example, \* searches for an asterisk
                 instead of searching for zero or more characters.

       /H     Hidden and/or system files will also be searched.

       /I     Ignore the config file, if present (see CONFIGURATION FILE).
              If stringing options together, this option must be the first
              in the string; for example, use "/ip" instead of "/pi".

       /J[n]  Use the viewer defined in the config file to display matches
              (see CONFIGURATION FILE). The number, if specified, is the
              number of lines before the match to start viewing from.

       /Kc    Change the keyword separator charactor from a semicolon to
              the specified character. This option may be needed to pass
              multiple keyword parameters to a batch file (as some versions
              of DOS remove semicolons from batch parameters), or if a
              semicolon is part of a keyword to be searched.



     KWS V1.42 Copyright (c) 1991-1993 Copy Con Incorporated         Page 5


     OPTIONS (continued)
     -------------------
       /L[n]  Line numbers or file offset position will be displayed with
              output. If the specified width begins with a zero, then the
              file offset will be displayed; otherwise, line numbers will
              be displayed. If no width is specified, the numbers will be
              left-justified, with a colon between the number and the text;
              otherwise, the numbers will be right-justified and zero-
              padded to the left, followed by the colon and text. If the
              specified width is too small for a number to fit, the number
              will NOT be truncated.

       /M[n]  Stop searching after n matches per file. /M alone will cause
              KWS to print only the filenames of successful searches, and
              these can be redirected to a file to be used as a file list.

       /Ofn   Route output to the specified device/filename. Output will be
              in addition to, not instead of, output displayed onscreen. To
              route output without viewing, use DOS redirection instead of
              this option (see your DOS manual for details). Do not append
              other options on to the end of this option, as they will be
              mistaken as part of the device/filename.

       /P[n]  Pause between each screen of text. If no height is specified,
              KWS will autodetect your screen size, and pause accordingly;
              otherwise, KWS will pause after every n lines. While paused,
              pressing the 'C' key will display the current and any
              remaining files continuously. Pressing the Escape key while
              paused will skip the current file and go on to the next.

       /R     Instead of reading from text files, KWS will read from
              standard input. When in this mode, the /V option will be
              inactive. Do not specify a filename when using this option.

       /S     Subdirectories will also be searched. This option is valid
              only with wildcard and file list searches.

       /T,T0  Display total lines found per file. /T will display lines and
              totals; /T0 will display totals only. For wildcard and file
              list searches, a grand total will also be displayed.

       /V     If KWS cannot determine if a file is binary or text, text is
              assumed; using this option will tell KWS to treat all files
              as binary. This option is inactive when using the /R option.

       /Wn    Normally, all keywords must be on the same line for the line
              to be displayed; use this option to look at more than one
              line at a time. If all keywords are found within the
              specified window size (maximum of 32767 lines), then the
              lines will be displayed, starting with the first line to
              contain a keyword, and ending with the last line to contain a
              keyword. This option is inactive when searching binary files.

       /X     Line numbers and offsets will be displayed in hexadecimal.



     KWS V1.42 Copyright (c) 1991-1993 Copy Con Incorporated         Page 6


     CONFIGURATION FILE
     ------------------
     Under DOS 3.0 or higher, a default configuration for KWS can be stored
     in a text file. If a file named KWS.CFG is in the same directory as
     KWS.EXE, KWS will read default configuration values from the CFG file.
     The config file can be ignored by using the /I option.

     Each line of the file consists of a configuration item, an equal sign,
     and the item's value.

     Item     Description

     OPTIONS  For specifying default command line option values. As with
              command line options, case is not important, and the options
              may be strung together. Any options enabled in the config
              file can be disabled on the command line by specifying the
              option with a minus sign appended. For example, with a config
              file that reads

                  options=/b /p

              bold keywords and screen pausing will be in effect whenever
              KWS is run. To disable bold keywords, "/b-" can be specified
              on the command line.

     VIEWER   Determines what program is run when the /J option is used.
              The value specified is the command line to execute. If "!F"
              or "!f" is encountered on the line, it will be replaced with
              the current file name before executing, and "!L" or "!l" will
              be replaced with the current line number. For example, if a
              match is found on line 30 of FILES.LST, and

                  viewer=c:\utils\list.com !f /#:!l /l-

              is in your config file, KWS will execute:

                  C:\UTILS\LIST.COM FILES.LST /#:30 /l-


     EXAMPLES
     --------
     KWS catalog.lst dvorak keyboard /p
       will take the lines in file CATALOG.LST that contain the words
       DVORAK and KEYBOARD, and display them one screen at a time (P).

     KWS catalog.lst arc;lzh shell /l5 /oprn
       will take the lines in file CATALOG.LST that contain either ARC or
       LZH, and also contain SHELL, and display them onscreen with line
       numbers (L5), while sending them to the printer (OPRN).

     KWS allfiles.lst /c !.ZIP >nozip.lst
       will make a file called NOZIP.LST, which will contain all of the
       lines in ALLFILES.LST that do NOT contain the word .ZIP in caps (C).
       Output will not be seen onscreen.



     KWS V1.42 Copyright (c) 1991-1993 Copy Con Incorporated         Page 7


     EXAMPLES (continued)
     --------------------
     KWS \dl\*.lst MIDI /ptc
       will search all .LST files in the DL directory for the word MIDI in
       capital letters (C), and displays the filenames and lines onscreen,
       one screen at a time (P), with totals (T) for each file.

     KWS *.bak _the_
       will search the backup files for lines that contain the word THE,
       but will not display them if THE is part of another word (as in
       THESIS or OTHER).

     KWS temp.bak _the_; /b
       will display every line in TEMP.BAK, hilighting (B) any occurrance
       of the word THE.

     KWS c:\*.bat _del;_era /s/h
       will search all (S) of the batch files on the C: drive, including
       those with their hidden and/or system attributes set (H), to see if
       any of them delete/erase files.

     dir | KWS -92 /r
       pipes the output from the DIR command into KWS (R), which will
       display the directory entries from 1992.

     KWS ; /r /l3 <one.txt >two.txt
       creates file TWO.TXT which is a duplicate of file ONE.TXT, except
       that TWO.TXT will have 3-digit line numbers (L3). (A search for the
       keyword separator will find every line.)

     KWS unix.man ; >unix.doc
       converts a Unix format text file (LF delimited) into a DOS format
       text file (CR/LF delimited). KWS can also read CR delimited files.

     KWS *.doc ~copyrite /f70b
       will search the .DOC files for words similar to COPYRITE, hilighting
       any close calls (F70).

     KWS *.doc ~copyrite !1993 /f70b
       will display the same lines as the above example, except for lines
       containing the word 1993.

     KWS allfiles.lst _c_;assem;asm src;source /pb
       will display all lines in ALLFILES.LST that have to do with C or
       assembler source code. Keywords will be in bold (B), and output will
       be paused after each screen (P).

     KWS allfiles.lst _c_;assem;asm src;source !c++ /pb
       will display the same as above, except C++ files will not be shown.

     KWS \dl\*.gif GIFLITE /cm
       looks inside of GIF files to see if any have been GIFLITEd, showing
       the filenames (M) of those that have.



     KWS V1.42 Copyright (c) 1991-1993 Copy Con Incorporated         Page 8


     EXAMPLES (continued)
     --------------------
     KWS \*.com ; /hal6p /od:com.txt
       examines all (even hidden/system) .COM files in the root directory,
       using hex (A) file offsets 6 characters wide (L6), pausing at each
       screen (P), while also sending output to file COM.TXT on the D:
       drive (OD:COM.TXT).

     KWS telix.use download file /w2
       searches a Telix usage log, looking at two lines at a time (W2), to
       see what files were downloaded.

     KWS kws.doc ; /pdolpt2
       displays this file, one screen at a time (P), removing embedded
       formfeed characters (D), while also sending output to printer LPT2
       (OLPT2).

     KWS c:\*.bat ; /sm >filelist.txt
       will create a file named FILELIST.TXT containing the names of all
       (S) of the batch files on the C: drive. This file is used in the
       next example.

     KWS @filelist.txt label "if %;goto"
       will search the filenames in FILELIST.TXT, and display lines in
       those files that contain the word LABEL and either the word GOTO or
       the phrase "IF %" (without the quotes). Note that this example has
       only two search strings, not three; if any words in a search string
       contain spaces, then the entire search string must be in quotes.

     KWS @filelist.txt label "if %;goto" /j3
       will conduct the same search as above, but the program specified in
       the configuration file under VIEWER will be used to show each match.
       Viewing will start 3 lines before the actual match.


     RETURN CODES
     ------------
     The DOS errorlevel will be set if a search is unsuccessful:

     Level  Description

       1    Invalid command line options

       2    None of the files contain the search string(s)

       3    Ctrl-Break interrupt

       4    Invalid directory specified

       5    No files match filespec

       6    Unable to open output file



     KWS V1.42 Copyright (c) 1991-1993 Copy Con Incorporated         Page 9


     SUPPORT
     -------
     If you have questions, comments, suggestions, bug reports, et cetera,
     feel free to contact me by any of the following methods:

     1: By modem at The Programmer's Corner (301-596-7692 or 410-995-6873).
        Send a message to RD Thomas in the Shareware or General conference,
        and check back in a couple of days for a reply.

     2: On a BBS that carries the RIME Shareware conference (RD Thomas,
        node ->1520). Allow at least one week for a reply.

     3: By US Mail at the address given on the first page. If you would
        like a reply, please include a self-addressed, stamped envelope.

     Looking forward to hearing from you.


     To print this document, type "COPY KWS.DOC PRN" at the DOS prompt.