Справочник по Ada (Ada 2022)

A.16 Каталоги пакетов

Пакет Directories предоставляет операции для работы с файлами и каталогами, а также их именами.

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

В библиотечном пакете Directories имеется следующее объявление:

with Ada.IO_Exceptions;
with Ada.Calendar;
package Ada.Directories
with Global => in out synchronized is

-- Операции с каталогами и файлами:

function Current_Directory return String;

procedure Set_Directory (Directory : in String);

procedure Create_Directory (New_Directory : in String;
Form : in String := "");

procedure Delete_Directory (Directory : in String);

procedure Create_Path (New_Directory : in String;
Form : in String := "");

procedure Delete_Tree (Directory : in String);

procedure Delete_File (Name : in String);

procedure Rename (Old_Name, New_Name : in String);

procedure Copy_File (Source_Name,
Target_Name : in String;
Form : in String := "");

-- Операции с именами файлов и каталогов:

function Full_Name (Name : in String) return String
with Nonblocking;

function Simple_Name (Name : in String) return String
with Nonblocking;

function Containing_Directory (Name : in String) return String
with Nonblocking;

function Extension (Name : in String) return String
with Nonblocking;

function Base_Name (Name : in String) return String
with Nonblocking;

function Compose (Containing_Directory : in String := "";
Name : in String;
Extension : in String := "") return String
with Nonblocking;

type Name_Case_Kind is
(Unknown, Case_Sensitive, Case_Insensitive, Case_Preserving);

function Name_Case_Equivalence (Name : in String) return Name_Case_Kind;

-- Запросы к файлам и каталогам:

type File_Kind is (Directory, Ordinary_File, Special_File);

type File_Size is range 0 .. определяется реализацией;

function Exists (Name : in String) return Boolean;

function Kind (Name : in String) return File_Kind;

function Size (Name : in String) return File_Size;

function Modification_Time (Name : in String) return Ada.Calendar.Time;

-- Поиск в каталогах:

type Directory_Entry_Type is limited private;

type Filter_Type is array (File_Kind) of Boolean;

type Search_Type is limited private;

procedure Start_Search (Search : in out Search_Type;
Directory : in String;
Pattern : in String;
Filter : in Filter_Type := (others => True));

procedure End_Search (Search : in out Search_Type);

function More_Entries (Search : in Search_Type) return Boolean;

procedure Get_Next_Entry (Search : in out Search_Type;
Directory_Entry : out Directory_Entry_Type);

procedure Search (
Directory : in String;
Pattern : in String;
Filter : in Filter_Type := (others => True);
Process : not null access procedure (
Directory_Entry : in Directory_Entry_Type))
with Allows_Exit;

-- Операции с записями каталога:

function Simple_Name (Directory_Entry : in Directory_Entry_Type)
return String;

function Full_Name (Directory_Entry : in Directory_Entry_Type)
return String;

function Kind (Directory_Entry : in Directory_Entry_Type)
return File_Kind;

function Size (Directory_Entry : in Directory_Entry_Type)
return File_Size;

function Modification_Time (Directory_Entry : in Directory_Entry_Type)
return Ada.Calendar.Time;

Status_Error : exception renames Ada.IO_Exceptions.Status_Error;
Name_Error : exception renames Ada.IO_Exceptions.Name_Error;
Use_Error : exception renames Ada.IO_Exceptions.Use_Error;
Device_Error : exception renames Ada.IO_Exceptions.Device_Error;

private
... -- не определено языком
end Ada.Directories;

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

Имя файла — это строка, идентифицирующая внешний файл. Аналогично, имя каталога — это строка, идентифицирующая каталог. Интерпретация имен файлов и каталогов определяется реализацией.

Полное имя внешнего файла — это полное указание имени файла. Если внешняя среда допускает альтернативные указания имени (например, сокращения), полное имя не должно использовать такие альтернативы. Полное имя обычно включает имена всех каталогов, содержащих элемент. Простое имя внешнего файла — это имя элемента без указания содержащих его каталогов. Если не указано иное, параметр имени файла или каталога в вызове предопределённой подпрограммы ввода-вывода Ada может быть полным именем, простым именем или любой другой формой имени, поддерживаемой реализацией.

