Руководство по Ada (Ada 2022)

A.17 Пакет Environment_Variables

Пакет Environment_Variables позволяет программе читать или изменять переменные окружения. Переменные окружения — это пары имя-значение, где и имя, и значение являются строками. Определение того, что представляет собой переменная окружения, и значение имени и значения определяются реализацией.

Статическая семантика

Библиотечный пакет Environment_Variables имеет следующее объявление:

package Ada.Environment_Variables
with Preelaborate, Nonblocking, Global => in out synchronized is

function Value (Name : in String) return String;

function Value (Name : in String; Default : in String) return String;

function Exists (Name : in String) return Boolean;

procedure Set (Name : in String; Value : in String);

procedure Clear (Name : in String);
procedure Clear;

procedure Iterate
(Process : not null access procedure (Name, Value : in String))
with Allows_Exit;

end Ada.Environment_Variables;

function Value (Name : in String) return String;

Если внешняя среда выполнения поддерживает переменные окружения, то Value возвращает значение переменной окружения с заданным именем. Если переменной окружения с заданным именем не существует, то возбуждается Constraint_Error. Если среда выполнения не поддерживает переменные окружения, то возбуждается Program_Error.

function Value (Name : in String; Default : in String) return String;

Если внешняя среда выполнения поддерживает переменные окружения и в настоящее время существует переменная окружения с заданным именем, то Value возвращает её значение; в противном случае возвращается Default.

function Exists (Name : in String) return Boolean;

Если внешняя среда выполнения поддерживает переменные окружения и в настоящее время существует переменная окружения с заданным именем, то Exists возвращает True; в противном случае возвращает False.

procedure Set (Name : in String; Value : in String);

Если внешняя среда выполнения поддерживает переменные окружения, то Set сначала очищает все существующие переменные окружения с заданным именем, а затем определяет новую переменную окружения с заданным именем и значением. В противном случае возбуждается Program_Error.

Если по определению реализации недопустимо определение переменной окружения с заданным именем и значением, то возбуждается Constraint_Error.

Реализация определяет, существуют ли значения, для которых вызов Set(Name, Value) имеет тот же эффект, что и вызов Clear (Name).

procedure Clear (Name : in String);

Если внешняя среда выполнения поддерживает переменные окружения, то Clear удаляет все существующие переменные окружения с заданным именем. В противном случае возбуждается Program_Error.

procedure Clear;

Если внешняя среда выполнения поддерживает переменные окружения, то Clear удаляет все существующие переменные окружения. В противном случае возбуждается Program_Error.

procedure Iterate
(Process : not null access procedure (Name, Value : in String))
with Allows_Exit;

Если внешняя среда выполнения поддерживает переменные окружения, то Iterate вызывает процедуру, указанную Process, для каждой существующей переменной окружения, передавая имя и значение этой переменной окружения. В противном случае возбуждается Program_Error.

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

Ограниченные (временные) ошибки

Ошибка ограниченного типа возникает при вызове Value, если существует более одной переменной окружения с заданным именем; возможные исходы:

возвращается одно из значений, и это же значение возвращается при последующих вызовах в отсутствие изменений в окружении; или

возбуждается Program_Error.

Ошибочное выполнение

Одновременные вызовы процедур Set или Clear с вызовами любой процедуры пакета Environment_Variables или любого экземпляра Iterate приводят к ошибочному выполнению.

Вызовы процедур Set или Clear в фактической процедуре, соответствующей параметру Process в Iterate, приводят к ошибочному выполнению.

Требования к документации

Реализация должна документировать, как работают операции этого пакета, если переменные окружения изменяются внешними механизмами (например, вызовами системных функций операционной системы).

Разрешения для реализации