[[Property:title|Selection Criteria]]
[[Property:weight|6]]
[[Property:uuid|d492c7f5-71ec-ae04-c62b-6845f30ed762]]
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.
[[Image:selection-cri1|Text criterion]]
[[Image:selection-cri2|Text criterion]]
==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:
[[Image:selection-cri3|Path criterion]]
==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.
[[Image:selection-cri4|Relation criterion]]
[[Image:selection-cri5|Relation criterion]]
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:
[[Image:selection-cri6|Relation criterion]]
The following figure shows the result of the above metric:
[[Image:selection-cri7|Relation criterion]]
==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:
[[Image:selection-cri8|Relation criterion]]
{{seealso|
[[Domains|Domains]]
[[Criterion References|Selection criterion reference]] }}