Main Content

Define Custom Annotation Format

This example shows how to create and edit an XML file to define an annotation format and map it to the Polyspace® annotation syntax. Once you create and edit the XML file, pass the file to Polyspace by using option -xml-annotations-description.

To define multiple custom annotation formats, see Define Multiple Custom Annotation Syntaxes.

To get started, copy the following code to a text editor and save it on your machine as annotations_description.xml.

<?xml version="1.0" encoding="UTF-8"?>

<Annotations xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:noNamespaceSchemaLocation="annotations_xml_schema.xsd"
             Group="example XML">
			 
	
 <Expressions Search_For_Keywords="myKeyword"
			  Separator_Result_Name="," >
    <!-- Define annotation format in this
	section by adding <Expression/> elements -->
   
   <Expression Mode="SAME_LINE"
               Regex="myKeyword\s+(\w+(\s*,\s*\w+)*)"
               Rule_Identifier_Position="1"
               />	
	
   <Expression Mode="GOTO_INCREMENT"
               Regex="myKeyword\s+(\+\d+\s)(\w+(\s*,\s*\w+)*)"
               Increment_Position="1"
		  Rule_Identifier_Position="2"     
			   />	
	
  <Expression Mode="BEGIN"
               Regex="myKeyword\s*(\w+(\s*,\s*\w+)*)\s*Block_on"
               Rule_Identifier_Position="1"
		  Case_Insensitive="true"
			   />

   <Expression Mode="END"
               Regex="myKeyword\s*(\w+(\s*,\s*\w+)*)\s*Block_off"
               Rule_Identifier_Position="1"
			   />	
   <Expression Mode="END_ALL"
               Regex="myKeyword\sBlock_off_all"
			   />
	
			
   <Expression Mode="SAME_LINE"
               Regex="myKeywords\s+(\w+(\s*,\s*\w+)*)(\s*\[(\w+\s*)*([:]\s*(\w+\s*)+)*\])*(\s*-*\s*)*([^-]*)(\s*-*)*"
               Rule_Identifier_Position="1"
	         Status_Position="4"
		  Severity_Position="6"
		  Comment_Position="8"

               />	
		
	<!-- SAME_LINE example with more complex regular expression.
		Matches the following annotations:
		//myKeywords 50 [my_status:my_severity] -Additional comment-
		//myKeywords 50 [my_status]
		//myKeywords 50 [:my_severity]
		//myKeywords 50 -Additional comment-
			-->
					
 </Expressions>
 
 <Mapping>
	<!-- Map your annotation syntax to the Polyspace annotation
	syntax by adding <Result_Name_Mapping /> elements in this section -->
    <Result_Name_Mapping Rule_Identifier="100" Family="DEFECT" Result_Name="INT_ZERO_DIV"/>
	
	<Result_Name_Mapping Rule_Identifier="50" Family="MISRA-C3" Result_Name="8.4"/>
	<Result_Name_Mapping Rule_Identifier="51" Family="MISRA-C3" Result_Name="8.7"/>
	<Result_Name_Mapping Rule_Identifier="ALL_MISRA" Family="MISRA-C3" Result_Name="*"/>

 </Mapping>
</Annotations>

The XML file consists of two parts:

  • <Expressions>...</Expressions> where you define the format of your annotation syntax.

  • <Mapping>...</Mapping> where you map your syntax to the Polyspace annotation syntax.

After you edit this file, Polyspace can interpret your custom code annotation when you invoke the option -xml-annotations-description.

Define Annotation Syntax Format

To define an annotation syntax in Polyspace, your syntax must follow a pattern that you can represent with a regular expression. See Regular Expressions. It is recommended that you include a keyword in the pattern of your annotation syntax to help identify it. In this example, the keyword is myKeyword. Set the attribute Search_For_Keywords equal to this keyword.

