
                    Documentation to FSEARCH V7.4
                    -----------------------------
                      written by Mark Davidson


This text forms the documentation to FSearch and describes the features 
and use of this program.

FSearch was written by Mark Davidson with Lattice C 5.6 extending the 
program written by Stephan Gerle.

**********************************************************************
*                          Important                                 *
*                                                                    *
*    This version of FSearch may be distributed freely on bulletin   *
*    boards and PD libraries. It can also be cover mounted by any    *
*    magazine.                                                       *
*    PROVIDED THAT:                                                  *
*                                                                    *
*    - No UK magazine may cover mount this without my permission     *
*    - all files listed below are included;                          *
*    - the copyright of the author is acknowledged;                  *
*    - no charge is made other than reasonable disk/administration   *
*      charges by PD libraries.                                      *
*                                                                    *
*    The Files should be:                                            *
*           FSEARCH.PRG  FSearch program                             *
*           FSEARCH.RSC  and resource                                *
*           FSEARCH.HYP  ST-Guide hypertext for FSearch              *
*           FSEARCH.REF  and REF file                                *
*           FSEARCH.TXT  Plain text version of the hypertext         *
*           README       FSearch readme                              *
*                                                                    *
**********************************************************************


Criticisms and suggestions to:
        Mark Davidson
        75 Chiltern Avenue
        High Wycombe
        Bucks HP12 3UW
        England
        
        E-mail: mdavidsona@cix.compulink.co.uk
        

Introduction ---------------------------------------------------------

 FSearch is a file find and grep (pattern searching) program. This 
 program is mainly of use on a hard disk, where files can be lost all 
 too easily. Also patterns and words can be searched for within files, 
 this is very useful for finding function calls etc within your source 
 code.

 The program runs as both an Accessory as well as a normal program. 
 This can be done by renaming it to FSEARCH.ACC or FSEARCH.PRG.
 
 If run as an ACC the Found List Window is limited to 1200 lines.


Main Dialog ----------------------------------------------------------

 The uppermost textfield is for the drive, path and file mask. The 
 drives and path are optional. Double clicking on this field brings up 
 a fileselector. The file name mask can be made up using unix like 
 regular expressions. 

 For example:
 CD:\TC\*.[CH]
 This would search on drives C and D for all files ending in a .C or .H 
 within TC directories.

 The exact format is:
 [Drives][Path]Mask

 If no path is indicated, it is assumed to be \. If no drives are 
 indicated, then all drives are searched.

Grep

This allows you to search for strings within the files.

RegExp

 Allows the use of regular expressions in the Grep line.
 For example:
 
   Grep Line:  FSE?RCH
   
   If RegEXP is selected then Fsearch would find:
               FSEARCH
               FSEERCH
               Fsefrch etc
               
   If RegExp is not selected, then Fsearch would only find strings 
   containing the question mark:
               FSE?RCH
               fse?rch  etc

 NB Searching for 'Regular Expressions' in binary files is not really 
 supported.

Recursive

 Recursively search sub directories.
 
Files Only

 When using grep, only the paths of files in which the pattern is found 
 are shown.
 
Skip Binaries

 Skip files which are in binary format when using grep.

X-Mask

 This brings up the Extended Mask dialog.

Process List
 
 This brings up the Process List dialog.

Options

 This brings up the Options dialog

Search

 This starts the search and opens the Found List Window. If a search is 
 already in progress, then it will ask if you want the search stopped.

Extended Mask --------------------------------------------------------

Date
 Search files between given dates.

Time
 Search for files between given times.
 NB This option does not make much sense unless a single day is chosen 
 in the Date selection.
 
Length
 Search for files greater or smaller than a given size.

File Attributes
 Search for files with certain attributes set or unset.

Process List ---------------------------------------------------------

Delete

 Deletes all found files. NB it checks if you are sure first.

Touch

 Sets the date and time on all found files to the current date and 
 time.

Copy
 Copies the files found into a new directory. NB This does not copy the 
 directory structure, just the files.

Move
 This copies and then deletes the files as per Copy. NB directories are 
 not deleted, just the files.

Search and Replace

 This puts up a dialog which asks for:
   Find: This is the string that will be searched for (NB case sensitive)
   Replace: This is the replace string it must be shorter or of equal 
            length to the find string.
   Null/Space: If the replace string is shorter then this character 
               will fill up to the length of the find string.
   
   As in other process list options this will search and replace in all 
   the files in the current list.
 
Save

 Saves the list of files to the specified file. If the file already 
 exists then a dialog will ask if you want to append or overwrite the 
 file.

Save to Clipboard

 Saves the list of files to the clipboard.

Print List

 Prints the list of files.
       
Options --------------------------------------------------------------

Small Text
 Use the small font if no font has been selected, or half the size of 
 the current font if possible.

Change Font
 At present this uses UFSL, the Universal Font Selector AUTO program 
 should be installed. If you have not got this then you could edit the 
 Configuration File.
 
