ASIS-for-GNAT Reference Manual

( GNAT-3.15p )

(C) Copyright 2000, Ada Core Technologies, Inc.

Перевод Copyright (C) 2003 А.Гавва.
Коммерческое распространение перевода, без разрешения автора перевода, запрещено.

Содержание

Об этом руководстве

Это руководство содержит информацию, которая может быть полезна при написании инструментальных средств и приложений, использующих реализацию ASIS 95 для Ada95-компилятора GNAT (ASIS-для-GNAT). Кроме того, руководство содержит информацию о характеристиках, которые зависят от реализации ASIS-для-GNAT.

ASIS был специально разработан как переносимый базис (основа) для множества инструментальных средств анализа Ада-кода. Однако, поскольку ASIS разрабатывался с целью использования с большим числом Ада-компиляторов, он также содержит множество свойств, которые характерны для использования конкретной реализации при взаимодействии с внутренними структурами реализации Ада-системы, а также привилегиями реализации на выполнение некоторых запросов.

Следует заметить, что любое приложение ASIS, использующее свойства, которые зависят от реализации, может быть непереносимым. При этом следует изолировать и хорошо документировать любые фрагменты программы, которые используют такие свойства непереносимым образом.

Что содержится в данном руководстве

Это руководство содержит следующие главы:

Что Вам необходимо знать перед чтением этого руководства

Это руководство предполагает, что Вы знакомы с языком программирования Ada95, который описан в интернациональном стандарте ANSI/ISO/IEC-8652:1995, январь 1995, и с ASIS 95, который описан в интернациональном стандарте ISO/IEC 15291:1999.

