                                TSP Manual

Text Search and Print V2.19a:
Searches for a string of text in a file or files.
Optionally sends results to Printer or to a file.

TSP [@][drive:][path]filename target_string [/C] [/AW] [/AP] [/1] [/B] [/S] [/L:outfile.ext]

  [drive:][path]filename   File specification including wildcards.
  @[drive:][path]filename  Search list of file specification(s) in filename.
  target_string            String to be searched for.
  /C                       Specifies case-sensitive search,
                               default mode ignores case.
  /AW                      Automatically write results to file.
  /AP                      Automatically send results to Printer.
  /1                       Find first occurrence of target_string in each file.
  /B                       Write results to Brief .APX file in First-Only mode.
  /S                       Searches subdirectories under specified directory.
  /L:outfile.ext           Name of output file. Default name is FOUND.TSP.
                           The extension is always .APX when /B switch is used.

Options can appear in any order on the command line.
(Can use - instead of / and options are not case sensitive).

The easiest way to use tsp is just to specify a file spec. and what you are
searching for. Some examples:

        TSP *.foo bar
        TSP *.txt "foo bar"
        TSP *.c \"ok\"        ( is looking for "ok", "OK", "oK" and "Ok" )
        TSP "*.c *.h" foobar  ( look for foobar in *.c, then in *.h)

Note in example two that if the pattern you are looking for includes spaces,
it must be enclosed in quotes.  If the pattern you are looking for contains a
quote, the quotes must be preceeded by backward slashes as in example three.
To search more than one file spec, enclose them in quotes with a space, tab
or comma separating them as in example 4.

If you ran example 3 from the D:\C700\FILES directory you might see something
like this (it loses something without the colors).


                             Text Search & Print

Search For: "OK"

File Name : D:\C700\FILES\JSI_CONV.C

Match Found at Line #   649
--------------------------------------------------------------------------------

   ushort x,left,right,lastfgd,newfgd;
   ushort oldtop,oldleft,oldbottom,oldright;
   ushort top = 8, bottom = top+4;
   int lastcursor, retval;
   long lastbgd,newbgd;
   static char *ok_msg = "OK";
   char *sScrn;

   lastfgd = _gettextcolor();
   lastbgd = _getbkcolor();
   oldpos = _gettextposition();



   Edit    Continue    Next file    Write info to file    Print info    Quit

The string "OK" would be highlighted and 5 lines before and 5 lines after the
matched line are displayed.  At this point you have several options.  Press
the first letter (highlighted) of the desired option to execute it or press
the Esc key to quit.

Edit: Opens the current file in an editor.  The default editor is Brief, but
      if you wish to use another editor, set the TSPEDIT environment variable
      to the name of your editor.  For example to use the DOS editor:

		set TSPEDIT=EDIT

      TSP parses the TSPEDIT environment variable and substitutes the current
      file name for %f and the current line number for %l.  If %f is not
      found in the TSPEDIT variable, the current file name is appended to
      the end of the command string.  Here are some examples, the current
      file is foo.txt and the current line number is 123:

	set TSPEDIT=EDIT %%f /B     	will run EDIT foo.txt /B
	set TSPEDIT=B -g%%l		will run B -g123 foo.txt
	set TSPEDIT=Q %%f -n%%l		will run Q foo.txt -n123

      Note: when using the DOS set command, %%f will yield %f in the actual
      environment variable.

      When you are done editing the file TSP will not return to that file,
      but will continue searching with the next file meeting the file
      specification.

Continue: Will resume search for target string in the same file, unless the
          /1 option was used, then Continue will be the same as Next file.
          The /1 option is most usefull with the /AP or /AW options
          (see below).

Next file: Will resume searching in the next file meeting the file spec.
           and ignore the rest of the current file.

Write info to file: If the /B switch is not used it will write to the
                    file specified by the /L switch, or to FOUND.TSP if
                    no output file is specified, in the following format:

"OK" found in file D:\C700\FILES\JSI_CONV.C on line 649
   static char *ok_msg = "OK";

                    If the /B switch is used, it will write to the
                    file specified by the /L switch, or to FOUND.APX if
                    no output file is specified, in the following format:

D:\C700\FILES\JSI_CONV.C ;|D:\C700\FILES\JSI_CONV.C

                    This is the format required by the dBrief macro package
                    for its APX feature.

Print info: Same as Write info to file except output is directed to stdprn.
            (Normally LPT1).

Quit: Stop running TSP.


Other command line options:
Note: If you specify more than one option there must be a space between
options. For example:

         TSP *.prg net_use -b -aw /c

@filename.ext: filename.ext contains a list of file specifications each of
               which are run through TSP in turn. Default extension is .CLP
               for filename.ext and .* for file names inside filename.ext.
               For example, if you entered:

               TSP @my_clp fopen

               and my_clip.clp contained:

                main
                sub1
                \clipper5\common\laser.prg

                TSP would search for the pattern fopen, without regard to
                case, in main.*, sub1.* and \clipper5\common\laser.prg.

/C: Specifies a case-sensitive search, normally case is ignored during
    searches (everything gets coverted to uppercase).

/1: Stop searching the current file after the first match of the search
    pattern. If using /AW or /AP TSP will go directly to the next file,
    otherwise will bring up the main screen before going to the next file.

/B: Writes to file or printer will be in dBrief APX format. Proceeds to the
    next file after writing.

/AW: Writes hits to the appropriate file without bringing each hit up
     on the screen.  The format written to the file is discussed above under
     Write info to file.  Use with the /B switch to create .APX files quickly.

/AP: Writes hits to the printer without bringing each hit up on the screen.
     The format written is discussed above under Write info to file.
     Use with the /1 switch to only print one match per file.  If you
     use the /AP switch and the /AW switch at the same time, output will
     go to both the printer and the file.

/S: Also searches all directories under the current directory.

/L:outfile.ext: Specifies name of output file. Default name is FOUND.TSP if
                /B switch is not used and FOUND.APX if /B is used. The
                extension will always be .APX if the /B switch is used even
                if you specify another one.


New for version 2.19a
Fixed a bug where if the file specification was through a file,
(e.g. tsp @file.lst somestring)	and a file was edited, it wouldn't finish
processing the file specification file.

New for version 2.19
Can search more than one file specification at a time. Improved support
for editors other than Brief (requested by Lechee Lai).  TSP now parses
TSPEDIT environment variable and substitutes the current file name for
%f and the current line number for %l.

New for version 2.18
With previous versions if your search string started with - or / tsp
would flag this as an invalid option error.  Now it will handle it.

Paul Bosselaers
paulboss@erols.com
1/4/00