Once you know the pattern of your annotation, you can define it in the XML by adding an <Expression/> element and specifying at least the attributes Mode, Regex, and Rule_Identifier_Position. For instance, the first <Expression/> element in annotations_description.xml defines an annotation with these attributes:

  • Mode="SAME_LINE". The annotation applies to code on the same line.

  • Regex="myKeyword\s+(\w+(\s*,\s*\w+)*)". Polyspace uses the regular expression to search for a string that begins with myKeyword, followed by a space \s+. Polyspace then searches for a capturing group (\w+(\s*,\s*\w+)*) that includes an alphanumeric rule identifier \w+ and, optionally, additional comma-separated rule identifiers (\s*,\s*\w+)*.

  • Rule_Identifier_Position="1". The integer value of this attribute corresponds to the number of opening parentheses preceding the relevant capturing group in the regular expression. In myKeyword\s+(\w+(\s*,\s*\w+)*), one opening parenthesis precedes the capturing group of the rule identifier (\w+(\s*,\s*\w+)*). If you want to match rule identifiers captured by (\s*,\s*\w+), then you set Rule_Identifier_Position="2" because two opening parentheses precede this capturing group.

The list of attributes and their values are listed in this table. The example column refers to the format defined in annotations_description.xml.

AttributeUseValueExample
ModeRequiredSAME_LINE

Applies only on the same line as the annotation.

code; //myKeyword 100
GOTO_INCREMENT

Applies on the same line as the annotation and the following n lines:

3. code; // myKeyword +3 ALL_MISRA
4. /*comments */			
5.	
6. code; 
7. code;

The preceding annotation applies to lines 3–6 only.

BEGIN

Applies to the same line and all following lines until a corresponding expression with attribute Mode="END" or "END_ALL", or until the end of the file.

 //myKeyword 50, 51 Block_on
 Code block 1;
 ...
END

Stops the application of a rule identifier declared by a corresponding expression with attribute Mode="BEGIN".

 //myKeyword 50, 51 Block_on
 Code block 1;
 ...
 More code;
 //myKeyword 50 Block_off

Only rule identifier 50 is turned off. Rule identifier 51 still applies.

END_ALL

Stops all rule identifiers declared by an expression with attribute Mode="BEGIN".

 //myKeyword 50, 51 Block_on
 Code block 1;
 ...
 More code;
 //myKeyword Block_off_all

Rule identifiers 50 and 51 are turned off.

RegexRequiredRegular expression search string

See Regular Expressions. Regex="myKeyword\s+(\w+(\s*,\s*\w+)*)" matches these expressions:

// myKeyword 50, 51
/* myKeyword ALL_MISRA, 100 */
Rule_Identifier_PositionRequired, except when you set Mode="END_ALL"Integer

The integer value of this attribute corresponds to the number of opening parentheses in the regular expression before the relevant search expression.

<Expression Mode="GOTO_INCREMENT"
            Regex="myKeyword\s+(\+\d+\s)(\w+(\s*,\s*\w+)*)"
            Increment_Position="1"
	     Rule_Identifier_Position="2"/>

The search expression for the rule identifier \w+(\s*,\s*\w+)* is after the second opening parenthesis of the regular expression.

Increment_PositionRequired only when you set Mode="GOTO_INCREMENT"Integer

The integer value of this attribute corresponds to the number of opening parentheses in the regular expression before the relevant search expression.

<Expression Mode="GOTO_INCREMENT"
            Regex="myKeyword\s+(\+\d+\s)(\w+(\s*,\s*\w+)*)"
            Increment_Position="1"
	     Rule_Identifier_Position="2"/>

The search expression for the increment \+\d+\s is after the first opening parenthesis of the regular expression.

