カスタム注釈形式の定義

この例では、XML ファイルを作成および編集して注釈形式を定義し、それを Polyspace® 注釈構文にマッピングする方法を示します。XML ファイルを作成して編集したら、オプション -xml-annotations-description を使用して、このファイルを Polyspace に渡します。

複数のカスタム注釈形式を定義するには、複数のカスタム注釈構文の定義を参照してください。

はじめに、次のコードをテキスト エディターにコピーして、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="RTE" Result_Name="ZDV"/>
	<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>

XML ファイルは次の 2 つの部分で構成されています。

  • <Expressions>...</Expressions>。ここで、注釈構文の形式を定義します。

  • <Mapping>...</Mapping>。ここで、構文を Polyspace 注釈構文にマッピングします。

このファイルを編集すると、オプション -xml-annotations-description を呼び出す場合に、Polyspace でカスタム コード注釈を解釈できるようになります。

注釈構文形式の定義

Polyspace の注釈構文を定義するには、構文は regex で表すことのできるパターンに従わなければなりません。正規表現を参照してください。注釈構文のパターンにキーワードを含めて、注釈構文を識別しやすくすることをお勧めします。この例では、キーワードは myKeyword です。属性 Search_For_Keywords をこのキーワードに設定します。

注釈のパターンを把握したら、<Expression/> 要素を追加して、少なくとも Mode、Regex、および Rule_Identifier_Position 属性を指定することで XML で注釈を定義できます。たとえば、annotations_description.xml の最初の <Expression/> 要素は、次の属性を使用して注釈を定義しています。

  • Mode="SAME_LINE".この注釈は同じ行のコードに適用されます。

  • Regex="myKeyword\s+(\w+(\s*,\s*\w+)*)".Polyspace では正規表現を使用して、myKeyword で始まり、スペース \s+ が続く文字列を検索します。Polyspace ではその後、英数字のルール識別子 \w+ およびオプションとして追加のコンマ区切りのルール識別子 (\s*,\s*\w+)* を含むキャプチャ対象グループ (\w+(\s*,\s*\w+)*) を検索します。

  • Rule_Identifier_Position="1".この属性の整数値は、正規表現内の関連するキャプチャ対象グループに先行する左かっこの数に対応します。myKeyword\s+(\w+(\s*,\s*\w+)*) の場合、ルール識別子のキャプチャ対象グループ (\w+(\s*,\s*\w+)*) に 1 つの左かっこが先行します。(\s*,\s*\w+) でキャプチャされるルール識別子を照合する場合は、このキャプチャ対象グループに 2 つの左かっこが先行するため、Rule_Identifier_Position="2" に設定します。

属性と値のリストを次の表に示します。例列は、annotations_description.xml で定義されている形式を表します。

属性使用値例
Mode必要SAME_LINE

注釈と同じ行にのみ適用されます。

code; //myKeyword 100
GOTO_INCREMENT

注釈と同じ行とそれに続く n 行に適用されます。

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

前記の注釈は行 3 ～ 6 にのみ適用されます。

BEGIN

同じ行と属性 Mode="END" または "END_ALL" が設定された対応する表現が出現するまでのすべての行、またはファイルの終端まで適用されます。

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

属性 Mode="BEGIN" が設定された対応する表現によって宣言されたルール識別子の適用を停止します。

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

ルール識別子 50 のみが無効になります。ルール識別子 51 は引き続き適用されます。

END_ALL

属性 Mode="BEGIN" が設定された表現によって宣言されたすべてのルール識別子を停止します。

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

ルール識別子 50 と 51 が無効になります。

Regex必要regex 検索文字列

正規表現を参照してください。Regex="myKeyword\s+(\w+(\s*,\s*\w+)*)" は次の表現に一致します。

// myKeyword 50, 51
/* myKeyword ALL_MISRA, 100 */
Rule_Identifier_Position必要 (Mode="END_ALL" を設定している場合を除く)整数

この属性の整数値は、関連する検索式の前の正規表現に含まれる左かっこの数に対応します。

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

ルール識別子 \w+(\s*,\s*\w+)* の検索式は、正規表現の 2 番目の左かっこの後です。

Increment_Position必要 (Mode="GOTO_INCREMENT" を設定している場合のみ)整数

この属性の整数値は、関連する検索式の前の正規表現に含まれる左かっこの数に対応します。

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

インクリメント \+\d+\s の検索式は、正規表現の 1 番目の左かっこの後です。

Status_Position オプション整数Increment_Position の例を参照してください。この属性を使用する場合、注釈のエントリは、ユーザー インターフェイスの [結果のリスト] ペインの [ステータス] 列に表示されます。
Severity_Position オプション整数Increment_Position の例を参照してください。この属性を使用する場合、注釈のエントリは、ユーザー インターフェイスの [結果のリスト] ペインの [重大度] 列に表示されます。
Comment_Position オプション整数Increment_Position の例を参照してください。この属性を使用する場合、注釈のエントリは、ユーザー インターフェイスの [結果のリスト] ペインの [コメント] 列に表示されます。コメントは文字列 Justified by annotation in source: に追加されます。
Case_Insensitive オプションtrue または false

この属性を "true" に設定すると、regex では大文字と小文字が区別されません。設定しない場合、大文字と小文字が区別されます。表現の中でこの属性を宣言しない場合、regex では大文字と小文字が区別されます。Case_Insensitive="true" の場合、次の注釈は等価です。

//MYKEYWORD ALL_MISRA BLOCK_ON

//mykeyword all_misra block_on

Polyspace 注釈構文への注釈のマッピング

注釈形式を定義したら、使用しているルール識別子を、対応する Polyspace 注釈構文にマッピングできます。このマッピングは、<Result_Name_Mapping/> 要素を追加して、属性 Rule_Identifier、Family、および Result_Name を指定して行うことができます。たとえば、ルール識別子 50 が MISRA C™:2012 Rule 8.4 に対応する場合、次の要素を使用して Polyspace 構文 MISRA-C3:8.4 にマッピングします。

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

属性と値のリストを次の表に示します。例列は、annotations_description.xml で定義されている形式を表します。

属性使用値例
Rule_Identifier必要ユーザー定義。各値は一意でなければなりません。annotations_description.xml のマッピング セクションを参照してください。
Family必要Polyspace の結果ファミリに対応します。指定可能な値の一覧は、指定可能な値を参照してください。annotations_description.xml のマッピング セクションを参照してください。
Result_Name必要Polyspace の結果名に対応します。指定可能な値の一覧は、指定可能な値を参照してください。annotations_description.xml のマッピング セクションを参照してください。

複数のカスタム注釈構文の定義

複数の注釈構文を定義するには、XML ファイルで Search_For_Keywords 属性の各構文と関連付けられているキーワードのコンマ区切りリストを指定します。

たとえば、MISRA C:2012 ルールの違反に注釈を付けるために以下のパターンに従うカスタム注釈を使用する場合を考えます。

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; 
}
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="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>
複数のカスタム注釈を使用する場合、各ルール識別子は一意でなければなりません。たとえば、前述の例では、ルール識別子 M123 を otherCustomSyntax で再利用することはできません。

参考

トピック