Kind Name Filters

Kind filters are conceptually fairly simple, and in practice are also fairly easy to use. However, there are many details involved that can make documenting them daunting.

There are approximately 75 to 150 different defined kinds of entities and references, depending on the language. Some concepts of kind are simple to describe in some languages. For example, there is a single kind that represents file entities in Ada. However, in C++ there are three different kinds that represent different kinds of files. (Actually, there is a fourth kind, but it is used internally only and should not occur in usage of this API).

Each distinct kind is represented by a string of tokens that together read something like a sentence. A Kind string always has a token representing the language (C, Ada, Fortran or Java) and one or more tokens which describe the kind. The tokens have been chosen to be common, when appropriate, among several similar kinds. For example, in C++, the three kinds of files are “C Code File”, “C Header File” and “C Unknown Header File”. Notice how the token “File” is common to all three kinds and the token “Header” is common to two of the kinds? This is very important when specifying a filter.

A filter string is used to match one or more related or unrelated kinds, for purposes of selecting entities or references from the database. In order for a filter string to match a kind, each token in the filter string must be present as a token in the kind string. This can be thought of as an “and” relationship. For example, the filter “File” matches all three C file kinds, since all three have the token “File” in their strings. The filter “Header File” matches the two C file kinds that have both “Header” and “File” in their strings.

A filter string may use the symbol “~” to indicate the absence of a token. So, again for example, the filter string “File ~Unknown” matches the two C file kinds that have the token “File” in their string but do not have the token “Unknown” in their string.

In addition to “and” filters, “or” filters can also be constructed with the “,” separator. Groups of tokens separated by a comma are essentially treated as different filters. When each filter is calculated the results are combined with duplicates discarded. So, the filter string “Code File, Header File” matches all three of the C file kinds.

With proper knowledge of all the kinds available, kind filters can provide a powerful mechanism for selecting entities and references. On the one hand, specifying “File” matches all file kinds; on the other hand, “Undefined” matches undefined files in addition to all other entity kinds that represent the concept “undefined”.

The following sections detail the name strings (used in the Perl API) and their respective C API literals for both Entity Kinds and Reference Kinds of each language.


Scientific Toolworks, Inc.
http://www.scitools.com