ref - Display a C function header

ref [options]... [restrictions]...

This page describes the Elvis 2.2_0 version of ref. See elvis(1).

ref quickly locates and displays the header of a function. To do this, ref looks in the "tags" file for the line that describes the function, and then scans the source file for the function. When it locates the function, it displays an introductory comment (if there is one), the function's declaration, and the declarations of all arguments.

-t

Output tag info, instead of the function header. The tag info consists of the three standard fields from each tag. The fields will be separated by tab characters, just like records from the traditional tags file format. Consequently, you can use "ref -t -a >oldtags" to convert a new-style tags file back to an old-style tags file.

-v

Output verbose tag info, instead of the function header. The verbose tag info shows the names and values of all attributes for each matching tag. Each name/value pair is shown on a separate line. It also shows the "match" factor that is used for sorting tags which have the same tagname.

-h

Output HTML browser info, instead of the function header. This is an HTML table with hypertext links into the source files where the tags are defined. You can use Netscape or another browser to use this, but they won't move the cursor to the correct line within the source file; only Elvis knows how to do that.

This resembles Elvis' :browse command.

-c

Don't output introductory comments before each tag definition line.

-d

Don't output other lines of the definition. The line where the tag is defined is shown but any preceding or following lines which are part of the definition will be omitted.

-a

List all matching tags. (Without this option, ref would only output the single most likely tag.)

-s

Search all tags files. Without this option, ref would stop searching after processing the first tags file which contained any tags which met the restrictions.

-p tagpath

List of directories or tags files to search through. By default, ref would use the value from the TAGPATH environment variable or a hardcoded default value for each operating system.

-l taglength

Only check the first taglength characters of tag names. The default behavior is to check all characters.

Other than options, any argument on ref's command line is interpreted as a restriction or sorting hint. Elvis parses all of the restrictions and sorting hints, and then scans the tags files (i.e., every file listed in the tag path, or a file named "tags" in every directory listed in the tag path). Tags which fail to meet any restriction are discarded.

Other tags are inserted into a list. The list is sorted primarily by each tag's tagname. If multiple tags have the same overloaded name, then those tags will be sorted according to the sorting hints. In the absence of hints, the tags will be added in the same order in which they appear in the tags file.

The restrictions can be given in any of the following forms:

name:value[,value...] Reject tags which have an attribute named name, but that attribute's value isn't in the list of acceptable values. E.g., "class:Foo" rejects tags from a different class, but accepts tags which have no class.

name:=value[,value...] Reject tags which have an attribute named name, but that attribute's value isn't in the list of acceptable values. Also reject tags which don't have an attribute named name. E.g., "class:=Foo" only accepts tags which have class "Foo".

name:/value[,value...] Like "name:value" except that the tagaddress field is required to contain value as a substring. So "class:/Foo" would find tags in class "Foo" PLUS global tags whose address mentions "Foo" - probably friends of the Foo class.

value[,value...]

Short for tagname:value[,value...] The sorting hints follow a similar form:

name:+value[,value...] Pretend that recent successful searches had attributes named "name" with the given values. This causes any similar tags in the new search to appear near the top of the list.

name:-value[,value...] Pretend that recent failed searches had attribute named "name" with the given values. This causes any similar tags in the new search to appear near the bottom of the list. A null value string matches anything. So "struct:=" would accept any tag with a "struct" attribute, and reject those without it. This would be handy when you're trying to do tag lookup for a word which follows a '.' character - you know it is a field name, but you don't know from which struct type. Note that if you invoke ref without giving any restrictions, then all tags will match and will (if invoked with the -a flag) be output.

While converting some code from K&R C to ANSI C, I needed to generate extern declarations for all the functions. To find the global function headers, I used the command...

ref -a kind:f file:dummy

The "-a" causes ref to output all headers, instead of just the first one that it finds. "kind:f" causes it to exclude any non-functions. "file:dummy" is tricky -- it causes ref to exclude static tags from all files except "dummy", and since there were no C functions defined in any file named "dummy", all statics were excluded. I only got globals.