Кроме того, это руководство полагается на некоторые факты, которые описаны в руководстве пользователя ASIS-для-GNAT (ASIS-for-GNAT User's Guide).

Дополнительная информация

При необходимости получения дополнительной информации, следует обратиться к следующим документам:

1. ASIS-для-GNAT и стандарт ASIS

В настоящий момент описание ASIS для Ada95 (ASIS 95) существует как интернациональный стандарт ISO/IEC 15291:1999. ASIS-для-GNAT поддерживает интерфейс ASIS 95 в соответствии с требованиями стандарта ASIS. Кроме того, ASIS-для-GNAT включает некоторые расширения ASIS (см. 2. Расширения ASIS), которые допускаются стандартом ASIS (секция 1.1.3.1).

Некоторые запросы, в некоторых ситуациях могут привести к возбуждению исключения Asis_Failed со статусом Not_Implemented_Error. Это подразумевает, что некоторые функциональные части данного запроса еще не реализованы. Если Вы столкнулись с подобной ситуацией, то сообщите об этом, как об обычной ошибке ASIS-для-GNAT. Нашей главной задачей является наличие полной реализации ASIS 95, в соответствии со стандартом ASIS.

ASIS-для-GNAT содержит спецификации для всех интерфейсных пакетов ASIS, которые определены стандартом ASIS, за исключением необязательного дополнения декомпозиции данных (Data Decomposition Annex). Эти спецификации неизменно соответствуют стандарту, за исключением добавления комментариев в начале спецификаций, добавления спецификаторов контекста with, добавления описаний в приватных частях спецификаций и некоторого переформатирования, которое необходимо для поддержки соответствия стиля оформления исходных текстов GNAT. Единственным действительным исключением является перемещение запроса Is_Dispatching_Operation из Asis.Expressions в Asis.Declarations.

2. Расширения ASIS

ASIS-для-GNAT предусматривает некоторые дополнительные запросы как расширение ASIS. Все эти запросы определены и отдокументированы в иерархии пакетов, корнем которой является пакет Asis.Extensions. Далее, в этом руководстве, эти пакеты будут упоминаться как "расширения ASIS" или "расширенные запросы ASIS".

Все расширения ASIS подчиняются основным правилам ASIS: при использовании расширений ASIS, Вы должны следовать требуемой последовательности вызовов; только стандартно определенные исключения ASIS могут распространяться за пределы расширенных запросов ASIS. Если документация на исключение запроса ASIS содержит список подходящих видов элементов, то этот запрос может применяться только к элементам Elements из этого списка, в противном случае будет возбуждаться исключение ASIS_Inappropriate_Element со статусом Value_Error. Если документация на исключение запроса ASIS содержит список ожидаемых видов элементов, то этот запрос может применяться к какому-либо элементу Element любого вида, однако запрос будет возвращать осмысленные результаты только для элементов Elements из списка.

Текущий набор расширений ASIS возник из нужд реализации ASIS и из разработки некоторых инструментальных средств ASIS, разработанных внутри группы разработки ASIS-для-GNAT. В нынешнем состоянии подразумевается, что иерархия Asis.Extensions - не стабильна, то есть, некоторые существующие запросы могут быть удалены, а некоторые новые запросы могут добавлены. Нам будут весьма интересны отзывы разработчиков ASIS-приложений, поскольку это позволит нам реализовать в ASIS-для-GNAT компактный и полезный набор расширеных запросов.

В настоящее время, иерархия Asis.Extensions содержит корневой пакет Asis.Extensions, описывающий набор расширений различного предназначения, и единственный дочерний пакет Asis.Extensions.Flat_Kinds, который описывает "плоскую" классификацию элементов.

Пакет Asis.Extensions содержит следующие расширенные типы и запросы (за подпробностями следует обратится к спецификации пакета Asis.Extensions, которая храниться в файле с именем asis-extensions.ads):

  1. Типы для списков динамических элементов и компилируемых модулей: 

      

   type Element_List_Access is access Element_List;
   type Compilation_Unit_List_Access is
      access Compilation_Unit_List;

    Какое-либо приложение может использовать динамическую аллокацию для сохранения результатов запросов возвращающих списки (вместо описания списка локальных переменных в блоке инструкций).

  2. Заполнители для конкретизации Traverse_Element: 

      

   type No_State is (Not_Used);
   --  Заполнитель для формального типа State_Information

   procedure No_Op
     (Element : Asis.Element;
      Control : in out Traverse_Control;
      State   : in out No_State);
   --  Заполнитель для формальной процедуры Post_Operation

    В большинстве простых случаев конкретизации Traverse_Element, единственно необходимым фактическим параметром является фактический параметр для Pre_Operation, таким образом, такие заполнители для переходного состояния и пост-операции могут быть использованы для получения правомерной конкретизации.

  3. Тестовые функции: 

      

   function Is_Primitive_Operation (Declaration : Asis.Element)
     return Boolean;
   --  Проверяет является ли ее аргумент определением какой-либо
   --  примитивной операции (определяемой пользователем) какого-нибудь типа
   --  (ожидается как явное так и неявное определение)

   function Acts_As_Spec (Declaration : Asis.Element)
     return Boolean;
   --  Проверяет отсутствие отдельного описания подпрограммы
   --  для данного описания тела или "заглушки" тела

   function Is_Renaming_As_Body (Declaration : Asis.Element)
     return Boolean;
   --  Проверяет является ли ее аргумент описанием
   --  renaming-as-body

   function Is_Completed (Declaration : Asis.Element)
     return Boolean;
   --  Проверяет имеет ли ее аргумент (который ожидается как
   --  описание требующее завершение) завершение в его текущем
   --  окружающем контексте

   function Is_True_Expression (Expression : Asis.Expression)
     return Boolean;
   --  Проверяет является ли выражение Expression каким-либо
   --  выражением Ады (то есть, выражением соответствующим
   --  определению в RM 4.4), и может ли тип этого выражения
   --  быть представлен в ASIS. В случаях когда An_Expression Element
   --  для которого Is_True_Expression возвращает True,
   --  запрос Corresponding_Expression_Type должен вернуть
   --  результат не-Nil

   function Is_Static (Expression : Asis.Expression)
     return Boolean;
   --  Проверяет является ли выражение Expression статическим
   --  с точки зрения GNAT (то есть, вычисляет ли компилятор значение
   --  выражения Expression в процессе компиляции).
   --  Мы надеемся, что это понятие/представление статического выражения
   --  максимально близко определению статического выражения в RM 95,
   --  однако мы не можем этого гарантировать.

  4. Модифицированные версии "первичных" запросов ASIS: 

      

   generic
      type State_Information is limited private;

      with procedure Pre_Operation
                       (Element : in     Asis.Element;
                        Control : in out Traverse_Control;
                        State   : in out State_Information) is <>;

      with procedure Post_Operation
                       (Element : in     Asis.Element;
                        Control : in out Traverse_Control;
                        State   : in out State_Information) is <>;

   procedure Traverse_Unit
     (Unit    : in     Asis.Compilation_Unit;
      Control : in out Traverse_Control;
      State   : in out State_Information);
   --  Обобщенная версия Asis.Iterator.Traverse_Element.
   --  Пересекает всю структуру аргумента модуля компиляйии Unit

   function Formal_Subprogram_Default
     (Declaration : in Asis.Generic_Formal_Parameter)
      return Asis.Expression;
   --  Модифицированная версия запроса
   --  Asis.Declarations.Formal_Subprogram_Default.
   --  Возвращает Nil_Element вместо возбуждения исключения
   --  Asis_Inappropriate_Element, когда Subprogram_Default_Kinds
   --  ее аргумента не является A_Name_Default

   function Primary_Owner
     (Declaration : Asis.Declaration)
      return        Asis.Declaration;
   --  В случае, когда аргумент Declaration является Is_Primary_Operation
   --  для какого-либо тэгового типа, эта функция возвращает описание
   --  тэгового типа для которого Declaration является первичной операцией

   function Corresponding_Called_Function_Unwinded
     (Expression : in Asis.Expression)
      return Asis.Declaration;
   --  Это модифицированная версия
   --  Asis.Expressions.Corresponding_Called_Function, которая
   --  "раскручивает" все переименования в случае, когда имя функции,
   --  в аргументе вызова функции, описано как определение переименования.
   --  Эта функция возвращает описание "входа" вызываемой функции.

   function Corresponding_Called_Entity_Unwinded
     (Statement : in Asis.Statement)
      return Asis.Declaration;
   --  Это модифицированная версия
   --  Asis.Statements.Corresponding_Called_Entity, которая "раскручивает"
   --  все переименования в случае, когда имя процедуры или входа,
   --  в аргументе вызова, описано как определение переименования.
   --  Эта функция возвращает описание сущности, которая может быть вызвана.

  5. Расширение функциональности ASIS: 

      

   function Is_Obsolete (Right : Asis.Compilation_Unit)
     return Boolean;
   --  Проверяет является ли модуль устаревшим.

   type Source_File_Statuses is
     (No_File_Status, Absent, Older,  Newer, Up_To_Date);

   function Source_File_Status
     (Right : Asis.Compilation_Unit)
      return  Source_File_Statuses;
   --  Проверяет состояние файла с исходным текстом для модуля,
   --  который указан с помощью аргумента

   function Is_Main_Unit_In_Tree
     (Right : Asis.Compilation_Unit)
      return  Boolean;
   --  Проверяет является ли указанный в аргументе модуль главным модулем
   --  для какой-либо компиляции, которая создает дерево внутри набора
   --  файлов деревьев, создавая объемлющий контекст.

   function Compilation_Dependencies
     (Main_Unit : Asis.Compilation_Unit)
      return      Asis.Compilation_Unit_List;
   --  Предоставляет полный список модулей, в системе компилятора GNAT,
   --  от которых зависит модуль Main_Unit.

   function Corresponding_First_Definition
     (Defining_Name : in Asis.Defining_Name)
      return Asis.Defining_Name;
   --  В случае когда существует более одного описания аргумента
   --  Defining_Name, обеспечивающего одно и то же представление
   --  для одной и той же сущности, эта функция возвращает первое
   --  описание, которое реально определяет сущность.

   function Corresponding_Body_Parameter_Definition
     (Defining_Name : Asis.Defining_Name)
      return          Asis.Defining_Name;
   --  Когда аргумент Defining_Name является именем формального параметра
   --  подпрограммы, эта функция возвращает описание имени этого параметра
   --  из тела подпрогрпммы.

   function Element_Span_In_Template
     (Element : Asis.Element)
      return    Asis.Text.Span;
   --  Если Is_Part_Of_Instance имеет значение True,
   --  для аргумента Element, то эта функция возвращает расстояние
   --  до соответствующего фрагмента кода в настраиваемом шаблоне.
   --  В противном случае, функция возвращщает Nil_Span.
   --  Функция также возвращает Nil_Span, когда Is_Part_Of_Implicit,
   --  для аргумента Element, имеет значение True.

   function Element_Image_In_Template
     (Element : Asis.Element)
      return    Program_Text;
   --  Если Is_Part_Of_Instance имеет значение True, для аргумента Element,
   --  то эта функция возвращает образ соответствующего фрагмента кода
   --  в настраиваемом шаблоне. В противном случае, функция возвращщает
   --  пустую строку (null string).
   --  Функция также возвращает пустую строку, когда
   --  Is_Part_Of_Implicit_Element, для аргумента Element,
   --  имеет значение True.

  6. Расширения общего назначения: 

      

   function Get_Last_Component (E : Asis.Element)
     return Asis.Element;
   --  Возвращает для аргумента крайний справа компонент

   function Components (E : Asis.Element) return Asis.Element_List;
   --  Возвращает для аргумента список всех компонентов первого уровня

Пакет Asis.Extensions.Flat_Kinds содержит описание типа Flat_Element_Kinds. Этот тип определяет "плоскую" классификацию элементов, которая является эквивалентом классификационной иерархии, определенной в пакете Asis: каждое значение вида из оригинальной иерархии, обладающее подчиненным видом, заменяется на соответствующий подчиненный диапазон. Кроме того, пакет Asis.Extensions.Flat_Kinds предусматривает функции преобразования из "плоской" классификации в оригинальную классификационную иерархию.

3. Свойства характерные для реализации и привилегии реализации

В ASIS существует три вида зависимостей реализации.

Во-первых, подпрограммы ASIS, которые описывают интерфейс между реализацией ASIS и внутренними структурами реализации Ада-системы, обладают параметрами, которые характерны для реализации. Существуют три запроса этого вида: Asis.Implementation.Initialize, Asis.Implementation.Finalize и Asis.Ada_Enfironments.Associate, - все они имеют параметр строкового типа, именуемый Parameters, который обладает характерным для реализации смыслом. Смысл строки Parameters (в ASIS-для-GNAT) рассматривается в секции 3.1 Взаимодействие с внутренними структурами Ада-реализации.

Во-вторых, некоторые массивы ASIS рассматриваются как создающие проблемы для реализации ASIS. Для таких массивов, рабочий черновик ASIS (Asis Working Draft) содержит явные привилегии реализации, которые позволяют какой-либо реализации ASIS не реализовывать некоторую функциональность ASIS или реализовывать ее ограниченным образом. Каждая из таких привелегий обычно затрагивает более одного отдельного запроса ASIS. Пакет Asis.Implementation.Permissions содержит логические запросы, которые известят Вас о том какой выбор был сделан для этих привилегий реализации в данной реализации ASIS. Решения выбранные в ASIS-для-GNAT для этих общих привилегий реализации рассматриваются в секции 3.2 Привилегии реализации.

В третьих, для некоторых запросов ASIS, привилегии реализации, которые характерны для данного запроса, явно указываются в рабочем черновике ASIS (Asis Working Draft). Для некоторых других запросов, результат запроса может зависеть от реализации поскольку это весьма характерно для запроса, даже если это явно не сказано в стандарте ASIS. Подобные запросы рассматриваются в секции 3.3 Запросы ASIS имеющие характерные для реализации привилегии или результаты.

3.1 Взаимодействие с внутренними структурами Ада-реализации

3.1.1 Формат строки Parameters

Строка Parameters является параметром для трех подпрограмм ASIS: Asis.Implementation.Initialize, Asis.Implementation.Finalize и Asis.Ada_Environments.Associate. Для всех этих подпрограмм, следующие требования являются общими:

3.1.2 Параметры процедуры Asis.Implementation.Initialize

Допустимыми параметрами parameters для Asis.Implementation.Initialize являются:

-d<debug_flag>
устанавливает для ASIS-для-GNAT отладочный флаг <debug_flag> в состояние ON
-dall
устанавливает для ASIS-для-GNAT в состояние ON все флаги отладки.
-w<warning_mode>
устанавливает для ASIS-для-GNAT режим предупреждений (в настоящий момент в состоянии разработки)

Флагом отладки <debug_flag> может быть любая буква нижнего регистра от 'a' до 'z' или любая цифра от '0' до '9' (в настоящее время не все соответствующие опции реализованы).

Флаги отладки ASIS документируются в файле a_debug.adb (см. также секцию 4.2 Флаги отладки ASIS).

Режим предупреждений <warning_mode> может быть 's', что подразумевает подавление всех предупреждающих сообщений (suppress all the warning messages), или 'e', что подразумевает трактовать любое предупреждение как ошибку (treat every warning as an error). В последнем случае, каждое предупреждающее сообщение будет конвертироваться в возбуждение исключения Asis_Failed с предупреждающим сообщением в качестве строк диагностики ASIS (ASIS Diagnosis strings).

При установке в строке диагностики более одного параметра, управляющего режимом предупреждающих сообщений, каждый из них будет изменять режим предупреждающих сообщений в том месте где он указан.

Для получения более полной информации о предупреждающих сообщениях, следует обратиться к руководству пользователя по ASIS-для-GNAT (ASIS-for-GNAT Users' Guide).

3.1.3 Параметры процедуры Asis.Implementation.Finalize

В текущей версии ASIS-для-GNAT процедура Asis.Implementation.Finalize не допускает использования параметров parameters.

Вызов Asis.Implementation.Finalize устанавливает все общие параметры parameters ASIS-для-GNAT в значения по умолчанию (таким образом, все флаги отладки устанавливаются в OFF, и режим предупреждающих сообщений устанавливается в режим предупреждающих сообщений по умолчанию).

3.1.4 Параметры процедуры Asis.Implementation.Associate

Для этого запроса допустимы следующие параметры parameters:

-C1
какой-либо контекст Context устанавливается одиночным файлом дерева, имя этого файла дерева должно быть явно указано в строке Parameters;

-CN
какой-либо контекст Context устанавливается набором файлов деревьев, имена этих файлов должны быть явно указаны в строке Parameters;

-CA
какой-либо контекст Context устанавливается всеми файлами деревьев, которые расположены в пути поиска файлов деревьев;

-FS
все деревья, которые рассматриваются как устанавливающие контекст Context, созданы "на лету", вне зависимости от существования файла дерева; однажды созданный файл дерева далее может использоваться повторно до тех пор, пока контекст Context остается открытым;

-FT
используются только предварительно созданные деревья, ASIS не может создать файл дерева;

-FM
смешанный подход: если требуемое дерево не существует, то осуществляется попытка создать это дерево "на лету";

-SA
исходные тексты для всех компилируемых модулей, принадлежащих к контексту Context (кроме предопределенного пакета Standard), рассматриваются при проверке согласованности в процессе открытия контекста Context;

-SE
только существующие файлы с исходными текстами для всех компилируемых модулей, принадлежащих к контексту Context, рассматриваются при проверке согласованности в процессе открытия контекста Context;

-SN
не учитывать файлы с исходными текстами, расположенные в файловой системе, при проверке согласованности набора файлов деревьев формирующих контекст Context;

-I<dir>
определяет каталог поиска файлов с исходными текстами;

-T<dir>
определяет каталог поиска файлов с деревьями;

<file_name>
определяет имя файла дерева;

Для параметров -I и -T, <dir> должен обозначать существующий каталог файловой системы. Допускается использование нотации "." и "..", а также абсолютных и относительных имен каталогов. Когда <dir> указывает на несуществующий каталог, возбуждается исключение Asis_Failed со статусом Parameter_Error.

Имя файла дерева, указанное с помощью параметра <file_name>, может содержать (или не содержать) информацию о каталоге.

Путь поиска ассоциированный с контекстом Context состоит из каталогов перечисленных как параметры parameters для запроса Asis.Ada_Environments.Associate, в той же последовательности, в которой они были включены в фактическую строку параметров Parameters. Для ASIS, путь поиска исходных файлов состоит только из каталогов следующих за '-I', а путь поиска файлов деревьев состоит только из каталогов следующих за '-T'. Когда значение строки параметров Parameters не указывает каталог исходных текстов (файлов деревьев), ASIS рассматривает для поиска исходных текстов (файлов деревьев) только текущий каталог, в противном случае текущий каталог включается в путь поиска исходных текстов (файлов деревьев) только в случае его явного указания с помощью '-I' или '-T' соответственно.

Если контекст Context ASIS ассоциирован с помощью опции -FS или -FM, то при вызове GNAT, для создания файлов деревьев, будет необходим путь поиска исходных текстов модулей контекста Context, для создания их файла дерева и поиска других файлов с исходными текстами. Например, когда мы имеем:

    

   Asis.Ada_Environments.Associate
     (My_Cont,
     "My_Cont_Name",
     "-CA -FS -I./dir -I.");

тогда, при обработке вызова:

    

   My_Unit := Asis.Compilation_Units.Library_Unit_Declaration
     ("Foo", My_Cont);

ASIS сначала пытается найти файл с исходным текстом foo.ads в каталоге ./dir, и если эта попытка неудачна, то он пытается обнаружить его в текущем каталоге. Если файл с исходным текстом обнаружен (предположим, в текущем каталоге), ASIS вызывает GNAT, для создания файла дерева, следующим образом:

    

   gcc -c -gnatc -gnatt -I./dir -I. -I- foo.ads

Если какой-либо контекст Context ASIS ассоциирован с помощью опции -CA, то, когда этот контекст открыт, ASIS обрабатывает все файлы деревьев расположенные в пути поиска файлов деревьев ассоциированном с этим контекстом.

На комбинирование параметров parameters, в фактической строке Parameters запроса Asis.Ada_Environments.Associate, накладываются следующие ограничения:

В случае установки неподходящей комбинации, возбуждается исключение Asis_Failed со статусом Parameter_Error.

В случае, когда фактическая строка параметров Parameters, при обращении к запросу Associate, является пустой строкой, параметрами по умолчанию будут "-CA -FT -SA".

Стедует заметить, что определения параметров parameters позднее могут быть изменены.

Для параметра Name, в качестве фактического значения, при обращении к запросу Asis.Ada_Environments.Associate, может быть передана любая строка. В текущей версии ASIS-для-GNAT отсутствует проверка фактических значений и семантическая ассоциация параметра Name при обращении к запросу Asis.Ada_Environments.Associate.

3.2 Привилегии реализации

3.2.1 Запросы Asis.Implementation.Permissions

Логические запросы, определенные в пакете Asis.Implementation.Permissions, возвращают, в ASIS-для-GNAT, следующие результаты:

    

   Is_Formal_Parameter_Named_Notation_Supported   True
   Default_In_Mode_Supported                      True
   Generic_Actual_Part_Normalized                 False
   Record_Component_Associations_Normalized       False
   Is_Prefix_Call_Supported                       True
   Function_Call_Parameters_Normalized            False
   Call_Statement_Parameters_Normalized           False
   Discriminant_Associations_Normalized           False
   Is_Line_Number_Supported                       True
   Is_Span_Column_Position_Supported              True
   Is_Commentary_Supported                        True
   Attributes_Are_Supported                       False
   Implicit_Components_Supported                  False +
   Object_Declarations_Normalized                 False
   Predefined_Operations_Supported                False +
   Inherited_Declarations_Supported               False +
   Inherited_Subprograms_Supported                False +
   Generic_Macro_Expansion_Supported              True

+ - См. секцию 3.2.2 Обработка неявных элементов

3.2.2 Обработка неявных элементов

ASIS Elements представляет как явные, так и неявные компоненты Ада-программ. Существуют запросы ASIS, которые способны вернуть неявные элементы Elements (таким образом, Elements представляют неявные конструкции Ады) или которые использовать неявные элементы Elements в качестве своих параметров.

Стандарт ASIS позволяет реализации ASIS не поддерживать неявные элементы или обеспечивать ограниченную поддержку неявных элементов. Если какая-либо реализация не поддерживает представление неявных элементов какого-либо вида неявных конструкций Ады, это подразумевает, что соответствующие запросы ASIS будут возвращать Nil_Element в случаях когда, в соответствии с определенными в RM синтаксисом и семантикой Ады, запросы ASIS должны возвращать неявные элементы Elements представляющие неявные конструкции.

В настоящее время, неявные элементы Elements частично поддерживаются в ASIS-для-GNAT. В случае наследования неявно описанных подпрограмм пользователя, запросы Asis.Expressions.Corresponding_Name_Definition, Asis.Expressions.Corresponding_Called_Function и Asis.Statements.Corresponding_Called_Entity возвращают непустой (non-nil) результат, представляя соответствующую сущность. В случае неявно описанных предопределенных операций, возвращается Nil_Element.

Нашей финальной задачей является получение в ASIS-для-GNAT наличия полной реализации для всех неявных конструкций Ады.

3.2.3 Одновременная обработка нескольких контекстов

Стандарт ASIS указывает, что число одновременно ассоциированных и открытых контекстов, а также число одновременно обрабатываемых модулей компиляции определяется реализацией ASIS. ASIS-для-GNAT не накладывает никаких ограничений на число одновременно ассоциированных и открытых контекстов в приложении ASIS, а также на число одновременно обрабатываемых модулей компиляции, которые могут быть получены от всех открытых контекстах до тех пор, пока используемые приложением системные ресурсы не исчерпали установленные системные лимиты.

Следует однако заметить, для контекста ассоциированного с опцией -FS или -FM, все деревья созданные "на лету", в процессе получения компилируемых модулей от этого контекста, помещаются в текущий каталог. Если текущий каталог содержит также некоторые файлы деревьев, принадлежащих другому контексту, то такие файлы могут быть повреждены. Для обработки, безопасным образом, более одного контекста, приложение должно иметь максимум один контекст, ассоциированный с опцией -FS или -FM Более того, при одновременной обработке нескольких контекстов, существует один контекст, который может создавать деревья "на лету", все остальные контексты не должны использовать файлы деревьев располагающиеся в текущем каталоге.

3.2.4 Типы и значения определяемые реализацией

Все определяемые реализацией типы, подтипы и значения зависят от подтипа Implementation_Defined_Integer_Type и от Implementation_Defined_Integer_Constant определенных в пакете Asis. ASIS-для-GNAT не изменяет определения, которые даны в спецификации пакета Asis согласно стандарта ASIS:

    

    subtype Implementation_Defined_Integer_Type is Integer;
    Implementation_Defined_Integer_Constant : constant := 2**31-1;

Все типы (подтипы) ASIS используются как индексы для типов-массивов ASIS, используя значение Implementation_Defined_Integer_Constant в качестве верхней границы.

3.3 Запросы ASIS имеющие характерные для реализации привилегии или результаты

Эта секция содержит документацию особенностей реализации запросов обладающих привилегиями реализации (указанные как "--|IP sentinel" в описании ASIS) или запросов, чье поведение может обладать какими-либо осмысленными особенностями реализации. Эти запросы упорядочены в соответствие с перечислением в описании ASIS. Нам понадобилось сохранение нумерации предложений из описания ASIS, путем помещения нумерации в одиночные кавычки, чтобы избежать путаницы с номерами секций в этом руководстве.

Результаты, возвращаемые ASIS-запросом Debug_Image, обсуждаются в секции 4.1 Интерпретация образов отладки.

    

'8'  package Asis.Ada_Environments

'8.1'  function Default_Name
       - возвращает "null string";

'8.2'  function Default_Parameters
       - возвращает "null string";

'8.4'  procedure Open
       - что происходит во время открытия контекста:

         - для контекста Context ассоциированного с опцией -CA:
           - если также установлена опция -FS, ничего не происходит;
           - если также установлена опция -FT или -FM,
             все файлы деревьев (то есть, файлы с суффиксом .adt),
             в пути поиска файлов деревьев, ассоциируются
             с обрабатываемым контекстом. Для каждого файла дерева
             выполняется попытка его чтения, после чего проверяется
             что этот файл был создан с опцией -gnatc.
             Файлы деревьев которые не могут быть прочитаны
             и которые созданы без указания опции -gnatc
             - игнорируются.
             Для всех остальных деревьев, ASIS накапливает некоторую
             информацию "черного-ящика" о компилируемых модулях,
             которые представлены этими деревьями, и осуществляет
             проверку согласованности для каждого обнаруженного
             в дереве модуля (обратитесь к рассмотрению проблем
             согласованности в "ASIS-for-GNAT Users' Guide").
             При любой ошибке согласованности, возбуждается исключение
             Asis_Failed и контекст Context остается закрытым.

         - для контекста Context ассоциированного с опцией -C1 или -CN:
           ASIS обрабатывает все файлы деревьев, ассоциируемых
           с контекстом Context, накапливая информацию "черного-ящика"
           и выполняя проверку согласованности для всех обнаруженных
           компилируемых модулей.
           Если, по какой-либо причине, файл дерева не может быть прочитан,
           для контекста ассоциированного с опцией -C1, возбуждается
           исключение Asis_Failed и контекст Context остается закрытым;
           для контекста, ассоциированного с опцией -CN, ASIS генерирует
           предупреждающее сообщение и процесс открытия контекста
           продолжается.
           При любой ошибке согласованности, возбуждается исключение
           Asis_Failed и контекст Context остается закрытым.

'10' package Asis.Compilation_Units

'10.3'  function Unit_Origin
        - возвращает источник A_Predefined_Unit для компилируемых
          модулей перечисленных в RM95, Annex A (2), причем,
          только для этих модулей;
        - возвращает источник An_Implementation_Unit для компилируемых
          модулей, которые являются компонентами библиотеки
          времени выполнения GNAT, но которые не рассматриваются
          в RM95, Annex A (2);
        - возвращает источник An_Application_Unit для всех остальных
          компилируемых модулей;


'10.6'  function Library_Unit_Declaration
'10.7'  function Compilation_Unit_Body
        - при обработке контекста Context, ассоциированного с опцией
          -FS или -FM, для обоих запросов, если ASIS не может
          обнаружить требуемый модуль в файлах деревьев, которые
          уже обработаны, ASIS пытается создать необходимое дерево
          путем обнаружения исходного текста модуля и компиляции
          исходного текста "на лету". Если эта попытка, по какой-либо
          причине, не удачна, возвращается Nil_Compilation_Unit;

'10.13' function Corresponding_Declaration:
        - ASIS-для-GNAT не использует модули компиляции ASIS
          вида An_Unknown_Unit;
        - если какой-либо аргумент принадлежит к классу
          A_Public_Declaration_And_Body, то возвращается
          Nil_Compilation_Unit;

'10.14' function Corresponding_Body
        - ASIS-для-GNAT не использует модули компиляции ASIS
          вида An_Unknown_Unit;

'10.22' function Can_Be_Main_Program
        - для GNAT, любая библиотечная процедура без параметров
          и любая библиотечная функция без параметров,
          возвращающая результат любого целочисленного типа,
          классифицируется этим запросом как (возможно)
          главная подпрограмма раздела;
        - Если для подобной библиотечной подпрограммы существуют
          тело и спецификация, как достижимые из данного контекста
          компилируемые модули ASIS, то они оба рассматриваются
          как Can_Be_Main_Program

'10.24' function Text_Name
        - эта функция возвращает имя файла с исходным текстом
          компилируемого модуля Compilation_Unit. Это имя файла
          может включать (или не включать) префикс, указывающий
          каталог в котором располагается файл; каталог может
          быть указан в абсолютной или относительной форме,
          в зависимости от опций командной строки, которые
          использовались при вызове GNAT для создания
          соответствующего файла дерева;
        - эта функция не проверяет существование соответствующего
          файла с исходным текстом, она только отображает
          ситуацию, которая существовала на момент создания
          соответствующего файла дерева. Следовательно,
          если Вы удалите или переместите соответствующий
          файл с исходным текстом после создания файла дерева,
          полное имя файла, возвращенное этой функцией,
          ножет быть некорректным;
        - в случае несогласованности (то есть, когда для создания
          файлов деревьев, формирующих контекст ASIS,
          использовалось несколько версий файла с исходным
          текстом модуля), будет возвращено имя последней версии
          файла с исходным текстом.

'10.25' function Text_Form
        - В модели компиляции GNAT, все файлы с исходными текстами
          являются обычными текстовыми файлами в используемой
          файловой системе. Следовательно, эта функция всегда
          возвращает Nil_Asis_String, для индикации того, что
          Text_IO.Open использует опции по умолчанию
          для манипулирования исходными текстами Ады.

'10.29' function Has_Attribute
        - Возвращает False. ASIS-для-GNAT не предусматривает
          каких-либо дополнительных атрибутов для компилируемых
          модулей.

'10.30' function Attribute_Value_Delimiter
        - Возвращает (wide) строку единичной длины, которая
          содержит (wide) символ LF.

'10.31' function Attribute_Values
        - возвращает "null string";


'11' package Asis.Compilation_Units.Times

'11.2'  function Time_Of_Last_Update
        - Эта функция возвращает метку времени соответствующего
          файла с исходным текстом. Соответствующим файлом
          с исходным текстом является файл имя которого
          может быть получено с помощью использования вызова
          Asis.Compilation_Units.Text_Name. Можно сказать,
          что эта функция возвращает время последней модификации
          исходного текста модуля.

'13' package Asis.Elements

'13.3'  function Context_Clause_Elements
        - Эта функция в точности возвращает инструкции и директивы,
          которые присутствуют в исходном тексте модуля.
        - Возвращает Nil_Element_List для Nonexistent или Unknown модуля.
        - Возвращает Nil_Element_List для предопределенного пакета
          Standard. Для всех остальных предопределенных компилируемых
          модулей, возвращает их спецификаторы контекста
          в том виде, в котором они присутствуют в исходных
          текстах содержащихся в библиотеке GNAT Run-Time.

'13.5'  function Compilation_Pragmas
        - Эта функция в точности возвращает директивы,
          которые присутствуют в исходном тексте модуля
          (и те которые расположены в спецификации контекста,
          и те которые расположены после завершения текста модуля)
        - Возвращает Nil_Element_List для Nonexistent или Unknown модуля.
        - Возвращает Nil_Element_List для предопределенного пакета
          Standard. Для всех остальных предопределенных компилируемых
          модулей, возвращает их спецификаторы контекста
          в том виде, в котором они присутствуют в исходных
          текстах содержащихся в библиотеке GNAT Run-Time.

'13.36' function Enclosing_Element
        - ASIS-для-GNAT фактически не требует параметр Element_Context.
          Функция Enclosing_Element с двумя параметрами просто
          вызывает функцию Enclosing_Element с одним параметром
          для своего параметра Element.


'15' package Asis.Declarations

'15.24' function Body_Block_Statement
        - Если тело, переданое как фактический параметр, не содержит
          в себе описаний, то Asis.Statements.Is_Declare_Block
          возвращает FALSE как результат этой функции.

'17' package Asis.Expressions

'17.6'  function Corresponding_Name_Definition
        - Когда какое-либо имя ссылки аргумента определено неявно,
          и если оно обозначает унаследованную подпрограмму
          пользователя, то будет возвращено соответствующее
          непустое (non-nil) имя описания элемента Element.
          В противном случае, функция возвращает Nil_Element.

'17.8'  function Corresponding_Name_Declaration
        - Когда какое-либо имя ссылки аргумента определено неявно,
          и если оно обозначает унаследованную подпрограмму
          пользователя, то будет возвращено соответствующее
          непустое (non-nil) имя описания элемента Element.
          В противном случае, функция возвращает Nil_Element.

'17.29' function Corresponding_Called_Function
        - Для неявно определенной функции, когда фактический
          параметр является выражением, которое представляет
          вызов предопределенной операции, будет возвращаться
          Nil_Element. Если фактический параметр является
          вызовом неявно определенной унаследованной
          операцией пользователя, то будет возвращаться
          соответствующее (неявное) определение функции.

'18' package Asis.Statements

'18.14' function Is_Declare_Block
        - Когда аргумент представляет пустой (dummy) блок
          инструкций, созданный с помощью вызова функции
          Asis.Declarations.Body_Block_Statement,
          возвращаемый результат будет True только в случае,
          когда соответствующее тело содержит в себе
          описания.


'20' package Asis.Text

'20.1'  type Line
        - Lines в ASIS-для-GNAT не содержат какой-либо символ,
          который обозначает конец строки, в соответствие
          с RM95, 2.2(2)

'20.22' function Delimiter_Image
        - Возвращает (wide) строку единичной длины, содержащую
          (wide) символ LF.

3.4 Ограничения характерные для опций -FS и -FM

Следующие запросы Asis.Compilation_Units не реализованы для контекста Context, который ассоциирован с опциями -FS и -FM:

    

   Library_Unit_Declarations
   Compilation_Unit_Bodies
   Compilation_Units
   Corresponding_Children
   Corresponding_Body (формально, эта функция реализована,
                       однако она может возвращать плохие
                       результаты)
   Subunits

4. Отладочная информация

Существует два вида отладочной информации доступной в ASIS-для-GNAT: образы отладки, возвращаемые ASIS-запросами Debug_Image для контекстов Contexts, компилируемых модулей Compilation Units и элементов Elements, и вывод отладки, генерируемый ASIS-запросами когда соответствующий отладочный флаг реализации установлен в состояние ON во время инициализации ASIS (см. 3.1.2 Параметры процедуры Asis.Implementation.Initialize).

4.1 Интерпретация образов отладки

Образы отладки, генерируемые для главной абстракции ASIS, легко интерпретировать поскольку большая часть генерируемой информации непосредственно соответствует представлениям ASIS. Следующие детали образов отладки являются зависимыми от реализации:

4.2 Флаги отладки ASIS

ASIS предусматривает некоторые внутренние отладочные флаги, которые описываются в a_debug.adb. Установки этих флагов генерируют (на устройство стандартного вывода) полезную внутреннюю отладочную информацию. Эта информация не всегда ориентирована на пользователя, однако следующие флаги отладки могут быть полезны для пользователя ASIS:

-dc
Выводит содержимое внутренних структур данных контекста, при закрытии или деассоциации контекста. Анализ этой информации позволяет отобразить другую отладочную информацию на идентификаторы модуля и дерева.

-di
Отключает включение расположения элемента Element в его образ отладки Debug_Image. Это может оказаться полезным когда ASIS-программа разрушается в результате каких-либо проблем структурных запросов ASIS (структурные запросы используются запросом образа отладки элемента для вычисления расположения аргумента в исходном тексте).

-do
Когда контекст Context открыт, отображает список обработанных файлов деревьев и выбранный для представления данного контекста файл дерева.

-dt
Выводит сообщение при каждом чтении файла дерева. Эта информация может быть полезной для анализа профиля обмена дерева (tree swapping profile) вашего приложения для сокращения числа обменов дерева.