Корневой каталог — это каталог, не имеющий содержащего его каталога.

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

Запись каталога — это отдельный элемент в каталоге, идентифицирующий отдельный внешний файл (включая каталоги и специальные файлы).

Для каждой функции, возвращающей строку, нижняя граница возвращаемого значения равна 1.

Предоставляются следующие операции с файлами и каталогами:

function Current_Directory return String;

Возвращает полное имя каталога для текущего каталога по умолчанию. Возвращённое имя должно быть пригодным для последующего вызова Set_Directory. Исключение Use_Error передаётся, если внешняя среда не поддерживает каталог по умолчанию.

procedure Set_Directory (Directory : in String);

Устанавливает текущий каталог по умолчанию. Исключение Name_Error передаётся, если строка, указанная в качестве Directory, не идентифицирует существующий каталог. Исключение Use_Error передаётся, если внешняя среда не поддерживает установку Directory в качестве каталога по умолчанию.

procedure Create_Directory (New_Directory : in String;
Form : in String := "");

Создаёт каталог с именем New_Directory. Параметр Form может быть использован для задания системно-зависимых характеристик каталога; интерпретация параметра Form определяется реализацией. Пустая строка для Form указывает на использование по умолчанию опций реализации нового каталога. Исключение Name_Error передаётся, если строка, указанная в качестве New_Directory, не позволяет идентифицировать каталог. Исключение Use_Error передаётся, если внешняя среда не поддерживает создание каталога с данным именем (в отсутствие Name_Error) и формой.

procedure Delete_Directory (Directory : in String);

Удаляет существующий пустой каталог с именем Directory. Исключение Name_Error передаётся, если строка, указанная в качестве Directory, не идентифицирует существующий каталог. Исключение Use_Error передаётся, если каталог не пуст или внешняя среда не поддерживает удаление каталога с данным именем (в отсутствие Name_Error).

procedure Create_Path (New_Directory : in String;
Form : in String := "");

Создаёт ноль или более каталогов с именем New_Directory. Каждый несуществующий каталог, указанный в New_Directory, создаётся. Например, в типичной системе Unix Create_Path ("/usr/me/my"); создаст каталог "me" в каталоге "usr", а затем создаст каталог "my" в каталоге "me". Параметр Form может быть использован для задания системно-зависимых характеристик каталога; интерпретация параметра Form определяется реализацией. Пустая строка для Form указывает на использование по умолчанию опций реализации нового каталога. Исключение Name_Error передаётся, если строка, указанная в качестве New_Directory, не позволяет идентифицировать какой-либо каталог. Исключение Use_Error передаётся, если внешняя среда не поддерживает создание каких-либо каталогов с данным именем (в отсутствие Name_Error) и формой. Если Use_Error передаётся, не определено, создаётся ли часть пути каталога.

procedure Delete_Tree (Directory : in String);

Удаляет существующий каталог с именем Directory. Каталог и всё его содержимое (возможно, включая другие каталоги) удаляются. Исключение Name_Error распространяется, если строка, заданная как Directory, не идентифицирует существующий каталог. Исключение Use_Error распространяется, если внешняя среда не поддерживает удаление каталога или какой-либо части его содержимого с заданным именем (при отсутствии Name_Error). Если Use_Error распространяется, то не определено, удалена ли часть содержимого каталога.

процедура Delete_File (Name : in String);

Удаляет существующий обычный или специальный файл с именем Name. Исключение Name_Error распространяется, если строка, заданная как Name, не идентифицирует существующий обычный или специальный внешний файл. Исключение Use_Error распространяется, если внешняя среда не поддерживает удаление файла с заданным именем (при отсутствии Name_Error).

процедура Rename (Old_Name, New_Name : in String);

Переименовывает существующий внешний файл (включая каталоги) с именем Old_Name в New_Name. Исключение Name_Error распространяется, если строка, заданная как Old_Name, не идентифицирует существующий внешний файл или если строка, заданная как New_Name, не позволяет идентифицировать внешний файл. Исключение Use_Error распространяется, если внешняя среда не поддерживает переименование файла с заданным именем (при отсутствии Name_Error). В частности, Use_Error распространяется, если файл или каталог уже существует с именем New_Name.

