home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tsd050.zip / TSD.DOC next >
Text File  |  1995-04-04  |  5KB  |  165 lines
  1.  
  2.                 TSD - C-oriented search utility
  3.                 ===============================
  4.  
  5.                        Version: 0.5
  6.                        File: TSD.EXE
  7.                        Size: 21834 bytes
  8.                        Date: 4/4/95
  9.                        Status: freeware
  10.  
  11.                     (C) Andrey Kogan, 1995
  12.                    E-mail: kogan@delphi.com
  13.  
  14.  
  15.  
  16. TSD program is useful when working with a big project
  17. containing hundreds of C-language source files. It allows you to
  18. find the definition of function or global variable. Standard
  19. text search utility may be inconvenient in this case, especially
  20. if the function you are trying to locate is called from many places.
  21.  
  22. TSD command has the following syntax:
  23.  
  24.         TSD     file_where_to_search    word_to_search_for
  25.  
  26. The first parameter may contain wildcards. All subrirectories
  27. of the specified directory will also be searched.
  28.  
  29. The second parameter contains valid C identifier. Files will be
  30. searched for the case-sensitive match of the whole word.
  31. Within each file, only global scope will be searched.
  32.  
  33. Example:
  34.  
  35.         TSD D:\*.C MyWord
  36.  
  37. This command will search for the definition of "MyFunction" in
  38. all C-files on drive D. Then it will display an appropriate
  39. fragment on the screen and prompt user for the next search.
  40.  
  41. Example of the fragments which will be shown:
  42.  
  43.         // 1. Prototype in global scope.
  44.         void MyWord(int a);
  45.  
  46.  
  47.         // 2. Function body.
  48.         void MyWord(int a){
  49.           // ...
  50.         }
  51.  
  52.  
  53.         // 3. Variable declaration in a global scope.
  54.         int MyWord;
  55.  
  56.         void f(){
  57.           // ...
  58.         }
  59.  
  60.  
  61.         // 4. Simple macro.
  62.         #define MyWord (something)
  63.  
  64.         // 5. Macro with parameters.
  65.         #define MyWord(a,b,c) my_fun(1,a,b,c)
  66.  
  67.  
  68. Example of the fragments which will NOT be shown:
  69.  
  70.         // int MyWord; - comments are ignored
  71.         /*
  72.            void MyWord();  // comments are ignored
  73.         */
  74.         flt MyWORD;     // different identifier - match is case sensitive
  75.         char MyWord_2;  // different identifier - the whole word must match
  76.  
  77.         void f(){
  78.           int MyWord; // local variable
  79.         }
  80.  
  81.         g(){
  82.           MyWord(x);    // function call, not a definition
  83.         }
  84.  
  85.         #define MY_MACRO() MyWord()     // function usage, not a definition
  86.  
  87.  
  88.  
  89.                     Using TSD in batch files
  90.                     ------------------------
  91.  
  92. Program returns nonzero ERRORLEVEL if and only if search was aborted
  93. by user. In any other case ERRORLEVEL is zero. This feature allows
  94. to chain several TSD commands which will behave as a single one.
  95.  
  96. Example. Let's define FINDDEF command which will search all *.C
  97. and *.H-files under CPROJ directory of drive C.
  98. Here is a proposed text of FINDDEF.BAT:
  99.  
  100.         TSD C:\CPROJ\*.C %1
  101.         IF NOT ERRORLEVEL 1 TSD C:\CPROJ\*.H %1
  102.  
  103.  
  104.  
  105.  
  106.              NOTE: TSD is executed in "background"
  107.              -------------------------------------
  108.  
  109. When TSD finds a match, it displays an appropriate fragment of
  110. text on the screen, asks user "Continue search ?" and continues
  111. search immediately. Thus, if user will answer "Yes" after some
  112. pause, next match would probably be already found. The only
  113. visible effect of this background search is a flashing hard
  114. disk access indicator.
  115.  
  116.  
  117.  
  118.                 When TSD doesn't work properly
  119.                 ------------------------------
  120.  
  121. TSD contain no C parser nor C preprocessor. It works properly
  122. if:
  123.  
  124. 1. Searched file contains correct C-program.
  125. 2. Each macro expansion has balanced brackets.
  126. 3. Program doesn't contain nested comments (this
  127.    limitation will probably be eliminated in next version).
  128.  
  129. Improper text will result in extra "Match found" screens.
  130. Example:
  131.  
  132.         #define BR_OPEN  {
  133.         #define BR_CLOSE }
  134.  
  135.         void f()
  136.         BR_OPEN
  137.           MyWord(); // will be treated as function definition
  138.         BR_CLOSE
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.                        DISTRIBUTION STATUS
  147.                        ===================
  148.  
  149. TSD program v.0.5 can be used freely by anyone for any legal
  150. purpose. The only limitation is:
  151.  
  152.    Distributing TSD.EXE without this file is not allowed.
  153.  
  154. Registered users will be informed about new releases.
  155. To register send E-mail to:
  156.  
  157.         kogan@delphi.com
  158.  
  159. with the word "TSD" in subject or first nonempty line.
  160.  
  161. The author will greatly appreciate any comments/complains/advises....
  162.  
  163. Andrey Kogan. 4/4/95
  164.  
  165.