Common Library Reference
Copyright © 2020 Synopsys, Inc. All rights reserved worldwide.
CodeXM is a domain-specific language that allows you to create custom code checkers. CodeXM checkers analyze source code for specific coding patterns, and report these defects with messages that you provide. Like other Coverity checkers, the defects are displayed in Coverity Connect. They can be archived with the cov-commit-defect
feature.
This document describes a set of functions that are common to all of the current CodeXM libraries. It is a supplement to the library references for the specific CodeXM target languages.
Describing CodeXM is a bit different from describing other languages. Most programming books talk about one language only. To describe CodeXM, we have to talk about CodeXM code itself, and the code of the language it is inspecting—the target language.
This reference shows all code in monospace
type.
CodeXM code appears in shades of green.
Target code (whatever the language) appears in shades of orange.
Reminder: By default, many browsers do not print out background colors.
The common library provides general-purpose functions for handling and analyzing target code.
This set of functions helps you focus on a particular portion of the target source.
Returns all code within the theCode argument.
Name | Type | Description |
---|---|---|
theCode | astnode | The input code |
return value | set<astnode> | A set whose elements are the code elements |
In this case, allCodeIn(code) returns a set of code that includes the statement x + 1;, the expression x + 1, the expression x, and the expression 1.
Finds all the code within the theCode argument that matches the desired pattern. Returns a list of values produced by the pattern matches.
Name | Type | Description |
---|---|---|
desiredPattern | pattern(astnode) -> T | The predicate pattern |
theCode | astnode | The input code |
return value | list<T> | A list of values produced by the pattern matches |
In this case, allMatchingCodeIn(pattern { throwOperator as t -> t.operandExpression }, code) returns a list that contains expressions 1 and 2.
If any code within the theCode argument matches the desired pattern, returns the value produced by the pattern match. Otherwise, returns null. If there are multiple matches, returns a single, arbitrary match.
Name | Type | Description |
---|---|---|
desiredPattern | pattern(astnode) -> T | The desired pattern |
theCode | astnode | The code to be checked |
return value | T? | Returns null if there is no code within the input that matches the desired pattern. |
In this case, anyMatchingCodeIn(pattern { throwOperator as t -> t.operandExpression }, code) returns the expression 1 or 2.
Returns true if any code within the theCode argument satisfies the predicate. Returns false otherwise.
Name | Type | Description |
---|---|---|
predicate | function(astnode) -> bool | The predicate function |
theCode | astnode | The code to be checked |
return value | bool | Whether there was any corresponding code |
This hasThrow() function checks whether n contains a throw.
Returns true if any code within the theCode argument matches the pattern. Return false otherwise.
Name | Type | Description |
---|---|---|
desiredPattern | pattern(astnode) -> T | The desired pattern |
theCode | astnode | The code to be checked |
return value | bool | Whether there was any matching code |
This hasThrow() function checks whether n contains a throw.
Returns a list of all the elements in the input set that satisfy the predicate.
Name | Type | Description |
---|---|---|
predicate | function(T) -> bool | The predicate to be checked |
s | set<T> | The set |
return value | list<T> | A list that contains those elements in the input set that satisfy the predicate |
Executing the following function call:
... results in the list [1].
Returns the innermost code that owns the theCode argument that matches the pattern. If the theCode argument matches the pattern, returns theCode itself.
Name | Type | Description |
---|---|---|
ownerPattern | pattern(astnode) -> T | The pattern that matches the owner |
theCode | astnode | The code from which the search starts |
return value | astnode? | Returns null if there is no such owner |
In this case, innermostOwner(statement, code1) returns the if statement, and innermostOwner(statement, code2) returns the x++; statement itself.
Returns the outermost code that owns the theCode argument that matches the pattern. If the theCode argument matches the pattern, returns theCode itself.
Name | Type | Description |
---|---|---|
ownerPattern | pattern(astnode) -> T | The pattern |
theCode | astnode | The code from which the search starts |
return value | astnode? | Returns null if there is no such owner. |
In this case, outermostOwner(expression, code1) returns the binary expression x + y == 10, and outermostOwner(expression, code2) returns the expression x++ itself.
innermostOwner, outermostOwnerExpression
Returns the outermost expression that owns the theExpression argument. If the theExpression argument is already the outermost expression, returns theExpression itself.
Name | Type | Description |
---|---|---|
theExpression | expression | The expression from which the search starts |
return value | expression | The outermost owner expression |
In this case, outermostOwnerExpression(expr1) returns the binary expression x + y == 10, and outermostOwnerExpression(expr2) returns the post-increment expression x++ itself.
Returns the innermost statement that contains the theCode argument. If theCode is a statement, returns theCode itself.
Name | Type | Description |
---|---|---|
theCode | astnode | The code from which the search starts |
return value | astnode? | Returns null if there is no such statement |
In this case, ownerStatement(code1) returns the if statement, and ownerStatement(code2) returns the x++; statement itself.
These functions are for manipulating list or set objects.
Returns a list whose members are in the reverse order of the input list.
Name | Type | Description |
---|---|---|
l | list<T> | The list |
return value | list<T> | The reversed list |
Executing the following function code:
... results in the list [2, 1].
Removes duplicates from a multi-set, based on a specified comparator. In other words, returns a list that contains all elements in the input set, but no duplicates.
Name | Type | Description |
---|---|---|
equal | function(T, T)->bool | The comparator |
s | set<T> | The set to remove duplicates from |
return value | list<T> | The list with all elements in the set, but no duplicates |
Executing the following function call:
... results in the list [1,2].
These are standard functions for searching or converting string objects.
Matches a string that conforms to the specified regular expression (regex), using the Boost engine.
Name | Type | Description |
---|---|---|
string | string | A string that contains the regular expression to match |
return value | pattern | This pattern matches a string if the string contains a match for the regular expression specified by the string argument. |
The pattern that Regex() returns is a record with two properties:
The following pattern detects cases where a const variable identifier does not start with "c":
Matches a string that conforms to the specified regular expression (regex), using the Boost engine. This version allows you to specify additional conditions for how the matching is carried out.
Name | Type | Description |
---|---|---|
string | string | A string that contains the regular expression to match |
options | record | Several fields that control the behavior of the search. |
return value | pattern | This pattern matches a string if the string contains a match for the regular expression specified by the string argument. |
These are the fields in the options record (these fields are all optional, and do not need to be present):
Name | Type | Description |
---|---|---|
caseInsensitive | bool | Set this to true if you want the match to ignore character case. |
exactMatch | bool | Set this to true if you want the match to be exact. |
multiLine | bool | Set this to true if you want the match to ignore line breaks. |
replace | string | If replace is specified, the fullMatch property of the yield record contains the original string with matched substrings replaced according to the value of the replace option. |
The replace option uses the algorithm specified for ECMA-262: See the description of “String.prototype.replace” in the EcmaScript® Language Specification. In particular, "$1" represents the first matched subgroup. | ||
singleLine | bool | Set this to true if you want line breaks to invalidate the match. |
The pattern that RegexExtended() returns is a record with two properties:
Converts a string to an integer value.
Name | Type | Description |
---|---|---|
string | string | The string to convert |
return value | int? | The integer value of the string parameter; null if the parameter does not represent an integer value |
The following snippet:
... returns 1.
Converts all ASCII letters found in a given string to lower case, if need be.
Name | Type | Description |
---|---|---|
string | string | The string to convert |
return value | string | The converted string, all lower case |
The two calls in the following sample code:
... both return "abc".
The debug() function is for printing error messages.
Prints a message to a standard output stream.
Important:
The debug() function does not generate output unless you specify the
--codexm-print-debug
option when you invoke cov-analyze
.
Name | Type | Description |
---|---|---|
eventString | eventString | The string to print |
return value | bool | Always returns true. |
The following expression prints out the debug log.
This log is located at ./<output_dir>/output/analysis-log.txt
.
Note: We don’t care about the value that debug() returns, so here we use the underscore as a placeholder variable name. We won’t reference it elsewhere.