Status_Position OptionalIntegerSee Increment_Position example. When you use this attribute, the entry in your annotation is displayed in the Status column on the Results List pane of the user interface.
Severity_Position OptionalIntegerSee Increment_Position example. When you use this attribute, the entry in your annotation is displayed in the Severity column on the Results List pane of the user interface.
Comment_Position OptionalIntegerSee Increment_Position example. When you use this attribute, the entry in your annotation is displayed in the Comment column on the Results List pane of the user interface. Your comment is appended to the string Justified by annotation in source:
Case_Insensitive OptionalTrue or false

When you set this attribute to "true", the regular expression is case insensitive, otherwise it is case sensitive. If you do not declare this attribute in your expression, the regular expression is case sensitive. For Case_Insensitive="true", these annotations are equivalent:

//MYKEYWORD ALL_MISRA BLOCK_ON

//mykeyword all_misra block_on

Map Your Annotation to the Polyspace Annotation Syntax

After you define your annotation format, you can map the rule identifiers you are using to their corresponding Polyspace annotation syntax. You can do this mapping by adding an <Result_Name_Mapping/> element and specifying attributes Rule_Identifier, Family, and Result_Name. For instance, if rule identifier 50 corresponds to MISRA C™: 2012 rule 8.4, map it to the Polyspace syntax MISRA-C3:8.4 by using this element:

<Result_Name_Mapping Rule_Identifier="50" Family="MISRA-C3" Result_Name="8.4"/>

The list of attributes and their values are listed in this table. The example column refers to the format defined in annotations_description.xml.

AttributeUseValueExample
Rule_IdentifierRequiredUser defined. Each value must be unique.See the mapping section of annotations_description.xml
FamilyRequiredCorresponds to Polyspace results family. For a list of allowed values, see allowed values.See the mapping section of annotations_description.xml
Result_NameRequiredCorresponds to Polyspace result names. For a list of allowed values, see allowed values.See the mapping section of annotations_description.xml

Define Multiple Custom Annotation Syntaxes

To define more than one annotation syntax, in your XML file, specify a comma separated list of keywords associated with each syntax for the Search_For_Keywords attribute.

For example, if you use custom annotations that follow these patterns to annotate violations of MISRA C: 2012 rules:

int func(int p) //customSyntax M123 $ customSyntax M124
{	
    int i;
    int j = 1;

    i = 1024 / (j - p); 
    return i;
}

int func2(void){ //otherCustomSyntax 50
	int x=func(2);
	return x; 
}
Enter the following in the XML file where you define the custom annotation syntax.
<?xml version="1.0" encoding="UTF-8"?>

<Annotations xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:noNamespaceSchemaLocation="annotations_xml_schema.xsd"
             Group="multipleCustomSyntax">
	<!-- Enter comma separated list of keywords -->		 
  <Expressions Search_For_Keywords="customSyntax,otherCustomSyntax"
			  Separator_Result_Name="$" >
			 							
	<!-- This section defines the annotation syntax format -->	  
   <Expression Mode="SAME_LINE"
               Regex="customSyntax\s(\w+(\s*,\s*\w+)*)"
               Rule_Identifier_Position="1"
               />
	<Expression Mode="SAME_LINE"
               Regex="otherCustomSyntax\s(\w+(\s*,\s*\w+)*)"
               Rule_Identifier_Position="1"
               />		   
 </Expressions>
  <!-- This section maps the user annotation to the Polyspace
  annotation syntax -->
 <Mapping>
	<!-- Mapping for customSyntax rules -->
	<Result_Name_Mapping  Rule_Identifier="M123" Family="MISRA-C3" Result_Name="8.7"/>
       <Result_Name_Mapping  Rule_Identifier="M124" Family="MISRA-C3" Result_Name="D4.6"/>
	<!-- Mapping for otherCustomSyntax rules  -->
    <Result_Name_Mapping  Rule_Identifier="50" Family="MISRA-C3" Result_Name="8.4"/>
 </Mapping>
</Annotations>
When you use multiple custom annotations, each rule identifier must be unique. For instance, in the preceding example, you cannot reuse rule identifier M123 with otherCustomSyntax.

See Also

Related Topics