Once I had a list of all global functions, I still had to do some editing to convert them into ANSI declarations (ref couldn't help me there) but at least I could be confident that my list of functions was complete and accurate.

For each source file, I also needed to find the static functions defined there, so for each "file.c" I used the command...

ref -a kind:f file:=file.c

This is very similar to the earlier command. The main difference is that we're using "file:=" (with an '=', to exclude globals) and a real file name (instead of "dummy") so we do include the static tags from that particular file.

ref is used by elvis(1)'s shift-K command. If the cursor is located on a word such as "splat", in the file "foo.c", then Elvis will invoke ref with the command "ref splat file:foo.c".

Elvis' "smartargs" option also uses ref to look up the arguments for a given function.

A tag is a collection of attributes. Each attribute has a name and a value. Every tag has attributes with the following names:

tagname

The name of the tag; usually the same as the function (or whatever) that the tag refers to.

tagfile

The name of your source code file, in which the tag's definition occurred.

tagaddress

Either a line number, or a "nomagic" regular expression, which allows Elvis or ref to locate the tag's definition within your source file.

In addition, any tag can have additional, optional attributes. These extra tags are meant to serve as hints, describing the contexts in which the tagname is permitted to occur in your source code. The list of additional attribute names is not preset; any tags file can use whatever seem appropriate. The following are typical:

kind

This value is a single letter indicating the lexical type of the tag. It can be "f" for functions, "v" for variables, and so on.

file

If the tag can only be used within a single source file, then this should be the name of that file. E.g., in C, a "static" function can only be used in the function in which it is defined, so if a function is static then its tag will usually have a file attribute, and its value will be the same as that of its tagfile attribute.

function

For local variables. The value is name of function in which they're defined.

struct

For fields of a struct or union. The value is the name of the struct or union. If it has no name (not even a typedef) then "struct=struct" is better than nothing.

enum

For values in an enum data type. The value is the name of the enum type. If it has no name (not even a typedef) then "enum=enum" is better than nothing.

class

Member functions of a class in C++ could use this to identify which class they're in. The class name itself, however, is global so it doesn't have a class attribute.

scope

Intended mostly for class member functions. It will usually be "public" or "private", so users can restrict tag searches to only public members.

arity

For functions. Its value is the number of arguments.

Currently, the hacked-up version of ctags(1) (sometimes installed as elvtags(1)) included with Elvis will only generate kind, file, and class hints, and it doesn't do a very good job on class hints.

The tags file is a text file, in which each line describes a single tag. Each line is divided into fields, delimited by tab characters.

The first 3 fields are implicitly defined to be the values of the tagname, tagfile, and tagaddress attributes, in that order. Note that this is identical to the traditional format of the tags file.

If there are other fields, then semicolon-doublequote will be appended to the tagaddress field; vi ignores anything after that, so the extra fields won't interfere with vi's ability to perform tag searches. Other editors such as Elvis and Vim use the extra fields though.

The extra fields are required to have the format "<tab>name:value". I.e., a ':' is required, and everything before the ':' is used as an attribute name, and everything after it is used as this tag's value for that attribute. There are two exceptions:

*

If an extra field lacks a colon, then the field is assumed to be the value of an attribute named "kind". (Some versions of ctags generate a single-letter "kind" value to indicate whether a tag is a function, variable, typedef, etc.) Since nearly all tags have this field, omitting "kind:" significantly reduces the size of the tags file, and the time needed to search it.

*

Static tags are usually marked with "file:", with no file name after the ":". In this case the file name is understood to be identical to the "tagfile" field. This does more than just reduce the size of the tags file -- "tagfile" values are relative to the directory containing the tags file, and this rule offers a way to make "file" values be relative, too.

Different tags may have differently named hints. Since each hint includes an explicit name with each value, they can appear in any order, and you can omit any which don't apply to a given tag.

Ref and Elvis store attribute names are stored in a fixed-size array, which is shared among all tags from a given file. Consequently, the number of distinct attribute names within a tags file is limited. As currently configured, that limit is 10 names - the 3 standard ones plus up to 7 other names for hints.

When ref has found a tag entry and is searching for the source of that tag, if it can't read the original source file then it will try to read a file named "refs". The "refs" file should contain a copy of all source code, with the bodies of functions replaced by "{}". Elvis' version of ctags(1) can generate a "refs" file.

The following files can be found in any directory named in the tagpath.

tags

List of function names and their locations, generated by ctags(1).

refs

Function headers extracted from source files (optional).

TAGPATH

List of directories or files to be searched. In the case of directories, ref looks for a file named "tags" in that directory. The elements in the list are separated by either colons (for Unix) or semicolons (for most other operating systems). For each operating system, ref has a built-in default which is probably adequate.

You might want to generate a "tags" file for the directory that contains the source code for standard C library on your system. This will allow ref to serve as a quick reference for any library function in addition to your project's functions.

If licensing restrictions prevent you from making the library source readable by everybody, then you can have Elvis' version of ctags(1) (often installed as "elvtags") generate a "refs" file, and make "refs" readable by everybody. If your system doesn't come with the library source code, then perhaps you can produce something workable from the lint(1) libraries.

elvis(1), ctags(1), lint(1)

Note that on most Unix systems, the Elvis version of ctags(1) is installed as elvtags(1).

Steve Kirkendall

kirkenda@cs.pdx.edu