home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 31 / CDASC_31_1996_juillet_aout.iso / vrac / 4dcat10.zip / FGREP180.ZIP / FGREP.DOC < prev    next >
Text File  |  1993-12-03  |  43KB  |  1,037 lines

  1.                                    FGREP 1.80
  2.                                    ----------
  3.  
  4.  
  5.  
  6.         Purpose
  7.         -------
  8.         FGREP (Fast GREP) is a small utility that can be used to find
  9.         strings of characters in ASCII text files, and arbitrary
  10.         sequences of bytes in other files.  String search capabilities
  11.         are not extensive (no regular expressions), but FGREP is small
  12.         and very, very fast.  FGREP is intended to replace the FIND
  13.         filter with something faster and more flexible.
  14.  
  15.         UNIX people: we fully realize that this isn't the grep or fgrep
  16.         with which you are familiar.  We know that the RE in GREP means
  17.         "regular expressions" and that we don't support regular
  18.         expressions.  However, the name serves to point people in the
  19.         right direction.  Please don't write to tell us that this "isn't
  20.         really fgrep".
  21.  
  22.  
  23.  
  24.         FGREP386
  25.         --------
  26.         FGREP386.COM is a version of FGREP.COM that requires an 80386
  27.         or better.  It should be slightly faster than FGREP.COM (don't
  28.         expect anything spectacular).  If you have an 80386 a higher
  29.         CPU, just erase FGREP.COM and rename FGREP386.COM to FGREP.COM.
  30.  
  31.  
  32.         New in version 1.80
  33.         -------------------
  34.         The following features are new for this version:
  35.  
  36.           - The -r option allows you to search "recursively" through
  37.             subdirectories.
  38.  
  39.           - The -i option allows you to define "search fields".
  40.  
  41.           - The BUILDFT program and the -g option allow you to build
  42.             and use your own character frequency tables, which may help
  43.             FGREP search faster.  See "Using your own frequency tables."
  44.  
  45.           - The -@, -t, -Za, -Zb, -Zd, and -Zl options are also new.  See
  46.             the "Options" section for descriptions.
  47.  
  48.           - Changes to the -o option.
  49.  
  50.           - FGREP386 has been added.
  51.  
  52.         Note that FGREP now requires DOS 3.0 or later; it will not run
  53.         under DOS 2.x.
  54.  
  55.  
  56.         "|" denotes changes in version 1.80.
  57.  
  58.  
  59.         Syntax
  60.         ------
  61.         FGREP's syntax is
  62.  
  63.                 FGREP [options] target {@file}
  64.  
  65.         There are many "options", but the most common use is very
  66.         simple:
  67.  
  68.                 FGREP hello myfile.txt
  69.  
  70.         This command would display all lines of MYFILE.TXT that contain
  71.         the character string "hello".
  72.  
  73.  
  74.         Targets
  75.         -------
  76.         The target is what you're looking for in the file.  There are
  77.         two ways to specify targets: as strings and as series of
  78.         hexadecimal bytes.  The two can be combined in a single target
  79.         specification.
  80.  
  81.         Strings are sequences of ASCII characters, like "hello".
  82.         Normally, you can just type in the string and forget it, but you
  83.         may have to "delimit" the string, i.e., bracket it by a pair of
  84.         matching non-alphanumeric characters (anything except '-' and
  85.         '$'):
  86.  
  87.             'string'
  88.             /string/
  89.             .string.
  90.  
  91.         Choose a delimiter that does not appear in the string.  This is
  92.         no good:
  93.  
  94.             'you've made a mistake'
  95.  
  96.         Delimiters are required for a string target if any of these four
  97.         conditions are met:
  98.  
  99.             -- it is combined with hex byte sequences (more below)
  100.             -- it contains spaces or tabs
  101.             -- it begins with a non-alphanumeric character
  102.             -- it contains the redirection characters < > |.
  103.  
  104.         In the last case, the string MUST be delimited by double quotes
  105.         ("), otherwise DOS will interpret it as redirection.
  106.  
  107.         Examples of valid string targets:
  108.  
  109.                 mov
  110.                 ax
  111.                 "two words"     (requires delimiter: contains a space)
  112.                 '/7'            (begins with non-alphanumeric)
  113.                 "f->x"          (contains ">", must use double quotes)
  114.  
  115.         It is always OK to delimit a string, even if delimiters are
  116.         unnecessary.
  117.  
  118.         REMEMBER that if the target contains DOS redirection characters
  119.         (<, >, or |), it MUST be delimited with double quotes ("") or
  120.         DOS will try to perform unwanted redirection.  For example:
  121.  
  122.             FGREP "a <= b" myfile.pas
  123.  
  124.         Hex byte sequences are used for binary file searching when the
  125.         bytes to be searched for are non-displayable characters or make
  126.         no sense as strings (e.g., program code).  They are specified as
  127.         pairs of hexadecimal bytes introduced by a leading '$':
  128.  
  129.             $EF
  130.             $CD21           (CDh, 21h)
  131.             $CD$21          (identical; either format is OK)
  132.             $00FFFE00       (00h, FFh, FEh, 00h)
  133.             $CD 21          (ILLEGAL: no spaces permitted)
  134.  
  135.         You can combine strings and hex sequences by using a '+':
  136.  
  137.             "abc"+$E74A+"def"
  138.  
  139.  
  140.         Target wildcards
  141.         ----------------
  142.         String targets (not hex targets) may contain one or more "?"
  143.         wildcards.  The ? will match any single non-null character in
  144.         the file.  E.g., "[?i]" will match "[si]", "[di]", etc., but not
  145.         "[i]".  Wildcards are not permitted when hex byte sequences are
  146.         used.
  147.  
  148.         If you want to search for the '?' character literally, use
  149.         '\?'.  For example, the target
  150.  
  151.                 what\?
  152.  
  153.         will search for the literal string "what?".
  154.  
  155.  
  156.         Specifying target files
  157.         -----------------------
  158.         You can list zero (see "Redirection"), one, or multiple files to
  159.         be searched.  Files listed may include DOS's * and ? wildcards.
  160.         Paths may be specified.  Examples:
  161.  
  162.             myfile.txt
  163.             *.txt
  164.             *.*
  165.             this.c that.c other.c
  166.             *.c *.pas
  167.             C:\UTIL\*.* D:\SYS\*.*
  168.             E:\LIBRARY\*.D?C
  169.  
  170.       | You may also specify just a drive or directory name.  If you
  171.       | specify just a drive, FGREP searches all files in the current
  172.       | directory of the specified drive.  If you specify a directory
  173.       | name, FGREP searches all files in the specified directory.
  174.       | Examples:
  175.       |
  176.       |     c:      [same as c:*.*]
  177.       |     c: d:   [same as c:*.* d:*.*]
  178.       |     \src    [same as \src\*.*]
  179.       |     d:\src  [same as d:\src\*.*]
  180.       |
  181.       | You can also search all subdirectories of the directories you
  182.       | specify; see the discussion of the -r option in the "Options"
  183.       | section below.
  184.  
  185.  
  186.         File lists
  187.         ----------
  188.         If the name of a file on the command line is prefixed with an
  189.         '@' character (e.g., '@list.txt'), the file is assumed to be a
  190.         text file containing the names of files to be searched.  For
  191.         example:
  192.  
  193.             fgrep hello @files.lst
  194.  
  195.         FGREP will assume that the file FILES.LST is a text file that
  196.         contains the names of files to be searched.  Each line of such a
  197.         file should contain the name(s) of one or more files to be
  198.         searched.  Files in file lists are specified exactly as are
  199.         files named on the command line, except that you can't use
  200.         another '@' file list; that is, file lists can't be nested.
  201.  
  202.         Here is an example of a valid list file:
  203.  
  204.             this.c
  205.             c:\c\*.c d:\c\*.c
  206.             d:\misc\*.txt
  207.  
  208.         The name specified for the list file cannot contain wildcards;
  209.         that is, this is illegal:
  210.  
  211.             fgrep hello @lists.*        (WRONG)
  212.  
  213.         If you want to search for text in a file whose name begins with
  214.         an '@', use a double '@'.  For example,
  215.  
  216.             fgrep hello @@foo.txt
  217.  
  218.         will search for 'hello' in the file @FOO.TXT.
  219.  
  220.  
  221.         Redirection
  222.         -----------
  223.         If no file is listed, FGREP will take its input from the
  224.         standard input device, allowing it to be used as a
  225.         filter. For example, the command:
  226.  
  227.             DIR | fgrep pas
  228.  
  229.         would display any lines from a directory listing that contain
  230.         the string "pas".  Or,
  231.  
  232.             DIR | fgrep "<dir>"
  233.  
  234.         would list all subdirectories of the current directory.
  235.  
  236.         This command:
  237.  
  238.             pkunzip -c myzip foo.txt | FGREP somestring
  239.  
  240.         would display all lines from the file FOO.TXT in the ZIP
  241.         file MYZIP that contain "somestring" (the -c option causes
  242.         PKUNZIP to extract FOO.TXT to the console device instead of to a
  243.         disk file).
  244.  
  245.         FGREP will terminate with an error if no file is listed and
  246.         standard input is not redirected.  Otherwise, it would be
  247.         silently waiting for keyboard input, possibly leading you to
  248.         believe that it had died.
  249.  
  250.  
  251.         Examples of use
  252.         ---------------
  253.         Here are some examples of FGREP use:
  254.  
  255.         1. List all lines of MYFILE.TXT containing "hello"
  256.  
  257.             FGREP hello myfile.txt
  258.  
  259.         2. List all lines of all *.C files in the current directory that
  260.         contain "include foo.c":
  261.  
  262.             FGREP "include foo.c"  *.c
  263.  
  264.         3. List all lines from FILEA.EXT, FILEB.EXT, and FILEC.EXT that
  265.         contain the string "abcd" followed by any character:
  266.  
  267.             FGREP abcd? filea.ext fileb.ext filec.ext
  268.  
  269.         4. Display occurrences of the byte CDh followed by 21h (a DOS
  270.         call) in the program MYPROG.EXE:
  271.  
  272.             FGREP $CD21 myprog.exe
  273.  
  274.         5. Display occurrences of the string "abc" followed by a byte of
  275.         zeroes in all files in the C:\UTIL and D:\SYS directories:
  276.  
  277.             FGREP 'abc' + $00 c:\util\*.* d:\sys\*.*
  278.  
  279.  
  280.         Output
  281.         ------
  282.         FGREP's default screen output looks like this:
  283.  
  284.                 **File <filename>
  285.                 [text of lines containing string]
  286.                 **File <filename>
  287.                 [text of lines containing string]
  288.  
  289.         You can add line numbers to the display by using the -l option
  290.         (see below).
  291.  
  292.         If the "Microsoft format" option (-m or -M, see below) is used,
  293.         the output is in this format:
  294.  
  295.                 filename(linenum): text
  296.  
  297.         This format is the standard format used by Microsoft (R)
  298.         language products and by its MEGREP.  If -m is used, only the
  299.         filename and extension are displayed; if -M is used, the
  300.         complete filespec, including path, is displayed.
  301.  
  302.         When a hex byte sequence or the -b switch is specified, FGREP
  303.         uses the binary output mode.  See below for details.
  304.  
  305.         All useful output is sent to the standard output device, so it
  306.         may be piped to other programs or redirected to file:
  307.  
  308.                 FGREP target filea | yourprog
  309.                 FGREP target filea > test.txt
  310.  
  311.         Error messages and the program logo will appear always appear on
  312.         the console device, and will never appear in redirected or piped
  313.         output (unless you use the -Zl option).
  314.  
  315.         FGREP returns an errorlevel to the operating system.  It will be
  316.         one of:
  317.  
  318.             0:   String not found in any file
  319.             1:   String found in at least one file
  320.             255: Error (file read error or bad parameter)
  321.  
  322.  
  323.         Options
  324.         -------
  325.         These are the option switches that control how FGREP works.  All
  326.         switches are case-insensitive except -m/M, and -b/B; for
  327.         example, either -a or -A will set ANSI mode.  All switches must
  328.         precede the target on the command line, but they may be in any
  329.         order.  If you specify conflicting switches, the last one will
  330.         be effective.
  331.  
  332.         -a is ANSI mode.  If you have ANSI.SYS (or equivalent)
  333.            installed, escape characters (ASCII 27) in displayed text
  334.            lines can cause odd results.  If you use the -A switch,
  335.            FGREP will substitute an upside-down question mark (¿) for
  336.            ESC, possibly resulting in cleaner displays.  You'll only
  337.            need this switch if you have ANSI installed and there are ESC
  338.            characters in the files you're scanning.  Ignored in binary
  339.            mode.
  340.  
  341.         -b specifies binary search mode/output.  This switch is
  342.            automatically set if you use a hex byte sequence in the
  343.            target.  See "binary search" below.
  344.  
  345.         -B specifies a case insensitive binary search.
  346.  
  347.         -c makes the search case sensitive ("String" will not match
  348.            "string" or "STRING").  Normally, FGREP ignores case.  This
  349.            switch is ignored in binary mode.  Using -c will generally
  350.            result in faster searches.
  351.  
  352.         -e specifies that ONLY an errorlevel is to be returned.
  353.            There will be no display at all.  This is equivalent to the
  354.            combination -s0.
  355.  
  356.         -f causes the "**File" header lines to be displayed only for
  357.            those files that contain the search string.
  358.  
  359.       | -g gets a user-supplied character frequency table.  See
  360.       |    "Using your own frequency table" below.
  361.       |
  362.       | -i specifies an "input field" or "search field," allowing you
  363.       |    to search only a part of each line.  See "Limiting searches
  364.       |    to specified columns", below.
  365.  
  366.         -l adds line numbers to FGREP's output.  Ignored in binary mode.
  367.  
  368.         -m or -M specify Microsoft (R) output format.  See "Output"
  369.            above.  If -m is used, only the filename will appear.  If
  370.            -M is used, the full filespec (including drive and path)
  371.            will be included. Ignored in binary search mode.
  372.  
  373.         -o specifies a maximum output width.  It should be followed by a
  374.       |    decimal number from 0 to 50000.  For example, -o40 causes
  375.       |    FGREP to truncate all output to a maximum of 40 characters per
  376.       |    line.  If you specify -o0, no text will be displayed at
  377.       |    all.  This is not useful for the normal display, but you
  378.       |    can use this feature with -l, -m, or -M if you want to
  379.       |    display just the line numbers where the text was found but
  380.       |    not the text itself.
  381.  
  382.            Do not confuse the "o" (Output) option with the "0" (zero
  383.            text) option.  -o is ignored in binary mode.
  384.  
  385.         -p pauses on full screen of output.
  386.  
  387.       | -r recursive (subdirectory) search.  For each filespec provided,
  388.       |    FGREP searches the specified directory and all subdirectories
  389.       |    for matching file names.  If no directory is specified, FGREP
  390.       |    begins the search with the current directory.  For example:
  391.       |
  392.       |         fgrep -r "text" *.c d:\src\*.c
  393.       |
  394.       |    This command searches all *.c files in the current directory
  395.       |    and all of its subdirectories; then it searches all *.c files
  396.       |    in D:\SRC and all of its subdirectories.
  397.  
  398.         -s suppresses the "**File" header lines in the output.
  399.  
  400.       | -t displays only the actual text found (rather than the entire
  401.       |    line containing the text).  This is useful with wildcards;
  402.       |    for example, the command
  403.       |
  404.       |         fgrep -t "??rse" dict.txt
  405.       |
  406.       |    might display "parse", "purse", "horse", etc. (perhaps
  407.       |    displaying all words from a text dictionary that match the
  408.       |    pattern). Note that the displayed text will be all lowercase
  409.       |    if the search is case insensitive; and, any embedded spaces
  410.       |    will be missing if the search is white space insensitive (-w
  411.       |    option).  -t and -v (reVerse search) are incompatible.
  412.  
  413.         -v provides a reVerse or negative search.  That is, all lines
  414.            that do NOT contain the specified string are displayed.  This
  415.            provides a handy way to get rid of lines containing specified
  416.            text.  Suppose, for example, that you have a file containing
  417.            a list of file names, and you are interested in all files
  418.            EXCEPT those that contain a '$' in the name (perhaps they are
  419.            temporary files):
  420.  
  421.                 FGREP -v "$" filename
  422.  
  423.            This switch is ignored in binary mode.
  424.  
  425.         -w indicates that white space (blanks and tabs) is not
  426.            significant.  White space in both the search string and the
  427.            input file will be ignored.  If -w is specified, the wildcard
  428.            character (?) will match any nonblank character.  Ignored in
  429.            binary mode.
  430.  
  431.         -x suppresses the display of the program logo/copyright.
  432.  
  433.       | -Za causes FGREP to echo its command line arguments to the
  434.       |    standard output device. This allows the parameters to be
  435.       |    captured in redirected output files and is intended mostly
  436.       |    for use by other programs that perform post-processing on
  437.       |    FGREP output.
  438.       |
  439.       | -Zb filter "bells" from output.  Before displaying the text of
  440.       |    lines containing the target string, FGREP changes any "bell"
  441.       |    characters (character 7) to spaces, which prevents the
  442.       |    system from beeping at you.
  443.       |
  444.       | -Zd causes FGREP to display the name of each directory as it
  445.       |    begins to search the directory.  This is intended mostly
  446.       |    for recursive searches (-r option).
  447.       |
  448.       | -Zl causes FGREP to send its logo to the standard output
  449.       |    device instead of the standard error device.  This allows
  450.       |    the logo and version number to be captured in redirected
  451.       |    output files and is intended mostly for use by other
  452.       |    programs that perform post-processing on FGREP output.
  453.  
  454.         -0 ("0" text lines) suppresses the display of lines of text
  455.            containing the specified string.  FGREP will skip immediately
  456.            to the next file when the string is found.  The -0 option
  457.            is most commonly used with -f (-f0) to simply display a list
  458.            of files containing the target string.
  459.  
  460.            Note that -0 is different in effect from -o0; when combined
  461.            with -l or -m, the -o0 option will display line numbers and/or
  462.            filenames, but -0 will display nothing.
  463.  
  464.         -1 ("1" text line) specifies that only the first line containing
  465.            containing the specified string in each file will be
  466.            displayed.  FGREP will then skip immediately to the next
  467.            file.
  468.  
  469.       | -@ causes FGREP to display ONLY a list of files that contain
  470.       |    the search target.  No text is displayed or other information
  471.       |    is displayed.  This option is useful to create a file
  472.       |    containing a list of files for further processing by
  473.       |    other programs.  For example:
  474.       |
  475.       |       FGREP -@ "stuff" *.txt > list.txt
  476.       |
  477.       |    On completion of this run, the file LIST.TXT will contain
  478.       |    a list of the files that contain "stuff".
  479.  
  480.  
  481.         Binary search
  482.         -------------
  483.         If you use a hexadecimal byte sequence in your target, or if you
  484.         specify the -b or -B switch, FGREP uses a "binary" mode rather
  485.         than the usual text mode.  In this mode, FGREP is not concerned
  486.         with "lines" of text and can be used to search any file for
  487.         arbitrary sequences of bytes.
  488.  
  489.         The output format is different.  Because there are no "lines" to
  490.         display, FGREP shows the locations in the file where the target
  491.         was found and the sixteen bytes surrounding the find (eight
  492.         before, and eight after).  Here is the output format, split into
  493.         two lines:
  494.  
  495.             nnnnnnnn: n n n n n n n n . n n n n n n n n
  496.                       cccccccc . cccccccc
  497.  
  498.         The initial sequence is the 32-bit file offset where the target
  499.         was found, in hex.  For example,
  500.  
  501.             0001C47A:
  502.  
  503.         indicates that the target was found at file offset 1C47A.
  504.  
  505.         The next two series (n n n ...) represent the eight bytes before
  506.         and after the target (which, logically, occurred at the '.'
  507.         position):
  508.  
  509.             4B 7F 37 42 42 44 FF FF . 20 20 21 48 48 4F 3C 22
  510.  
  511.         The final series (ccc...) represents the same sixteen bytes
  512.         displayed as characters.  Nondisplayable characters are shown as
  513.         periods.
  514.  
  515.         Unlike text searches, binary searches are normally case
  516.         sensitive.  That is, $41 ('A') will not match $61 ('a').  If you
  517.         want a binary search to be case INsensitive ($41 matches both
  518.         $41 and $61), use -B instead of -b.  The normal case sensitive
  519.         switch (-c) is ignored.
  520.  
  521.         These switches are also ignored in binary mode:
  522.  
  523.             -a          ANSI mode
  524.             -l          Show line numbers
  525.             -m/M        "Microsoft" format
  526.             -t          Display found text only
  527.             -v          Inverse search
  528.             -w          Whitespace insensitive
  529.             -Zb         Filter "bell" characters
  530.  
  531.         Also, wildcards are not permitted in string targets when a
  532.         binary search is used.
  533.  
  534.  
  535.       | Limiting searches to specified columns
  536.       | --------------------------------------
  537.       | The -i option specifies an input search field.  You can use this
  538.       | if you are only interested in text that appears in certain
  539.       | columns of your files.  The syntax of the option is:
  540.       |
  541.       |     -i#[,#]
  542.       |
  543.       | where the first # is the starting column and the second is the
  544.       | ending column.  The second # is optional; if it is not present,
  545.       | FGREP will only find your target if it begins in the specified
  546.       | starting column.
  547.       |
  548.       | The first column of each line is column 1.
  549.       |
  550.       | Examples:
  551.       |
  552.       |     fgrep -i20,30 stuff *.txt
  553.       |
  554.       |       Looks for the word "stuff" in text columns 20 through 30.
  555.       |
  556.       |     fgrep -i1 stuff *.txt
  557.       |
  558.       |       Looks for lines that begin with the word "stuff".
  559.       |
  560.       |     fgrep -i10 stuff *.txt
  561.       |
  562.       |       Looks for lines with the word "stuff" beginning at
  563.       |       column 10.
  564.       |
  565.       | In order for text to be "found," it must appear entirely within
  566.       | the search field.  Using the first example, the only matches
  567.       | would be lines that contain "stuff" beginning in columns 20
  568.       | through 26:
  569.       |
  570.       |       1 2 2 2 2 2 2 2 2 2 2 3 3
  571.       |       9 0 1 2 3 4 5 6 7 8 9 0 1
  572.       |       s t u f f                   (No match; 's' in col 19)
  573.       |         s t u f f                 (Match)
  574.       |                     s t u f f     (Match)
  575.       |                       s t u f f   (No match; 'f' in col 31)
  576.       |
  577.       | Note that using the -i option forces FGREP to use the "slower"
  578.       | of its two search techniques (see below).  It will probably
  579.       | speed up searches that use the -L, -m/m, -V, or -W options (all
  580.       | of which also require the slower search), but it may slow down
  581.       | other searches.
  582.  
  583.  
  584.         "Fast" search technique
  585.         -----------------------
  586.         FGREP uses two different search techniques.  Both are fast, but
  587.         one is faster than the other.  The faster search will be used
  588.         UNLESS any of these conditions are met:
  589.  
  590.             - line numbers or "Microsoft" format used (-L or -m/M)
  591.             - the search is reVerse (-v)
  592.             - the search is whitespace insensitive (-w)
  593.             - the target string contains wildcards ("?")
  594.             - the search is limited to specified columns (-i)
  595.  
  596.         For other searches, the "fast" technique is typically 20-40%
  597.         faster than the "slow", although we've seen 70% improvements in
  598.         some cases.
  599.  
  600.         The technique has its roots in searching for unusual (less
  601.         frequently used) characters, so it will make more of a
  602.         difference searching for "squeeze" (q is a little-used letter)
  603.         than it will searching for "eat".
  604.  
  605.  
  606.       |            Using your own frequency tables: BUILDFT
  607.       |            ----------------------------------------
  608.       |
  609.       | In most cases, FGREP uses a built-in character frequency table
  610.       | to help find strings as fast as possible.  Because FGREP was
  611.       | originally intended for use by programmers, this frequency table
  612.       | was created by analyzing a great deal of program source code
  613.       | written in the C, Pascal, and assembler programming languages.
  614.       |
  615.       | While the table is pretty good for programmers using the above
  616.       | languages, it may not be ideal for your use, because the
  617.       | character frequencies in your files may be very different from
  618.       | the frequencies in program source code files.  You can use the
  619.       | BUILDFT program, which is included with FGREP, to create your
  620.       | own frequency tables for FGREP to use, possibly resulting in
  621.       | faster searches.
  622.       |
  623.       | Speed differences between using the default table and custom
  624.       | tables depend on several factors; in specific searches, you may
  625.       | see a big difference, a small difference, or no detectable
  626.       | difference.  In some cases, it's even possible that using the
  627.       | default table could be faster than using a custom table.  In
  628.       | other words, your mileage may vary.
  629.       |
  630.       | FGREP does NOT use a character frequency table if your search
  631.       | target contains wildcards (? characters).
  632.       |
  633.       |
  634.       | Creating frequency tables
  635.       | -------------------------
  636.       | To create frequency tables, just run BUILDFT and specify one
  637.       | or more filenames (which may include paths and wildcards):
  638.       |
  639.       |       BUILDFT file {file}
  640.       |
  641.       | The file name(s) specify which files you want BUILDFT to scan.
  642.       | It reads these files, counts characters, and stores the
  643.       | resulting frequency table in a disk file named FGREP.FT.  For
  644.       | example:
  645.       |
  646.       |       BUILDFT *.txt d:\bd\*.bas
  647.       |
  648.       | This command reads all *.TXT files in the current directory and
  649.       | *.BAS in D:\BD, counts characters, and creates a new FGREP
  650.       | frequency table in the file FGREP.FT (see below for information
  651.       | on how to use the new frequency table).
  652.       |
  653.       |
  654.       | Options
  655.       | -------
  656.       | There are several options you can use when creating frequency
  657.       | tables.  Options are not case-sensitive and may be specified in
  658.       | any order.  Multiple options must be separated by at least one
  659.       | space.  The options are as follows:
  660.       |
  661.       | The -R option causes BUILDFT to search subdirectories
  662.       | recursively, just like FGREP's -R option.  For example, this
  663.       | command counts the characters in all *.TXT files on drives C, D,
  664.       | and E:
  665.       |
  666.       |       BUILDFT -r c:\*.txt d:\*.txt e:\*.txt
  667.       |
  668.       | The -M option causes BUILDFT to merge previous character counts
  669.       | with new character counts.  Use this to merge the results of
  670.       | multiple BUILDFT runs.  The following series of commands is
  671.       | identical in effect to the previous example:
  672.       |
  673.       |       BUILDFT -r c:\*.txt
  674.       |       BUILDFT -r -m d:\*.txt
  675.       |       BUILDFT -r -m e:\*.txt
  676.       |
  677.       | The first command (which does not have the -M option) creates a
  678.       | new frequency table from the character counts of TXT files on
  679.       | drive C. The second command counts the characters in TXT files
  680.       | on drive D; because it uses -M, the new character counts are
  681.       | added to the previous counts from drive C.  The third command
  682.       | does the same thing for drive E.
  683.       |
  684.       | The -F option allows you to specify a filename other than
  685.       | FGREP.FT for the frequency table file.  For example, this
  686.       | command creates a file called C.FFT instead of FGREP.FT:
  687.       |
  688.       |       BUILDFT -fC.FFT -r *.c
  689.       |
  690.       | Finally, the -D option causes BUILDFT to display the frequency
  691.       | table after it has been created:
  692.       |
  693.       |       BUILDFT -d *.c
  694.       |
  695.       | This command builds the frequency table file and displays the
  696.       | results.  The display might look like this:
  697.       |
  698.       |       Cod Chr  Freq    Count
  699.       |       --- ---  ----    -----
  700.       |        32     65534   161601
  701.       |       101  e   6179    24716
  702.       |        42  t   4350    17400
  703.       |       ...
  704.       |
  705.       | The first column is the ASCII code for the character (e.g., the
  706.       | ASCII code for the letter 'e' is 101).  The second column is the
  707.       | character itself.  The third column is FGREP's frequency factor,
  708.       | which is the actual number that FGREP uses.  For all
  709.       | characters other than <space> (character 32), the value will
  710.       | be between 0 and 32767, with higher numbers representing higher
  711.       | frequencies (for technical reasons, the space character
  712.       | always has a frequency value of 65534).  The final column shows
  713.       | the actual number of occurrences of each character in the
  714.       | file(s) scanned.
  715.       |
  716.       | If you specify -D without any filenames to scan, BUILDFT simply
  717.       | displays the contents of an existing frequency table file
  718.       | without changing it.  Examples:
  719.       |
  720.       |       BUILDFT -d
  721.       |       BUILDFD -d -fTEXT.FT
  722.       |
  723.       | The first command displays the character frequencies from the
  724.       | default file, FGREP.FT.  The second command displays the
  725.       | frequencies from the file TEXT.FT.
  726.       |
  727.       |
  728.       | Using frequency tables
  729.       | ----------------------
  730.       | To use a frequency table created by BUILDFT, just run FGREP with
  731.       | the -g option, which tells it to "Get" the frequency table from
  732.       | FGREP.FT.  For example:
  733.       |
  734.       |       fgrep -g "stuff" *.txt
  735.       |
  736.       | If the frequency table is in a file other than FGREP.FT, or
  737.       | if FGREP.FT isn't in the current directory, specify the
  738.       | filename and/or path:
  739.       |
  740.       |       fgrep -gTEXT.FT "stuff" *.txt
  741.       |       fgrep -gC:\UTIL\FGREP.FT "stuff" *.txt
  742.       |
  743.       | Note that this method of using custom frequency tables is not
  744.       | efficient for searching small files; the extra time required
  745.       | to load the frequency table will "drown out" any improvements in
  746.       | search speed.
  747.       |
  748.       |
  749.       | Replacing the built-in frequency table
  750.       | --------------------------------------
  751.       | Alternatively, you can use BUILDFT to permanently replace
  752.       | FGREP's built-in table.  This option copies a frequency table
  753.       | from a file previously created by BUILDFT into the FGREP program
  754.       | file; after you've done this, you don't need to use the -g
  755.       | option when you run FGREP.
  756.       |
  757.       | To do this, just run BUILDFT with the -U option:
  758.       |
  759.       |       BUILDFT -u
  760.       |
  761.       | This copies the frequency table from the file FGREP.FT (the
  762.       | default name) into the FGREP program file, FGREP.COM, replacing
  763.       | the built-in frequency table.
  764.       |
  765.       | Of course, when you use the -U option (which alters the
  766.       | FGREP.COM program file), you will want to save a copy of the
  767.       | original program file somewhere!
  768.       |
  769.       | To specify a frequency table file other than FGREP.FT, use the
  770.       | -F option (just as you did when you created the table file):
  771.       |
  772.       |       BUILDFT -fTEXT.FT -u
  773.       |
  774.       | You can also use the -P (Program file) option to specify that
  775.       | the name of the FGREP program file is something other than
  776.       | FGREP.COM.  For example:
  777.       |
  778.       |       BUILDFT -pFGREPC.COM -fTEXT.FT -u
  779.       |
  780.       | This command copies the frequency table from TEXT.FT into a copy
  781.       | of FGREP named FGREPC.COM.
  782.       |
  783.       | You can use this feature to build custom versions of FGREP for
  784.       | different types of files.  For example:
  785.       |
  786.       |       copy fgrep.com fgrepc.com
  787.       |       buildft *.c *.h
  788.       |       buildft -u -pFGREPC.COM
  789.       |
  790.       | You now have a custom version of FGREP.COM (FGREPC.COM) that has
  791.       | a special frequency table just for C program source files (which
  792.       | usually have the extensions .C or .H).
  793.       |
  794.       | When you use -U, the only other options you can use are -P and
  795.       | -F; no others are permitted.
  796.  
  797.  
  798.         Notes on FGREP
  799.         --------------
  800.         1. The -f and -s switches are mutually exclusive.  If both are
  801.         specified, the last one will be effective.
  802.  
  803.         2. The -M/m and -s switches are mutually exclusive.  If both
  804.         are specified, the last one will be effective.
  805.  
  806.       | 3. The -v and -t switches are mutually exclusive.  If both are
  807.       | specified, FGREP terminates with an error.
  808.  
  809.       | 4. The -i and -w switches are mutually exclusive.  If both are
  810.       | specified, FGREP terminates with an error.
  811.  
  812.         5. If you specify the -e switch, FGREP will stop processing as
  813.         soon as a nonzero errorlevel is determined.  The -e switch is
  814.         really designed to enable other programs to determine whether or
  815.         not a specific file contains a specific string in as little time
  816.         as possible.  For example, here's an algorithm that will quickly
  817.         'touch' all files that do NOT contain a specified string:
  818.  
  819.                 for file in (*.*) do
  820.                     FGREP -e string file
  821.                     if errorlevel < 1 then touch file
  822.                 end
  823.  
  824.         6. The -s switch is automatically set when input is taken from
  825.         redirected standard input.
  826.  
  827.         7. FGREP optimizes the combination -s0 (suppress headers, no
  828.         text) to -e.
  829.  
  830.         8. If you just want to know which files contain a string, use -0;
  831.         it saves time because the rest of the file (after the first hit)
  832.         is skipped.  The combination -f0 is particularly efficient
  833.         for this as it will simply display a list of files that contain
  834.         the string.
  835.  
  836.         9. There is a maximum line length of 500 characters if any of
  837.         the -V, -W, -L, or -M switches are used; otherwise, the maximum
  838.         line length is about 60K (may be less under low memory
  839.         conditions).
  840.  
  841.         10. FGREP expects standard text files; binary files will yield
  842.         weird results unless you use the -b/B binary switch.  For
  843.         the most part, word processor documents are NOT text files; they
  844.         are special files in proprietary formats that contain a good
  845.         deal of non-text information.
  846.  
  847.         Lines can be terminated by any of CR, LF, or CR+LF.
  848.  
  849.         11. If output is redirected to disk, make sure there is enough
  850.         space available.  The program does not check.
  851.  
  852.  
  853.         A little note from the author
  854.         -----------------------------
  855.         I get lots of calls like this:
  856.  
  857.             I love FGREP because it's so fast.  It outperforms the next
  858.             fastest text search utility I have by two-to-one.  If you
  859.             could just add (regular expressions | boolean searches), it
  860.             would be ideal.
  861.  
  862.         Now, there are lots of text search programs with boolean
  863.         searches and regular expressions out there (including the real
  864.         GREPs).  I use some of them myself.  But one day it occurred to
  865.         me that 95% or more of my searches were very simple (not
  866.         requiring either feature) and that I was probably incurring a
  867.         speed penalty for flexibility that I wasn't using much.  So I
  868.         decided to write a program that would handle only these simpler
  869.         searches, but much faster.
  870.  
  871.         The main reason why FGREP is so fast is that I've been able to
  872.         highly optimize these simple searches.  If I added regular
  873.         expressions or boolean searches, this optimization would not be
  874.         possible, and the main reason for the existence of the program
  875.         (speed) would go away.
  876.  
  877.         So. I'm always glad to get comments and suggestions on FGREP,
  878.         so please keep calling and writing.  But I won't be adding
  879.         regular expressions or boolean searches.  If you need those,
  880.         there are plenty of fancier search programs available (including
  881.         the real grep).  The penalty for greater flexibility is usually
  882.         increased search time.
  883.  
  884.  
  885.         Version 1.80
  886.         ------------
  887.         Adds recursive search (-r option).
  888.         Adds ability to specify just drive/directory (assumes *.*).
  889.         Adds -i option to specify search fields.
  890.         Adds -@, -t, -Za, -Zb, -Zd, and -Zl options.
  891.         Always includes full path when displaying filenames.
  892.         Adds user-specified frequency table (-g option).
  893.         Includes BUILDFT program to create frequency tables.
  894.         Maximum value for -o option increased to 50000 from 256.
  895.         Allows -o0 to suppress text display.
  896.         Corrects a problem in parsing hex targets and allows
  897.           single-digit hex characters (e.g., $A instead of $0A).
  898.         Uses character frequency table in all searches unless wildcards
  899.           are present in the search target.
  900.         Includes 386-only version of FGREP.COM.
  901.         Corrects a problem in earlier versions that sometimes caused
  902.           FGREP to incorrectly report insufficent memory.
  903.         Now requires DOS 3.0 or later.
  904.  
  905.         Version 1.72
  906.         ------------
  907.         Fixes problem with DOS 2.x, unable to read files.
  908.  
  909.         Version 1.71
  910.         ------------
  911.         Adds file lists.
  912.         Adds file sharing support.
  913.         Corrects two bugs in binary mode display: displaying data beyond
  914.             end of file, and skipping bytes immediately after the
  915.             target.
  916.  
  917.         Version 1.70
  918.         ------------
  919.         Adds binary search.
  920.         Adds target concatenation (target+target).
  921.         Cancels if no file specified and not redirected.
  922.  
  923.         Version 1.64
  924.         ------------
  925.         Bug fix release only: fix garbage in -M display from 1.63
  926.  
  927.         Version 1.63
  928.         ------------
  929.         Distinguish between -M (path) and -m (no path) switches.
  930.         -M/-m and -S now mutually exclusive.
  931.         Allow search for literal '?' character via '\?'.
  932.  
  933.         Version 1.62
  934.         ------------
  935.         Added -M switch.
  936.         Increased max length of lines ("slow" search) from 256 to 500.
  937.  
  938.         Version 1.61
  939.         ------------
  940.         Fixed a problem with pausing on > 255 hits (-P not specified).
  941.  
  942.         Version 1.60
  943.         ------------
  944.         Added -P switch.
  945.         Fixed a problem with tab characters and -O switch.
  946.  
  947.         Version 1.59
  948.         ------------
  949.         Added -O switch.
  950.         Altered -L operations to allow for line numbers > 65535.  Line
  951.         numbers now right justified in a 6-character field.
  952.  
  953.         Version 1.58
  954.         ------------
  955.         Fixed two problems that were causing endless loops in 1.55-1.57.
  956.         Added -A switch.
  957.  
  958.         Version 1.57
  959.         ------------
  960.         Added -X switch.
  961.  
  962.         Versions 1.55/1.56
  963.         -----------------
  964.         "Fast" search algorithm added (thanks to Dave Angel for the
  965.             idea and the shove).
  966.         Fixed problems with redirected input.
  967.         Forced -v (reVerse) search to show blank lines.
  968.  
  969.         Versions 1.50/1.51
  970.         ------------------
  971.         These versions contain no new features but are significantly
  972.         faster than earlier versions.  Standard (case-insensitive)
  973.         searches run about 40% faster than 1.45 (which was 25-30%
  974.         faster than 1.40).  "Literal" searches (case-sensitive and
  975.         spacing-sensitive) are highly optimized and may be as much as
  976.         70% faster than 1.45.
  977.  
  978.         Version 1.45
  979.         ------------
  980.         We found a few areas that could be made more efficient.  This
  981.         version can be as much as 25-30% faster than version 1.40.
  982.  
  983.         The -L (line numbers) option was added, and improvements made to
  984.         parameter parsing such that delimiters are not always necessary.
  985.  
  986.  
  987.         Copyright/License/Warranty
  988.         --------------------------
  989.         This document and the program files FGREP.COM and BUILDFT.COM
  990.         ("the software") are copyrighted by the author.  If you are an
  991.         individual, the copyright owner hereby licenses you to:  use the
  992.         software; make as many copies of the program and documentation
  993.         as you wish; give such copies to anyone; and distribute the
  994.         software and documentation via electronic means.  There is no
  995.         charge for any of the above.
  996.  
  997.         However, you are specifically prohibited from charging, or
  998.         requesting donations, for any such copies, however made; and
  999.         from distributing the software and/or documentation with
  1000.         commercial products without prior permission.  An exception is
  1001.         granted to not-for-profit user's groups, which are authorized to
  1002.         charge a small fee (not to exceed $7) for materials, handling,
  1003.         postage, and general overhead.  NO FOR-PROFIT ORGANIZATION IS
  1004.         AUTHORIZED TO CHARGE ANY AMOUNT FOR DISTRIBUTION OF COPIES OF
  1005.         THE SOFTWARE OR DOCUMENTATION, OR TO INCLUDE COPIES OF THE
  1006.         SOFTWARE OR DOCUMENTATION WITH SALES OF THEIR OWN PRODUCTS.
  1007.  
  1008.         THIS INCLUDES A SPECIFIC PROHIBITION AGAINST FOR-PROFIT
  1009.         ORGANIZATIONS DISTRIBUTING THE SOFTWARE, EITHER ALONE OR WITH
  1010.         OTHER SOFTWARE, AND CHARGING A "HANDLING" OR "MATERIALS" FEE OR
  1011.         ANY OTHER SUCH FEE FOR THE DISTRIBUTION.  NO FOR-PROFIT
  1012.         ORGANIZATION IS AUTHORIZED TO INCLUDE THE SOFTWARE ON ANY MEDIA
  1013.         FOR WHICH MONEY IS CHARGED.  PERIOD.
  1014.  
  1015.         Businesses, institutions, and governmental entities must obtain
  1016.         a specific license agreement from The Cove Software Group in
  1017.         order to use the software.
  1018.  
  1019.         No copy of the software may be distributed or given away without
  1020.         this document; and this notice must not be removed.
  1021.  
  1022.         There is no warranty of any kind, and the copyright owner is not
  1023.         liable for damages of any kind.  By using this free software,
  1024.         you agree to this.
  1025.  
  1026.         The software and documentation are:
  1027.  
  1028.                            Copyright (C) 1985-1993 by
  1029.                              Christopher J. Dunford
  1030.                             The Cove Software Group
  1031.                                  P.O. Box 1072
  1032.                             Columbia, Maryland 21044
  1033.  
  1034.                               Tel: (410) 992-9371
  1035.                              CompuServe: 76703,2002
  1036.                       Internet: 76703.2002@compuserve.com
  1037.