Exponenta Banner
exponenta event banner

Определение пользовательского формата аннотаций

В этом примере показано, как создать и отредактировать XML-файл, чтобы определить формат аннотации и сопоставить его с синтаксисом аннотации Polyspace ®. После создания и редактирования XML-файла передайте его в Polyspace с помощью опции-xml-annotations-description.

Чтобы определить несколько пользовательских форматов аннотаций, см. раздел Определение нескольких пользовательских синтаксисов аннотаций.

Для начала скопируйте следующий код в текстовый редактор и сохраните его на компьютере как 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-файл состоит из двух частей:

  • <Expressions>...</Expressions> где определяется формат синтаксиса аннотаций.

  • <Mapping>...</Mapping> где синтаксис сопоставляется с синтаксисом аннотации Polyspace.

После редактирования этого файла приложение Polyspace может интерпретировать пользовательскую аннотацию кода при вызове опции -xml-annotations-description.

Определение синтаксического формата аннотаций

Чтобы определить синтаксис аннотации в Polyspace, синтаксис должен следовать шаблону, который можно представить регулярным выражением. См. раздел Регулярные выражения. Рекомендуется включить ключевое слово в шаблон синтаксиса аннотации для его идентификации. В этом примере ключевое слово: myKeyword. Установка атрибута Search_For_Keywords равно этому ключевому слову.

Как только вы знаете образец аннотации, вы можете определить его в XML, добавив <Expression/> элемент и указание, по крайней мере, атрибутов Mode, Regex, и Rule_Identifier_Position. Например, первый <Expression/> элемент в annotations_description.xml определяет аннотацию со следующими атрибутами:

  • 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+)*). Если вы хотите сопоставить идентификаторы правил, захваченные (\s*,\s*\w+), затем вы устанавливаете 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="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+)* после второй открывающей круглой скобки регулярного выражения.

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 после первой открывающей круглой скобки регулярного выражения.

Status_Position ДополнительныйЦелое числоПосмотрите Increment_Position пример. При использовании этого атрибута запись в аннотации отображается в столбце Статус (Status) панели Список результатов (Results List) интерфейса пользователя.
Severity_Position ДополнительныйЦелое числоПосмотрите Increment_Position пример. При использовании этого атрибута запись в аннотации отображается в столбце Серьезность (Severity) на панели Список результатов (Results List) интерфейса пользователя.
Comment_Position ДополнительныйЦелое числоПосмотрите Increment_Position пример. При использовании этого атрибута запись в аннотации отображается в столбце Комментарий (Comment) на панели Список результатов (Results List) интерфейса пользователя. Комментарий добавлен к строке Justified by annotation in source:
Case_Insensitive ДополнительныйПравда или ложь

Если для этого атрибута задано значение «true», регулярное выражение не учитывает регистр, в противном случае - регистр. Если этот атрибут не объявлен в выражении, регулярное выражение чувствительно к регистру. Для 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 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.

См. также

Связанные темы

Документация по программе проверки кода Polyspace

Поддержка