Double Click
Double Click Right Shift
Double Click Left Shift
 These popups define the action when these operations are performed in 
 the List Window. The current options are:
   AVSTART          - On a single tasking system, this will send an 
                      AVSTART message to the main program. If the main 
                      program is a desktop that supports the VA 
                      protocol then it will start the appropriate 
                      program for the type of file you have double 
                      clicked on, if the main program is a program that 
                      supports the VA protocol, then it will attempt to 
                      open a window containing the file you have double 
                      clicked on. If you are running a multi-tasking 
                      system, then AVSTART will only be sent to a 
                      desktop that supports the VA protocol (eg GEMINI 
                      or EASE)
   AVOPENWINDOW     - This tells a desktop that supports the VA 
                      protocol to open a file window at the path of the 
                      selected file.
   ST-GUIDE         - This sends the selected file to ST-GUIDE.
   1ST-GUIDE        - This sends the selected file to 1ST-GUIDE.
   USER             - If USER is chosen, then FSearch will attempt to
                      the USERDEF slot with start the program in a
                      VASTART call. Programs I include the defaults have
                      tested this with EDITRESS (Edith), EVEREST and
                      GEMVIEW.

Background Search On
 If this is selected, then the pointer stays as an arrow while the 
 search continues. If unselected the pointer changes to a busy bee and 
 you have to wait for the search to finish.

Save Configuration
 Save the Fsearch configuration file in FSEARCH.INF

Found List Window ----------------------------------------------------

 If the close button is clicked on while still searching a dialog will 
 appear on which you can choose to stop searching. The escape key also 
 does this.

 Files found are listed as:
 FileDate FileSize FilePath

 When using grep found lines are listed as:
    LineNumber  Text    (for text files)
    FileOffset  Text    (for binary files)

 The found list window can communicate with other applications. See the 
 Options Dialog for more information.

Regular Expressions --------------------------------------------------

 A Regular Expression defines the pattern that will be searched for.
 Fsearch ignores case when pattern matching.
 
 Within a regular expression any character not defined below has to 
 match exactly.
 
 ^  A ^ at the beginning of the expression only matches at the beginning 
    of a line.
    
 $  A $ at the end of the expression only matches with the end of a line.
 
 ?  A ? matches with any normal character.

 :  A : defines the beginning of a class. ':a' defines the class of all 
    characters a-z. ':d' defines the class of 0-9. ':n' defines the 
    class of all alphanumerics. ': ' defines the class of all white 
    space (that is space, tab, newline etc)
 
 *  A * matches an arbitrary number of arbitrary characters.
 
 +  The + sign goes after an expression and means match with 1 or more 
    of the expression.
    
 -  The - sign goes after an expression and means 0 or 1 of the 
    expression.
    
 [] A string in angular brackets matches with any character that occurs 
    between the brackets. If a ^ character is the first character after 
    the [ then any character that not not appear between the brackets 
    is matched. A range can be defined with -, for example [a-z] 
    matches with any character form a to z.
    
    Some Examples:
    
    [dr]e?d    would match with dead, deed, read, dezd but not feed
    fe+d       would match with fed, feed, feeed but not fd
    fe-d       would match with fed, fd but not feed
    [^dr]eed   would match with feed but not reed or deed 

Configuration File ---------------------------------------------------

The configuration file is saved as FSEARCH.INF, I would recommend not 
altering it except through FSearch itself as the ordering is important. 
But if you really want to, here is the description of it:

FSearch Inf V3.7      This is the config file version
Path00=G:\*.*         Path and Grep lines are the popup lines
Grep00=Empty          from the main fsearch dialog.
.
.
.
Path09=Empty
Grep09=Empty
CurrentPath=0         Current Path
CurrentGrep=0         Current Grep
FontId=1              Window font id
FontSize=12           Window font size
GrepFlag=FALSE           -+
RecursiveFlag=TRUE        |
SmallTextFlag=TRUE        |
RegExpFlag=FALSE          +-- Various flags
SkipBinariesFlag=FALSE    |
FilesOnlyFlag=FALSE       |
BackgroundFlag=TRUE      -+
ListWindow=94;95;450;273 -+
MainDial=36;157           |
AboutDial=136;125         +-- Window positions
OptionsDial=176;93        |
XmaskDial=120;85          |
ProcessDial=188;97       -+
DoubleClick=1            -+
DoubleClickLeft=2         +-- Double click popup settings
DoubleClickRight=3       -+
UserDef=EDITRESS         -+
UserDefL=GEMVIEW          +-- UserDef settings
UserDefR=EVEREST         -+

If you mess up the config file, just delete it and Fsearch will use 
it's default settings.

History --------------------------------------------------------------

 FSearch was first written by Stephan Gerle, who developed the program 
 until 1994, then Stephan found himself too busy to continue. Ofir Gal 
 then put a message on Cix to find someone else to support it. I said 
 yes.
 I then got in contact with Stephan and he sent me his source. 
 Unfortunately, Stephan had recently had a hard disk crash and so the 
 source was for v5.2, while v6.2 was the latest executable. So if there 
 is anything in v6.2 that you find is missing in this version, sorry.
 This version has some very major changes to previous versions, I hope 
 you like it.

 I'd like to say thanks to Stephan for the source, to Ofir Gal for 
 getting me and Stephan together, and to the other testers: 
 John Upstone, Mark Baines, Joe Connor, Oliver Skelton, Daron Brewood, 
 Ofir Gal, Martyn Dryden.


  Mark Davidson 1994
  
  mdavidsona@cix.compulink.co.uk

