You're a C programmer who has just changed employers. You are suddenly responsible for maintaining more than 100 source code files and perhaps three times as many C functions. In wandering through your new wealth of source code, you find a reference to a function called get_input which sounds like a good thing to look at next. But which file is it in? Or perhaps you recall seeing a function called save_screen (or was it save_scrn?) that would be just the thing to use in that new function you have to write, but you just can't recall where you saw it. What to do?

The traditional way of handling these problems is this: First, you use a text-searching program such as grep (Unix) or ts (from The Norton Utilities) and search through all your source files for every reference to the function you are looking for until you finally locate the reference that is the function definition. Then, you bring up the source file in your editor. Next, you search for the function again until you finally find the function definition. By this time, the reason you were looking for it has usually slipped your mind.

Having suffered through this situation several times over the years (and not just with other peoples' code!), I resolved to find a better way. This article presents my solution: a function finder for MS-DOS. Using the function finder (actually, it consists of two programs) speeds up the process considerably. You simply invoke the finder with the function name as an argument. The program then scans an index file, invokes your editor using the appropriate source file, and, for sophisticated editors such as Brief, even positions the cursor at the function definition.

The two programs that make up the function finder, bldfuncs and getf are written in C. Although I used Microsoft C (Version 5.0) to compile the programs presented here, the code could be ported to other compilers (or to Unix) with minimal changes. The editor I use is Brief, Version 2.01, but any other editor could be used.

As I mentioned earlier, my solution consists of two programs, bldfuncs and getf. bldfuncs constructs an index by reading through all the C source files specified on the command line and then constructing a text file (funcs.txt) that contains the name of each C source file read and a list of all functions defined therein. The resulting file looks something like this:

file_1.c:
       function_1a
       function_1b
       ...
       function_1z;

file_2.c:
       function_2a
       ...

Once the index file has been built by bldfuncs getf can be run with a function name as a command-line argument. getf reads funcs.txt until it finds a match for the specified function name (wildcard characters are allowed) and then gets the name of the C source file in which the function resides. Next, getf constructs a DOS command line invoking the editor of your choice with this source file as the file to be edited. Then, a DOS exec call is performed to replace getf by the editor in memory. For editors such as Brief, which let you specify editor commands on the command line as well, even more is possible: You can specify an appropriate search command to position the cursor at an occurrence of the function name, which will hopefully be the actual definition of the sought for function.

In brief then, you run bldfuncs once to construct funcs.txt and thereafter whenever major changes occur in the distribution of functions among your source files. If you then need that elusive function save_screen (save_scrn?), you just type getf save_scr*. One of three things will happen then:

1. getf will politely tell you that there is no such function in funcs.txt.

2. getf will find that there is exactly one function in funcs.txt matching the mask save_scr*, and the next thing you will see is the desired source file in your editor, with the cursor positioned at the exact place where the function is defined (maybe).

3. getf will find more than one match for save_scr and will present you with a menu of such functions and the source files in which they are defined; after you choose one of these files, it will be presented in the editor, as in case 2.

bldfuncs is intended to read C files that work with almost any C compiler on the market; it is assumed, however, that the files will compile without errors.

Now for some of the details. In an effort to land exactly at the function definition after the editor was invoked, I first tried instructing Brief to start at the beginning of the file and search forward for the function name. Most programmers, however, code so that functions are more likely to be referenced (in the source file in which they are defined) before they are defined rather than after. In keeping with this general rule, I wrote a custom Brief macro to start at the end of the file and search backward for the function name instead. This worked much better and in fact lands me at the exact spot about 50 percent of the time; when it doesn't work, I just use the key assigned to search_again to continue looking.

The command line getf uses to invoke the editor is built by using the DOS environment variable GETFEDIT, which allows users to customize getf to their editor of choice. On my machine, my autoexec.bat file contains the line:

     set GETFEDlT= b-m'funcsrch %%s'%%s

Where funcsrch is the Brief macro mentioned earlier. The -m option tells Brief to invoke the macro in quotes after it begins. getf replaces the first %%s by the function name it is looking for and the second %%s by the file name in which it will be found.

(macro funcsrch
     (
          (string s)
          (extern _s_pat _dir center_line)
          (get_parm 0 s)
          (message "locating function %s..." s)
          (end_of_buffer)
          (if ( > (search_back s) 0 )
               (
                    (message "function %s found" s)
                    (center_line)
                    (sprintf _s_pat "%s" s)
                    ( = _dir 0)
               )
          ;else
               (
                    (top_of_buffer)
                    (beep)
                    (message "function %s not found" s)
               )
          )
     )
)

bldfuncs.obj: bldfuncs.c
              cl /c bldfuncs.c

bldfuncs.exe: bldfuncs.obj
             link bldfuncs+\msc5\lib\setargv/ST:14000/NOE;

The next filter is filter_quotes, which reads the character stream returned by filter_cmt and replaces any quoted string (delimited by either single or double quotes) by the special value QUOTES, which is used as a place marker for the original string. Higher-level filters look for matching curly braces, for example, and would be confused by curly braces occurring within quotes. The only subtlety in filter_quotes is to treat escaped characters (preceded by a backslash) correctly to avoid terminating a quoted string prematurely--for example, the string \i (slash, curly brace).

Next in the hierarchy comes filter_ppdir, whose task is to read from the stream provided by filter_quotes and eliminate all preprocessor directives. (I have made the simplifying assumption that no function will be defined either via a #define directive or in an include file. Although such peculiarities are possible, they are rare and are not constructs found when good programming style is employed.) The gotcha to be avoided in this filter is that #define constructs may extend to several programming lines, so filter_ppdir is careful to scan for escaped new-line sequences (a backslash followed immediately by a newline character) before deciding that a #define construct has terminated.

Next, filter_curly_braces reads the stream returned by filter_ppdir and replaces all characters between matching curly brace pairs (( )) by the special value BRACES. This is accomplished by maintaining a brace count that begins at zero and is incremented when a left brace is encountered and decremented when a right brace is encountered. While the count is nonzero, no incoming character is returned to the caller.

At this point, the filtered input stream consists of external data items, function models for type checking, and actual function definitions. To simplify the task further, filter_parens reads the character stream provided by filter_curly_braces and eliminates all characters between parentheses, returning instead the special value PARENS. This approach eliminates thorny problems in the declaration of formal function parameters--for example, in the function definition:

int function1(a,b,c)

int (*a)( );
char(*b)( );
int c;
{
}

Some data initialization expressions can have constructions that resemble functions also--for example:

     int size = sizeof(array)/sizeof(element);

To avoid such problems, filter_data reads the stream provided by filter_parens and deletes the right-hand side of any assignment and the equal sign, leaving just the semicolon.

The stream returned by filter_data is sufficiently simple that it can now be used to extract the names of defined functions. The routine get_names_one_file opens the file specified by the parameter source_file_name; reads this file via filter data; and writes the resulting function names to the file specified by the parameter fp_out, which is the already opened FILE pointer to the output stream for funcs.txt. This is done by storing characters from filter_data until EOF, or a semicolon, or the PARENS symbol is encountered. You are really only interested in sequences like this that end with PARENS because a sequence ending with a semicolon before a PARENS symbol cannot represent a function definition.

The routine get_fn_name is now used to extract the function name from the stored line, by scanning backward from the PARENS symbol until a character is encountered that is neither an underscore nor an alphanumeric. The decision as to whether this is a function definition or a type-checking construction is made as follows: If the first non-white-space character encountered after the PARENS symbol is a semicolon or a comma, it is a type-checking construction. The comma might occur as follows:

     int func1(int, char), func2(int);

If you have an actual function definition, you bypass all characters until the BRACES symbol is encountered because certainly no function definition can occur between the PARENS and BRACES symbols. It only remains to append the function name to the output file, funcs.txt.

I have found these two programs in conjunction to be an excellent timesaver whenever I have to go wandering through source code files and have been using them extensively since I wrote them. The programs have saved me a great deal of time, and fall into the performance category of "fast enough." Although I've no doubt that there are more efficient ways of parsing through C source code than my multiple-filter strategy, the method I chose had two outstanding advantages over other methods: it was easy to program, and it was simple to debug.

Of course, the techniques presented in this article could be generalized to languages other than C. getf would require almost no changes, but a new version of bldfuncs would be required in order to do the parsing specific to the language desired. I'd be interested in hearing from anyone who does the conversion to another language.

_FIND THAT FUNCTION_ by Marvin Hymowech