процедура Copy_File (Source_Name,
Target_Name : in String;
Form : in String := "");

Копирует содержимое существующего внешнего файла с именем Source_Name во внешний файл с именем Target_Name. Результирующий внешний файл является дубликатом исходного внешнего файла. Параметр Form может использоваться для задания системно-зависимых характеристик результирующего внешнего файла; интерпретация параметра Form определена реализацией. Исключение Name_Error распространяется, если строка, заданная как Source_Name, не идентифицирует существующий внешний обычный или специальный файл, или если строка, заданная как Target_Name, не позволяет идентифицировать внешний файл. Исключение Use_Error распространяется, если внешняя среда не поддерживает создание файла с именем, заданным Target_Name, и формой, заданной Form, или копирование файла с именем, заданным Source_Name (при отсутствии Name_Error). Если Use_Error распространяется, то не определено, скопирована ли часть файла.

Предоставляются следующие операции с именами файлов и каталогов:

функция Full_Name (Name : in String) return String;

Возвращает полное имя, соответствующее имени файла, указанному в Name. Исключение Name_Error распространяется, если строка, заданная как Name, не позволяет идентифицировать внешний файл (включая каталоги и специальные файлы).

функция Simple_Name (Name : in String) return String;

Возвращает часть простого имени файла, указанного в Name. Простое имя корневого каталога — это имя самого корня. Исключение Name_Error распространяется, если строка, заданная как Name, не позволяет идентифицировать внешний файл (включая каталоги и специальные файлы).

функция Containing_Directory (Name : in String) return String;

Возвращает имя каталога, содержащего внешний файл (включая каталоги), идентифицированный по имени Name. (Если более одного каталога может содержать Name, то возвращаемое имя каталога определено реализацией.) Исключение Name_Error распространяется, если строка, заданная как Name, не позволяет идентифицировать внешний файл. Исключение Use_Error распространяется, если внешний файл не имеет содержащего каталога.

функция Extension (Name : in String) return String;

Возвращает имя расширения, соответствующее Name. Имя расширения — это часть простого имени (без разделителей), обычно используемое для идентификации класса файла. Если внешняя среда не имеет расширений имен, возвращается пустая строка. Исключение Name_Error распространяется, если строка, заданная как Name, не позволяет идентифицировать внешний файл.

функция Base_Name (Name : in String) return String;

Возвращает базовое имя, соответствующее Name. Базовое имя — это остаток простого имени после удаления расширения и разделителей расширения. Исключение Name_Error распространяется, если строка, заданная как Name, не позволяет идентифицировать внешний файл (включая каталоги и специальные файлы).

функция Compose (Containing_Directory : in String := "";
Name : in String;
Extension : in String := "") return String;

Возвращает имя внешнего файла со заданным Containing_Directory, Name и Extension. Если Extension — пустая строка, то Name интерпретируется как простое имя; в противном случае Name интерпретируется как базовое имя. Исключение Name_Error распространяется, если:

строка, заданная как Containing_Directory, не пуста и не позволяет идентифицировать каталог;

строка, заданная как Extension, не пуста и не является возможным расширением;

строка, заданная как Name, не является возможным простым именем (если Extension пусто) или базовым именем (если Extension не пусто); или

строка, заданная как Name, является корневым каталогом, а Containing_Directory или Extension не пустые.

функция Name_Case_Equivalence (Name : in String) return Name_Case_Kind;

Возвращает правило эквивалентности имен файлов для каталога, содержащего Name. Вызывает Name_Error, если Name не является полным именем. Возвращает Case_Sensitive, если имена файлов, отличающиеся только регистром букв, считаются разными именами. Если имена файлов, отличающиеся только регистром букв, считаются одинаковыми именами, то возвращается Case_Preserving, если регистр имени файла используется при создании файла; в противном случае возвращается Case_Insensitive. Возвращает Unknown, если правило эквивалентности имен файлов неизвестно.

