home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 September / Simtel20_Sept92.cdr / msdos / c / getf.arc / GETF.DOC < prev    next >
Text File  |  1988-11-11  |  5KB  |  144 lines
  1. NAME: getf - locate the source file containing a C function
  2.             and present it in a specified editor.
  3.  
  4. USAGE:    getf  [list_file_name]  function_name
  5.  
  6. DESCRIPTION:
  7.     getf looks for the file funcs.txt, which is presumed to be a
  8.     listing of C source file names together with a list of the C
  9.     functions defined in these source files, and the line numbers of
  10.     the definitions.  The expected format is
  11.  
  12.         source_file_1.c:
  13.             function_1      lineno_1
  14.             function_2      lineno_2
  15.             ...
  16.             function_n      lineno_n;
  17.  
  18.         source_file_2.c:
  19.             ...
  20.  
  21.     (This file can be conveniently built using the companion program
  22.     bldfuncs.c.)
  23.  
  24.     The editor to be used is specified in the DOS environment variable
  25.     GETFEDIT, which is presumed to have the form:
  26.  
  27.         editor_file_name  control_string
  28.  
  29.     where control_string is an sprintf control string which must have
  30.     an occurrence of the pattern "%s".  This pattern will be replaced by
  31.     the name of the source file in which the requested function
  32.     resides.  
  33.  
  34.     If a pattern "%d" exists, it will be replaced by the line number on
  35.     which the requested function is defined.  Otherwise, if a second
  36.     "%s" pattern exists, it will be replaced by the name of the
  37.     function.  The latter two formats allow the use of an
  38.     editor-specific command to position the source file to the
  39.     requested function automatically.  After replacing the %s and %d
  40.     patterns as above, the GETFEDIT string is executed via a DOS exec
  41.     call, thus overlaying the current program getf.
  42.  
  43.     Unix style regular expressions are allowed in the function name
  44.     argument for getf, and are interpreted as follows:
  45.  
  46.         *    Matches any string including the null string.
  47.         ?    Matches any single character.
  48.         [...]    Matches any one of the characters enclosed.
  49.         [~...]    Matches any character NOT enclosed.
  50.         -    May be used inside brackets to specify range
  51.         (i.e. x[1-58] matches x1, x2, ... x5, x8)
  52.         \\    Escapes special characters.
  53.         Other characters match themselves.
  54.  
  55. EXAMPLES:
  56.  
  57.     An example of funcs.txt is
  58.  
  59.         bldfuncs.c:
  60.             main                       48
  61.             get_names_one_file         97
  62.             get_fn_name               187
  63.             filter_data               221
  64.             filter_parens             242
  65.             filter_curly_braces       274
  66.             filter_ppdir              306
  67.             get_ppdir_line            343
  68.             filter_quotes             367
  69.             filter_cmt                396;
  70.  
  71.         getf.c:
  72.             main                       49
  73.             patn_match                193
  74.             ask_for_file              226
  75.             edit                      259
  76.             help                      299;
  77.  
  78.     Assume the editor is BRIEF.  Possible GETFEDIT strings might be:
  79.  
  80.             b.exe %s
  81.                     This will simply bring up the desired source file
  82.                     in BRIEF without any attempt at positioning the
  83.                     cursor to the requested function.
  84.  
  85.             b.exe -m"search_fwd %s" %s
  86.                     This will bring up the desired source file and
  87.                     position the cursor to the first occurrence of the
  88.                     requested function.
  89.  
  90.             b.exe -m"funcsrch %s" %s
  91.                     (see DDJ article for a description of this
  92.                     customized BRIEF macro.)  This will bring up the
  93.                     desired source file, seek to the end of the file,
  94.                     then seek backwards for the LAST occurrence of the
  95.                     requested function.  In practice, this is the
  96.                     approach most likely to position the cursor to the
  97.                     actual definition of the function.
  98.  
  99.     For the SEE editor supplied with the DeSmet C compiler, a suitable
  100.     GETFEDIT control string is:
  101.  
  102.             \see.exe %s -l%d
  103.                     This will bring up the desired source file and
  104.                     position the cursor near the function definition. 
  105.                     Of course, if much text is added or deleted the
  106.                     line numbers in funcs.txt will be out of date, so
  107.                     bldfuncs will need to be run again.
  108.  
  109.     To illustrate wildcards:
  110.  
  111.         getf func*
  112.                     matches  func, func1, func_2, etc.
  113.  
  114.         getf t*n
  115.                     matches  ten, tension, transportation, but not tens.
  116.  
  117.         getf [bdf-h]ad
  118.                     matches  bad, dad, fad, gad, had
  119.  
  120.         *alloc
  121.                     matches  alloc, malloc, calloc, realloc
  122.  
  123.         [~c]alloc
  124.                     matches  malloc,  but not alloc, calloc
  125.  
  126. NOTE: 
  127.     Remember that to set GETFEDIT in your autoexec.bat file (or in any
  128.     other batch file) you must use TWO percent signs instead of one:
  129.  
  130.                 set GETFEDIT=c:\bin\b.exe -m"funcsrch %%s" %%s
  131.  
  132.     This is necessary to avoid interpretation of the percent signs by
  133.     command.com.
  134.  
  135.  
  136. AUTHOR:
  137.     Marvin Hymowech, "Find That Function", Dr. Dobb's Journal of Software
  138.     Tools, #142 (August 1988).
  139.  
  140.     transcribed and modestly enhanced by James R. Van Zandt,
  141.     jrv@mitre-bedford.arpa.
  142.     
  143.  
  144.