Polyspace Query Language Syntax for Creating User-Defined Coding Standard

A user-defined coding standard is a collection of coding rules that you curate to check for bugs and defects that are relevant to your project. You can collect existing Polyspace^® Bug Finder™ checkers as well as new user-defined defects into one coding standard.

Overview of a User-Defined Coding Standard

In Polyspace Query Language (PQL), a user-defined coding standard consists of one or more sections and each of these sections consist of one or more rules. The rules can map to existing Bug Finder checkers or user-defined defects. For example, a coding standard myStandard can contain components in a hierarchy:

You can declare individual components such as user-defined defects, mappings, rules, and sections first and then assemble the components into a user-defined coding standard. For coding standards that are small and consist of only a few rules, you can define the entire coding standard in the same file.

Syntax for Components of User-Defined Coding Standard

Use this syntax to declare necessary components of a user-defined coding standard.

New user defined coding standard

Declare the user-defined coding standard NewStandard by using the catalog keyword:

#[Attributes]
catalog NewStandard = {
  // ...
}

The PQL definition of a user defined coding standard must contain a unique catalog component. This component houses one or more sections. The Attributes keyword specify specific properties of the catalog component.

Section

Declare a new section in a user-defined coding standard by using the section keyword:

#[Description ("Section Description")]
section mySection = {
  // ...
}

This code declares a new section mySection. When you create the UDC containing this section, Polyspace uses Section Description as the label for this section. Each section contains one or more rule.

Rule

Declare each rule by using the rule keyword:

#[Attributes]
#[Description ("Rule Definition"), Id(Rule_Id)]
rule myRule = {
 // ...
}

Here, Attributes specify various properties of the rule. The rule can be a mapping to existing Bug Finder checkers or a new user-defined defect.

Mapping

Mappings are one possible component of a rule. Use mappings to associate one or more Bug Finder checkers to a rule. Declared a mapping by using the mapping keyword:

mapping myMapping = {
std.PQLStandardName.PQLCheckerName
}

In this syntax:

myMapping is the name you assign to the mapping.
PQLStandardName is the PQL name of the coding standard or Bug Finder defect.
PQLCheckerName is the PQL name of an existing Bug Finder checker. You can find the PQL name of a checker on its reference page. See Polyspace Bug Finder Results.

This table shows the PQL names of the coding standards and Bug Finder defect.

Standard	PQL Name
MISRA C:2012	`std.misra_c_2012`
MISRA C:2023	`std.misra_c_2023`
CERT C	`std.cert`
CWE	`std.cwe_native`
MISRA C++:2023	`std.misra_cpp_2023`
AUTOSAR C++14	`std.autosar_cpp14`
CERT C++	`std.cert-cpp`
Bug Finder defects	`std.defects`

New user-defined Defect

A rule can contain the definition of a user-defined defect. Declare a user-defined defect by using the defect keyword:

defect myDefect = 
  when myQuery
  raise myMessage
  on var

This defect queries the code using myQuery and reports a violation on var with the contextual message myMessage. For details about creating user-defined defects, see Polyspace Query Language Syntax for Creating User-Defined Defects.

Package

Each mapping, defect, rule, and section of a user-defined coding standard can be thought of as a component of the standard. You can declare these components in separate files. In each file, use the keyword package to define the scope of the components. For example, this code declares a rule myRule in the package myPackage:

package myPackage
rule myRule = {
  //...
}

All components that are declared in the same package have the same scope. You can add additional components in a package by declaring them to be in the same package.

package myPackage
rule newRule = { 
  //...
}

By using packages, you can make the coding standard modular, extensible, and easier to maintain. See Best Practices for Creating User-Defined Coding Standards.

Syntax for Attributes

When defining a user-defined coding standard, you can provide additional information about components by defining several attributes. Declare the attributes by using this syntax preceding the component declaration:

#[<Attribute> ("<value>")]

Attributes that apply to any component are:

Description ("value") — Use this attribute with any component of the coding standard. Polyspace uses value as the label of the component in the user interface For example, this code labels the user-defined coding standard myStandard with New standard about specific issue:
```
#[Description ("New standard about specific issue")]
  catalog myStandard = {
}
```
Similarly, you can label other components of the coding standard by using the Description annotation.
Deprecated — Specify that the component is no longer in use. If any code uses a component specified by this attribute, Polyspace issues value as a warning.
NoWarning — Specify that warnings arising from the component is suppressed. This attribute does not accept any value.

The attribute Catgories(str1, str2...) apply specifically to the catalog component. This attribute specifies str1, str2, and other listed strings as possible categories of the standard, with str1 being the lowest priority and subsequent categories being progressively higher priority. If this attribute is used, then these same categories must be assigned as categories to the rules of the standard.

Attributes that apply to rule include:

Id(Rule_Id) — The identifier Rule_Id acts as the rule identifier during result review. You can using Rule_Id to annotate the results of a user-defined PQL defect checker. Rule_Id must be smaller than 60 character. PQL supports Rule Id with and without surrounding double quotes:
```
#Id("MyRule") // valid
#Id(MyRule) // valid
```
PQL allows upper and lower case letters, numbers, and the underscore character (_) in Rule_Id. Other special characters and white space in Rule_Id is not supported.
Category(Category_ID) — Associates the rule to the category Category_ID. This identifier must be one of the values listed in the Categories attribute of the catalog component.
Lang — Specify the language to which a rule applies. Specify either C or C++. If this attribute is not specified, a coding rule applies to both C and C++.
Subset — Associates a rule with a subset.
NotImplemented(Cause) — Use this attribute to associate a comment Cause to rules that are not yet implemented. This comment appears in the Comment column of the Checkers Selection window when using the user-defined coding standard.
NotEnforceable — Specify that a rule is not enforceable.

The attribute NoInline applies to predicate components. This attribute specifies that when creating the user-defined coding standard, the predicate is not inlined. Such predicates cannot accept an input parameter. This attribute is used for debugging.

Define Small Coding Standard in a Single File

In addition to the componentized approach, you can also create smaller user-defined coding standards in a monolithic source file. This approach is useful for quick prototyping.

For example, to define the coding standard myStandard in a single monolithic source file, define the lower level components within the body of their parent components:

package main

catalog myStandard = {
    #[Description ("Section about one issue")]
	section sectionA = {
        #[Description ("Rule to check issue foo"), Id("Foo"), Category ("Required"), Subsets ("Subset_X")]
		rule A_1 = {
			std.autosar_cpp14.M9_3_3 // map to existing rule			
		},
        #[Description ("Rule to check issue bar"), Id("Bar"), Category ("Optional"), Subsets ("Subset_Y")]
		rule A_2 = {
			std.defects.INT_ZERO_DIV
		}
	},
    #[Description ("Section about another issue")]
	section section_B = {
        #[Description ("Rule to check issue Foo_1"), Id("Foo_1"), Category ("Required"), Subsets ("Subset X")]
		rule B_2 = {
			std.cert.PRE01_C //map to existing rule
			}
	}
}