Предоставляются следующие запросы и типы файлов и каталогов:

тип File_Kind is (Directory, Ordinary_File, Special_File);

Тип File_Kind представляет тип файла, представленного внешним файлом или каталогом.

тип File_Size is range 0 .. определённая реализацией;

Тип File_Size представляет размер внешнего файла.

функция Exists (Name : in String) return Boolean;

Возвращает True, если внешний файл, представленный Name, существует, и False в противном случае. Исключение Name_Error распространяется, если строка, заданная как Name, не позволяет идентифицировать внешний файл (включая каталоги и специальные файлы).

функция Kind (Name : in String) return File_Kind;

Возвращает тип внешнего файла, представленного Name. Исключение Name_Error распространяется, если строка, заданная как Name, не позволяет идентифицировать существующий внешний файл.

функция Size (Name : in String) return File_Size;

Возвращает размер внешнего файла, представленного Name. Размер внешнего файла — количество элементов потока, содержащихся в файле. Если внешний файл не является обычным файлом, результат определяется реализацией. Исключение Name_Error распространяется, если строка, заданная как Name, не позволяет идентифицировать существующий внешний файл. Исключение Constraint_Error распространяется, если размер файла не является значением типа File_Size.

функция Modification_Time (Name : in String) return Ada.Calendar.Time;

Возвращает время последнего изменения внешнего файла, представленного Name. Если внешний файл не является обычным файлом, результат определяется реализацией. Исключение Name_Error распространяется, если строка, заданная как Name, не позволяет идентифицировать существующий внешний файл. Исключение Use_Error распространяется, если внешняя среда не поддерживает чтение времени изменения файла с заданным именем (при отсутствии Name_Error).

Предоставляются следующие операции поиска по каталогам и типы:

тип Directory_Entry_Type is limited private;

Тип Directory_Entry_Type представляет один элемент в каталоге. Эти элементы могут быть созданы только процедурой Get_Next_Entry в этом пакете. Информацию об элементе можно получить из функций, объявленных в этом пакете. Объект этого типа, инициализированный по умолчанию, недействителен; объекты, возвращаемые из Get_Next_Entry, действительны.

тип Filter_Type is array (File_Kind) of Boolean;

Тип Filter_Type указывает, какие элементы каталога предоставляются из операции поиска. Если компонент Directory имеет значение True, предоставляются элементы каталога, представляющие каталоги. Если компонент Ordinary_File имеет значение True, предоставляются элементы каталога, представляющие обычные файлы. Если компонент Special_File имеет значение True, предоставляются элементы каталога, представляющие специальные файлы.

тип Search_Type is limited private;

Тип Search_Type содержит состояние поиска по каталогу. Объект Search_Type, инициализированный по умолчанию, не имеет доступных записей (функция More_Entries возвращает False). Тип Search_Type требует завершения (см. 7.6).

процедура Start_Search (Search : in out Search_Type;
Directory : in String;
Pattern : in String;
Filter : in Filter_Type := (others => True));

Начинает поиск в каталоге, указанном параметром Directory, по записям, соответствующим шаблону Pattern и фильтру Filter. Pattern представляет шаблон для сопоставления имён файлов. Если Pattern — пустая строка, все элементы в каталоге сопоставляются; в противном случае интерпретация Pattern определяется реализацией. Возвращаются только элементы, соответствующие фильтру Filter. После успешного вызова Start_Search, объект Search может содержать записи, но может и не содержать записей, если ни один файл или каталог не соответствует Pattern и Filter. Исключение Name_Error передаётся, если строка, заданная параметром Directory, не идентифицирует существующий каталог, или если Pattern не позволяет идентифицировать какой-либо возможный внешний файл или каталог. Исключение Use_Error передаётся, если внешняя среда не поддерживает поиск в каталоге с данным именем (при отсутствии Name_Error). Когда Start_Search передаёт Name_Error или Use_Error, объект Search не будет содержать записей.

процедура End_Search (Search : вход-выход Search_Type);

