Справочник Ada 2005

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

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

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

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

with Ada.IO_Exceptions;
with Ada.Calendar;
package Ada.Directories 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;

function Simple_Name (Name : in String) return String;

function Containing_Directory (Name : in String) return String;

function Extension (Name : in String) return String;

function Base_Name (Name : in String) return String;

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

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

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));

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

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) и формой.

procedure Delete_Tree (Directory : in String);

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

procedure 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, не идентифицирует существующий внешний файл. Исключение 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).

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

функция 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, не равна null и не позволяет идентифицировать каталог, или если строка, заданная как Extension, не равна null и не является возможным расширением, или если строка, заданная как Name, не является возможным простым именем (если Extension равно null) или основным именем (если Extension не равно null).

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

тип 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. Pattern представляет шаблон для сопоставления имён файлов. Если Pattern равно null, все элементы каталога соответствуют; в противном случае интерпретация 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 : in out Search_Type);

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

функция More_Entries (Search : in Search_Type) return Boolean;

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

процедура Get_Next_Entry (Search : in out Search_Type;
Directory_Entry : out Directory_Entry_Type);

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

процедура Search (
Каталог : вход Строка;
Шаблон : вход Строка;
Фильтр : вход Тип_фильтра := (другие => Истина);
Обработка : не null доступная процедура (
Элемент_каталога : вход Тип_элемента_каталога));

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

функция Простое_Имя (Элемент_каталога : вход Тип_элемента_каталога)
возвращает Строка;

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

функция Полное_Имя (Элемент_каталога : вход Тип_элемента_каталога)
возвращает Строка;

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

функция Тип (Элемент_каталога : вход Тип_элемента_каталога)
возвращает Тип_файла;

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

функция Размер (Элемент_каталога : вход Тип_элемента_каталога)
возвращает Размер_файла;

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

функция Время_изменения (Элемент_каталога : вход Тип_элемента_каталога)
возвращает Ada.Calendar.Время;

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

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

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

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

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

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

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