Справочное руководство Ada 2012

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

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

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 (при отсутствии Name_Error) в качестве каталога по умолчанию.

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 null) или базовым именем (если Extension не null).

функция 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) возвращает Булево;

Возвращает 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 : вход Строка;
Pattern : вход Строка;
Filter : вход Filter_Type := (другие => True);
Process : непустой доступный процедура (
Directory_Entry : вход Directory_Entry_Type));

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

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

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

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

Возвращает полное внешнее имя внешнего файла (включая каталоги), представленного 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 Каталоги пакетов

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

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

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