Завершает поиск, представленный объектом Search. После успешного вызова End_Search, объект Search не будет содержать записей.

функция More_Entries (Search : вход Search_Type) возвращает Boolean;

Возвращает True, если доступны дополнительные записи для возврата функцией Get_Next_Entry для указанного объекта поиска, и False в противном случае.

процедура Get_Next_Entry (Search : вход-выход Search_Type;
Directory_Entry : выход Directory_Entry_Type);

Возвращает следующую запись Directory_Entry для поиска, описанного объектом Search, которая соответствует шаблону и фильтру. Если больше совпадений нет, возникает ошибка Status_Error. Реализация определяет, изменятся ли результаты, возвращаемые этой подпрограммой, если содержимое каталога изменится во время существования объекта Search (например, другой программой). Исключение Use_Error передаётся, если внешняя среда не поддерживает продолжение поиска в каталоге, представленном объектом Search.

процедура Search (
Directory : вход String;
Pattern : вход String;
Filter : вход Filter_Type := (others => True);
Process : не null доступная процедура (
Directory_Entry : вход Directory_Entry_Type))
с Allows_Exit;

Ищет в каталоге, указанном параметром Directory, записи, соответствующие Pattern и Filter. Подпрограмма, обозначенная параметром Process, вызывается для каждой соответствующей записи по очереди. Pattern представляет шаблон для сопоставления имён файлов. Если Pattern — пустая строка, все элементы в каталоге сопоставляются; в противном случае интерпретация Pattern определяется реализацией. Возвращаются только элементы, соответствующие фильтру Filter. Исключение Name_Error передаётся, если строка, заданная параметром Directory, не идентифицирует существующий каталог, или если Pattern не позволяет идентифицировать какой-либо возможный внешний файл или каталог. Исключение Use_Error передаётся, если внешняя среда не поддерживает поиск в каталоге с данным именем (при отсутствии Name_Error).

функция Simple_Name (Directory_Entry : вход Directory_Entry_Type)
возвращает String;

Возвращает простое внешнее имя внешнего файла (включая каталоги), представленного Directory_Entry. Формат возвращаемого имени определяется реализацией. Исключение Status_Error передаётся, если Directory_Entry недействителен.

функция Full_Name (Directory_Entry : вход Directory_Entry_Type)
возвращает String;

Возвращает полное внешнее имя внешнего файла (включая каталоги), представленного Directory_Entry. Формат возвращаемого имени определяется реализацией. Исключение Status_Error передаётся, если Directory_Entry недействителен.

функция Kind (Directory_Entry : вход Directory_Entry_Type)
возвращает File_Kind;

Возвращает тип внешнего файла, представленного Directory_Entry. Исключение Status_Error передаётся, если Directory_Entry недействителен.

функция Size (Directory_Entry : вход Directory_Entry_Type)
возвращает File_Size;

Возвращает размер внешнего файла, представленного Directory_Entry. Размер внешнего файла — это количество элементов потока, содержащихся в файле. Если внешний файл, представленный Directory_Entry, не является обычным файлом, результат определяется реализацией. Исключение Status_Error передаётся, если Directory_Entry недействителен. Исключение Constraint_Error передаётся, если размер файла не является значением типа File_Size.

функция Modification_Time (Directory_Entry : вход Directory_Entry_Type)
возвращает Ada.Calendar.Time;

Возвращает время последнего изменения внешнего файла, представленного Directory_Entry. Если внешний файл, представленный Directory_Entry, не является обычным файлом, результат определяется реализацией. Исключение Status_Error передаётся, если Directory_Entry недействителен. Исключение Use_Error передаётся, если внешняя среда не поддерживает чтение времени изменения файла, представленного Directory_Entry.

Требования к реализации

Для Copy_File, если Source_Name идентифицирует существующий обычный внешний файл, созданный предопределённым пакетом ввода-вывода Ada, и Target_Name и Form могут быть использованы в операции Create этого пакета ввода-вывода с режимом Out_File без возникновения исключения, то Copy_File не должен передавать Use_Error.

A.16 Каталоги пакетов

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

Требования к реализации

Рекомендации по реализации