home *** CD-ROM | disk | FTP | other *** search
/ Boston 2 / boston-2.iso / DOS / PROGRAM / C / GETF / GETF.DOC < prev    next >
Encoding:
Text File  |  1993-12-01  |  4.5 KB  |  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.  
  61.             main                       48
  62.  
  63.             get_names_one_file         97
  64.  
  65.             get_fn_name               187
  66.  
  67.             filter_data               221
  68.  
  69.             filter_parens             242
  70.  
  71.             filter_curly_braces       274
  72.  
  73.             filter_ppdir              306
  74.  
  75.             get_ppdir_line            343
  76.  
  77.             filter_quotes             367
  78.  
  79.             filter_cmt                396;
  80.  
  81.  
  82.         getf.c:
  83.  
  84.             main                       49
  85.  
  86.             patn_match                193
  87.  
  88.             ask_for_file              226
  89.  
  90.             edit                      259
  91.  
  92.             help                      299;
  93.  
  94.     Assume the editor is BRIEF.  Possible GETFEDIT strings might be:
  95.  
  96.             b.exe %s
  97.                     This will simply bring up the desired source file
  98.                     in BRIEF without any attempt at positioning the
  99.                     cursor to the requested function.
  100.  
  101.             b.exe -m"search_fwd %s" %s
  102.                     This will bring up the desired source file and
  103.                     position the cursor to the first occurrence of the
  104.                     requested function.
  105.  
  106.             b.exe -m"funcsrch %s" %s
  107.                     (see DDJ article for a description of this
  108.                     customized BRIEF macro.)  This will bring up the
  109.                     desired source file, seek to the end of the file,
  110.                     then seek backwards for the LAST occurrence of the
  111.                     requested function.  In practice, this is the
  112.                     approach most likely to position the cursor to the
  113.                     actual definition of the function.
  114.  
  115.     For the SEE editor supplied with the DeSmet C compiler, a suitable
  116.     GETFEDIT control string is:
  117.  
  118.             \see.exe %s -l%d
  119.                     This will bring up the desired source file and
  120.                     position the cursor near the function definition. 
  121.                     Of course, if much text is added or deleted the
  122.                     line numbers in funcs.txt will be out of date, so
  123.                     bldfuncs will need to be run again.
  124.  
  125.     To illustrate wildcards:
  126.  
  127.         getf func*
  128.                     matches  func, func1, func_2, etc.
  129.  
  130.         getf t*n
  131.                     matches  ten, tension, transportation, but not tens.
  132.  
  133.         getf [bdf-h]ad
  134.                     matches  bad, dad, fad, gad, had
  135.  
  136.         *alloc
  137.                     matches  alloc, malloc, calloc, realloc
  138.  
  139.         [~c]alloc
  140.                     matches  malloc,  but not alloc, calloc
  141.  
  142. NOTE: 
  143.     Remember that to set GETFEDIT in your autoexec.bat file (or in any
  144.     other batch file) you must use TWO percent signs instead of one:
  145.  
  146.                 set GETFEDIT=c:\bin\b.exe -m"funcsrch %%s" %%s
  147.  
  148.     This is necessary to avoid interpretation of the percent signs by
  149.     command.com.
  150.  
  151.  
  152. AUTHOR:
  153.     Marvin Hymowech, "Find That Function", Dr. Dobb's Journal of Software
  154.     Tools, #142 (August 1988).
  155.  
  156.     transcribed and modestly enhanced by James R. Van Zandt,
  157.     jrv@mitre-bedford.arpa.
  158.     
  159.  
  160.