Selection Criteria

A selection criterion is used to filter out candidate code elements and only leave and count those satisfied elements. For example, criterion is_deferred in a basic class metric is only satisfied when a candidate class is deferred. A selection criterion can have modifiers which indicate how the associated criterion will perform its filtering task. There are four kinds of modifiers, shown as follows:

• Text modifier - String text, and this text is called criterion text
• Domain modifier - Domain, and this domain is called criterion domain
• Metric modifier - Metric, and this metric is called criterion metric
• Normal modifier - modifier other than text, domain and metric

Let's first introduce a convention to describe selection criteria:

• Criterion name will be followed by modifiers (separated by a comma) if any
• Text modifier will be in double quotes
• Domain modifier will follow the convention of domain
• Metric modifier will be in bold
• Normal modifier will be in normal font and face
• Braces will be added to avoid ambiguity

Some examples:

is_deferred

text_is "some text", identity, case-sensitive

ancestor_is {ANY}

value_of_metric_is Class, {base}, (>0 and <100)

There are several kinds of selection criteria, namely, text criterion, path criterion, relation criterion, metric value criterion and normal criterion.

Text Criterion

Text criterion uses a text modifier, two normal modifiers (one to specify matching strategy and the other to specify case sensitivity) to perform text pattern matching. Criterion such as name_is and text_is are text criteria.

Let's take text criterion name_is as an example:

The syntax for name_is is:

name_is "pattern", matching_strategy, case_sensitive

The match_strategy modifier decides how criterion text "pattern" is matched, and can choose from one of the following four values:

• Identity - Pattern is matched if the text is identical to criterion text

• Containing - Pattern is matched the text contains criterion text

• Wildcard - Pattern is matched if it occurs in criterion text according to wildcard rules

• Regular expression - Pattern is matched if it occurs in criterion text according to regular expression rules

The case_sensitive modifier can be True or False, it indicates if pattern matching is case sensitive or not.

In the following two figures, name_is criterion is shown. That criterion will select all classes whose name starts with a letter A (using regular expression rules) case-insensitively.

Path Criterion

A path criterion uses a text modifier as path to test if a candidate class is located in that path. There are two path criteria, namely, path_is and path_in.

The path uses Unix format. For example, criterion path_is "/kernel" will evaluate to True if a candidate class is located in kernel folder related to the class's group. On Windows, path matching will be case-insensitive, on other platforms, path matching will be case-sensitive.

The following figure shows a path criterion used to find classes which locate in "kernel" folder:

Relation Criterion

A relation criterion uses a criterion domain to check if a candidate code element is of some relationship between the criterion domain. Some other modifiers may also appear in a relation criterion.

Let's have look at a class relation criterion client_is shown in the following two figures where a basic class metric with relation criterion client_is is defined. This client_is criterion will match all direct normally referenced as well as only syntactically referenced suppliers of class LINKED_LIST.

For more information about normally referenced and only syntactically referenced suppliers, see document of relation criterion client_is.

Value Criterion

Value criterion is used to test if calculated value of a given metric satisfies some values. There is only one criterion named value_of_metric_is in this category. Please see the document for value criterion value_of_metric_is for more information.

The following figure shows the use of value_of_metric_is criterion, where a class basic metric is defined to find classes whose lines of code is over 1000:

The following figure shows the result of the above metric:

Normal Criterion

All other criteria except for those described above are called normal criteria.

Some examples:

is_library - test if a candidate group is a library

is_deferred - test if a candidate class or feature is deferred

is_comment - test if a candidate line is comment

Criterion Connector

There are three criterion connectors: and, or, not. They are self-explanatory. Just a simple example, see the following figure:

See Also:
Domains
Selection criterion reference