Synopsys logo

Coverity® 2020.12 CodeXM

Common Library Reference

Introduction

Functions

Hide/show Contents

Coverity® 2020.12 CodeXM

Common Library Reference

Introduction

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.

Typographic Conventions

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.

Functions

The common library provides general-purpose functions for handling and analyzing target code.

Filtering Target Code

This set of functions helps you focus on a particular portion of the target source.

allCodeIn( theCode )

Returns all code within the theCode argument.

Parameters and Return Value

Name Type Description
theCode astnode The input code
return value set<astnode> A set whose elements are the code elements

Example

C/C++ code follows
x + 1; // "code" is this statement.

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.

See Also

contains

allMatchingCodeIn( desiredPattern, theCode )

Finds all the code within the theCode argument that matches the desired pattern. Returns a list of values produced by the pattern matches.

Parameters and Return Value

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

Example

C++ code follows
if ( x ) { // "code" is the if statement.
throw 1;
} else {
throw 2;
};

In this case, allMatchingCodeIn(pattern { throwOperator as t -> t.operandExpression }, code) returns a list that contains expressions 1 and 2.

See Also

anyMatchingCodeIn

anyMatchingCodeIn( desiredPattern, theCode )

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.

Parameters and Return Value

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.

Example

C++ code follows
if ( x ) { // "code" is the if statement.
throw 1;
} else {
throw 2;
};

In this case, anyMatchingCodeIn(pattern { throwOperator as t -> t.operandExpression }, code) returns the expression 1 or 2.

See Also

allMatchingCodeIn

contains( predicate, theCode )

Returns true if any code within the theCode argument satisfies the predicate. Returns false otherwise.

Parameters and Return Value

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

Example

CXM code follows
function hasThrow( n: astnode ) -> contains( function( t: astnode ) -> t matches throwOperator, n );

This hasThrow() function checks whether n contains a throw.

See Also

containsMatch

containsMatch( desiredPattern, theCode )

Returns true if any code within the theCode argument matches the pattern. Return false otherwise.

Parameters and Return Value

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

Example

CXM code follows
function hasThrow( n: astnode ) -> containsMatch( throwOperator, n );

This hasThrow() function checks whether n contains a throw.

See Also

contains

filter( predicate, s )

Returns a list of all the elements in the input set that satisfy the predicate.

Parameters and Return Value

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

Example

Executing the following function call:

CXM code follows
filter( function( x: int ) -> x == 1, [1, 2] );

... results in the list [1].

innermostOwner( ownerPattern, theCode )

Returns the innermost code that owns the theCode argument that matches the pattern. If the theCode argument matches the pattern, returns theCode itself.

Parameters and Return Value

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

Example

C/C++ code follows
while( 1 ) {
if( x ) { // "code1" is the expression "x"
x++; // "code2" is the statement "x++;"
}
};

In this case, innermostOwner(statement, code1) returns the if statement, and innermostOwner(statement, code2) returns the x++; statement itself.

See Also

outermostOwner

outermostOwner( ownerPattern, theCode )

Returns the outermost code that owns the theCode argument that matches the pattern. If the theCode argument matches the pattern, returns theCode itself.

Parameters and Return Value

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.

Example

C/C++ code follows
if( x + y == 10 ) { // "code1" is the expression "x"
x++; // "code2" is the expression "x++"
};

In this case, outermostOwner(expression, code1) returns the binary expression x + y == 10, and outermostOwner(expression, code2) returns the expression x++ itself.

See Also

innermostOwner, outermostOwnerExpression

outermostOwnerExpression( theExpression )

Returns the outermost expression that owns the theExpression argument. If the theExpression argument is already the outermost expression, returns theExpression itself.

Parameters and Return Value

Name Type Description
theExpression expression The expression from which the search starts
return value expression The outermost owner expression

Example

C/C++ code follows
if( x + y == 10 ) { // "expr1" is the expression "x"
x++; // "expr2" is the expression "x++""
};

In this case, outermostOwnerExpression(expr1) returns the binary expression x + y == 10, and outermostOwnerExpression(expr2) returns the post-increment expression x++ itself.

See Also

outermostOwner

ownerStatement( theCode )

Returns the innermost statement that contains the theCode argument. If theCode is a statement, returns theCode itself.

Parameters and Return Value

Name Type Description
theCode astnode The code from which the search starts
return value astnode? Returns null if there is no such statement

Example

C/C++ code follows
if( x ) { // "code1" is expression "x"
x++; // "code2" is statement "x++;"
};

In this case, ownerStatement(code1) returns the if statement, and ownerStatement(code2) returns the x++; statement itself.

See Also

innermostOwner

Handling Sets and Lists

These functions are for manipulating list or set objects.

reverse( l )

Returns a list whose members are in the reverse order of the input list.

Parameters and Return Value

Name Type Description
l list<T> The list
return value list<T> The reversed list

Example

Executing the following function code:

CXM code follows
reverse( [1, 2] );

... results in the list [2, 1].

unique( equal, s )

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.

Parameters and Return Value

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

Example

Executing the following function call:

CXM code follows
unique( function( x: int, y: int ) -> x == y, [1, 1, 2] );

... results in the list [1,2].

Managing Strings

These are standard functions for searching or converting string objects.

Regex( string )

Matches a string that conforms to the specified regular expression (regex), using the Boost engine.

Parameters and Return Value

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:

captures
list<string> — A list of the capture groups in the regular expression
fullMatch
string — The full match

Example

The following pattern detects cases where a const variable identifier does not start with "c":

CXM code follows
pattern constVarNoC { variableDefinition { .type == typeQualifierCost; .identifer != Regex( "^c" ); } };

RegexExtended( string, options )

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.

Parameters and Return Value

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:

captures
list<string> — A list of the capture groups in the regular expression
fullMatch
string — The full match

strToInt( string )

Converts a string to an integer value.

Parameters and Return 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

Example

The following snippet:

CXM code follows
strToInt( "1" )

... returns 1.

strToLower( string )

Converts all ASCII letters found in a given string to lower case, if need be.

Parameters and Return Value

Name Type Description
string string The string to convert
return value string The converted string, all lower case

Example

The two calls in the following sample code:

CXM code follows
strToLower( "ABC" ); strToLower( "abc" );

... both return "abc".

Debugging Support

The debug() function is for printing error messages.

debug( eventstring )

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.

Parameters and Return Value

Name Type Description
eventString eventString The string to print
return value bool Always returns true.

Example

The following expression prints out the debug log. This log is located at ./<output_dir>/output/analysis-log.txt.

CXM code follows
let _ = debug( "custom debug message:" + n ) in // ...

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.