eiffel-org/documentation/20.05/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/selection-criteria.wiki

[[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 {<eiffel>ANY</eiffel>}

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 <eiffel>LINKED_LIST</eiffel>.

[[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|<br/>
[[Domains|Domains]]  <br/>
[[Criterion References|Selection criterion reference]]  }}