### findgrep-1.0 README file

    Readme file for: findgrep

    Programme: findgrep

    grep's in current as well as in subdirectories.
    Perl reg.exp.s can be used. Supports approximate matches.

    usage:

      findgrep [-lnisefcpdtBhaFSx] <reg.exp.> [<file name reg.exp.>]

    Author: Lars Gregersen
            E-mail:   lg@kt.dtu.dk
            Homepage: http://www.gbar.dtu.dk/~matlg/

    findgrep webpage: http://www.gbar.dtu.dk/~matlg/findgrep/

    1997.10.01, version 1.00: Creation of a great new programme
    1997.10.07, version 1.10: added -s option
    1997.10.08, version 1.20: added -e, -f and -c options
    1997.10.22, version 1.30: added -p option
    1997.11.05, version 1.31: changed option -c to -b
    1997.11.07, version 1.40: added -P, -d, -t and -B option
    1997.12.17, version 1.41: runs nicely with Perl -w option
                              added -h option
    1998.03.12, version 1.50: added -a, --adiff, --ains, --adel
                               and --asub options
                              changed the handling of the -t option
                              now uses Getopt::Long to handle options
                              env.var. FINDGREP contains default arguments
                              removed option -P
                              added option -F
    1998.04.09, version 1.60: fixed bug with -i option
                              fized bug: added 'local $_' to build_matchany
                              addapted to String::Approx version 2.5
    1998.07.28, version 1.61: allowed "cpp,h" when using -e option
                              will now give an error message and
                               continue when an unreadable file is met
    1999.01.31, version 1.63: added option -S (show paragraph)
                              -f now handles ..
                              adapted to String::Approx version 3.05
                               (works with version 2.5+)
    1999.02.07, version 1.64: bug fixes for options -S and -s
                              -S option may now take an integer as argument
    1999.04.19, version 1.70: added option -x

    findgrep [-lnisefcpdtBhaFSx] <reg.exp.> [<file name reg.exp.>]

     Options:
      -l : list file names
      -n : line numbers
      -i : case insensitive
      -s : shorten long lines
      -e : treat file name reg.exp. as an extension
      -f : use directory names in file name reg.exp.
           and convert . to \. and * to .*
      -b : only search base directory
      -p : write path name with the file names
      -d : match file name reg.exp. on path name and
           file name (concatenated)
      -t : transform file names to lower case
      -B : don't search binary files
      -h : help screen
      -a : approximate search
      -F : use pattern file
      -S : show paragraph
      -x : exclude file/directory pattern

    Options can be specified in the environmental variable FINDGREP just
    like on the command line. Options given in the FINDGREP variable will
    be overridden by the options given on the commandline.

    An option can be turned off on the command line bu specifying '--no'
    before the option letter. E.g. if you have specified 'FINDGREP=-n' the
    numbering can be turned of on the command line using '--non'.

    The options have the same effect whether specified on the command line
    except for the approximate match modifiers. See approximate match for
    a specification.

    On DOS systems the following definition in autoexec.bat is often
    useful
    set FINDGREP=-t

    Description of options:

     -l : list file names

    List only the filenames of the files that have lines that match the
    criteria. If used in combination with the -n option the lines numbers
    of the first matching line is shown.

     -n : line numbers

    Show line numbers of matching lines.

     -i : case insensitive

    Do a case insensitive search. This makes the regular expresions case
    insensitive for both the search pattern and the path and file name
    pattern.

     -s : shorten long lines

    Show only a few lines of text around the place where some matching
    text is found. This feature is useful when searching binary files
    that do not have "standard" end of line chracters.

     -e : treat file name reg.exp. as an extension

    Use the file name specification as an extension (suffix) instead of a
    regular expression. That means that "cpp" will be tranferred into
    "\.cpp$". You may specify more than one extension by using "(h|cpp)",
    which will search files that have either "h" or "cpp" as extension.
    When used with the -f option the last part of the file name
    specification will be used as the extension.

     -f : use directory names in file name reg.exp.
          and convert . to \. and * to .*

    Make it possible to specify the base directory for the recursive
    search. The remeaning part of the file name specification will have
    the characters "." and "*" translated into "\." and ".*" respectively
    and in that order. This makes it easier to specify file names in a
    'glob' kind of way. But remember that regular expressions are still
    used.

      Examples:

    Search for the pattern "foo" using bar as base directory in all files that matches the pattern "filename"
      findgrep -f foo bar/filename

    Search for the pattern "foo" in files that start with "bar" and
    has the extension "h", but note that a file called "foobar.h.bak"
    will also be found by this search criterion. The search criterion
    used is "bar.*\.h".
      findgrep -f foo "bar*.h"

    Search for the pattern "foo" in a file that has "bar" in it followed by a number somewhere using the directory "tmpdir" as the base directory.
      findgrep -f foo "tmpdir/bar*\d"

    Search for the pattern "foo" in files that matches the pattern bar using the previous directory as base directory.
      findgrep -f foo ../bar

     -b : only search base directory

    Only search the base directory. This makes findgrep work almost as
    grep.

     -p : write path name with the file names instead of
          in seperate lines

    The normal output of findgrep is to first specify the directory where
    the search is made and then to write the file names without directory
    names. The -p option changes this so the directory names are written
    with the files.

     -d : match file name reg.exp. on path name and
          file name (concatenated)

    Instead of just matching the file name the file name reg.exp. must
    match the path name and the file name when they are concatenated

    Example:

    search for "foo" when the path name and file name will match
    "bar.*foo". Will e.g. match "bar/somedir/foo".
      findgrep -d foo "bar.*foo"

    searh for "foo" using the "dir1" as base directory and looking for
    files which have a path name (relative to the current file
    directory) and file name that matches "bar*txt". It will e.g. match
    "dir1/dir2/bar/readme.txt"
      findgrep -fd foo "dir1/bar*txt"

     -t : transform file names to lower case

    File names and path names are transformed to lower case before using
    in tests and when printing. The case is preserved when opening files.
    Useful on file systems that do not distinguish between (but allow)
    upper and lower case (like Windows 96/NT).

     -B : don't search binary files

    Don't search files that appear to be binary.

     -h : help screen

    Print a help screen with the most commonly used options.

     -a : approximate search

     Search for approximate match. This is good for searching for
     misspelled
     information and when you don't know the precise spelling of words.
     Warning: the approximate search takes much longer time than the
     normal
     search. Note that String::Approx must be installed for this to work.

     --adiff, --ains, --adel --asub

    Approximate is defined here as k-differences.  One difference
    is an insertion, a deletion, or a substitution of one character.
    The k in the k-differences is the maximum number of differences. The
    default is to allow for one difference. This can be changed using the
    modifiers above.

    Approximate matching will automatically be used when any of the
    modifiers are specified on the command line. This means that the -a
    option can be left out. If the modifiers are specified in the FINDGREP
    environmental variable the approximate match is not used unless the -a
    option is specified. This feature allow one to specify defaults of the
    modifers.

     Examples

    Search for 'Tschaikowskij' with one difference
      findgrep -ea Tschaikowskij

    Search for 'Tschaikowskij' with one substitution and no deletions or
    insertions
      findgrep -e --adiff=0 --asub=1 'Tschaikowskij'

    FINDGREP contains '--adiff=2' and we want to search for
    'Tschaikowskij' with 1 insertion, 2 deletions and 2 substitutions
      findgrep --ains=1 Tschaikowskij

     -F : use pattern file

    Use the pattern in the specified pattern file for searches. A regular
    expression cannot be specified on the command line if this option is
    used. The pattern in the pattern file are separated by newlines.

     Example
    The file 'pattern.ptn' contains:
    red
    blue
    green

    Use findgrep to find these words in text files:
      findgrep -e -Fpattern.ptn txt

      -S : show paragraph

    The standard output of findgrep is a single line where the matching
    text if found. This is out of context with the rest of the text/file.
    By using the option -S the entire paragraph where the matching text is
    found will be displayed. findgrep uses an empty line to determine where
    paragraphs start and end. Note that this option can create a lot of
    output if paragraphs are long. This option can be combined with the -s option.

    If used in combination with the -n parameter the line number of the first matching line is shown with the file name (note that there can be more than more match in a paragraph); the line number of the lines in the paragraph will be shown as well.

    When the -S option is used the number of lines in a paragraph is limited to a default of 100 lines. This number can be changed using the option
      -S=<number>

     Example
    A search for the word "foo" showing only entire paragraphs when the paragraph is smaller than 25 lines.
      findgrep -S=25 foo
    If paragraphs larger than 25 lines is encountered only the matching line is shown.

      -x : exclude file/directory pattern

    Use this option to exclude files and/or directories that is otherwise included. File names and directories must first positively match their respectively specified patterns before this pattern is checked.

     Example
    Search for "foo" in .ini files, but exclude files that contain "system"
      findgrep -e -x="system" foo ini
    Note that this search expression will search for files in directories containing "system".

    Search for "foo" in .ini files, but exclude directories that contain "system"
      findgrep -ed -x="/system/" foo ini
    Note that this search expression will search for files that contain the phrase "system".

    Search for "foo" in .ini files, but exclude paths that contain "system". I.e., do not contain "system" in the directory name or file name.
      findgrep -ed -x="system" foo ini