Главная » Haskell » Модуль Directory

0

В модуле Directory определены системонезависимые функции для  работы с каталогами файловой системы. Использование модуля:

import System.Directory

Каждый  идентификатор каталога  содержит набор элементов,  являющихся поименованными указателями на некоторый объект в  файловой системе (файлы, каталоги и т. д.). Некоторые такие объекты могут быть скрыты, недоступны или иметь определённые  административные функции (например, объекты «.» или «..»). Однако в данном модуле все элементы идентификатора  каталога рассматриваются в качестве  содержимого каталога,  за исключением  содержимого подкаталогов текущего каталога.

К произвольному  элементу файловой структуры можно обратиться при помощи пути. В большинстве операционных систем к каждому объекту имеется по крайней мере один абсолютный путь. В некоторых  операционных системах можно использовать относительные пути.

Функция: createDirectory

Описание: создаёт новый  каталог  по  заданному пути.  Этот  каталог  изначально является пустым  (настолько, насколько  позволяет операционная система). Данная функция может  завершиться неуспешно в случаях: у процесса недостаточно прав  доступа для создания каталога  (isPermissionError или PermissionDenied);  аргумент указывает на каталог,  который  уже  существует (isAlreadyExistsError или  AlreadyExists); произошла ошибка ввода/вывода на физическом уровне (HardwareFault);  аргумент не является валидным идентификатором каталога (InvalidArgument); не существует пути к создаваемому

каталогу (NoSuchThing); недостаточно памяти или других ресурсов для создания каталога  (ResourceExhausted); и наконец, заданный  путь указывает на объект, который не является каталогом (InappropriateType).

Определение:

createDirectory ::  FilePath ->  IO ()

Функция определена в виде примитива.

Функция: createDirectoryIfMissing

Описание: создаёт новый каталог, если его ещё не существует.  Если первый аргумент принимает значение True, то эта функция также создаёт все родительские  каталоги, если они отсутствуют.

Определение:

createDirectoryIfMissing :: Bool  ->  FilePath ->  IO ()

createDirectoryIfMissing  parents file

= do b < doesDirectoryExist  file case (b,  parents, file)  of

(_,       _, "")  -> return () (True,  _,   _)  -> return ()

(_,  True,    _)  ->  mapM_  (createDirectoryIfMissing  False) (tail  (pathParents file))

(_, False,  _)  ->  createDirectory file

Функция: removeDirectory

Описание: удаляет существующий каталог,  заданный при  помощи  пути.  Реализация и операционная система могут  требовать  выполнения дополнительных ограничений перед удалением каталога (например, такое ограничение, что удаляемый каталог  должен быть пуст).  Данная функция может завершиться неуспешно в случаях: произошла ошибка ввода/вывода на  физическом уровне (HardwareFault);  аргумент не является  валидным идентификатором каталога (InvalidArgument);  удаляемого каталога  не существует (isDoesNotExistError или  NoSuchThing); у процесса недостаточно  прав доступа, чтобы  удалить каталог (isPermissionErrorPermissionDenied или  PermissionDenied);  невыполненные требования для удаления каталога (UnsatisfiedConstraints); операция по удалению не  поддерживается (UnsupportedOperation); и наконец, аргумент указывает на объект, не являющийся каталогом (InappropriateType).

Определение:

removeDirectory :: FilePath  ->  IO ()

Функция определена в виде примитива.

Функция: removeDirectoryRecursive

Описание: аналог функции removeDirectory, который удаляет заданный каталог рекурсивно со всеми его подкаталогами и файлами.

Определение:

removeDirectoryRecursive :: FilePath  ->  IO () removeDirectoryRecursive  startLoc

= do cont  < getDirectoryContents startLoc

sequence_ [rm  (startLoc ‘joinFileName‘ x) | x  < cont, x  /=  "." &&  x  /= ".."] removeDirectory startLoc

where

rm :: FilePath ->  IO ()

rm f = do temp < try  (removeFile f) case  temp of

Left e   ->  do isDir  < doesDirectoryExist f unless  isDir $  ioError  e removeDirectoryRecursive  f

Right   _ ->  return ()

Функция: renameDirectory

Описание: переименовывает  заданный каталог.  Старый каталог  определяется первым аргументом, новый — вторым. Если каталог,  заданный новым идентификатором, уже  существует, он заменяется  старым каталогом.  Данная функция может завершиться неуспешно в случаях: произошла ошибка ввода/вывода на физическом уровне (HardwareFault);  аргумент не является валидным идентификатором каталога (InvalidArgument); переименовываемого каталога не существует (isDoesNotExistError или NoSuchThing); у процесса  недостаточно прав доступа, чтобы переименовать  каталог  (isPermissionErrorPermissionDenied или PermissionDenied); невыполненные требования для переименования каталога (UnsatisfiedConstraints); операция по переименованию не поддерживается (UnsupportedOperation); и наконец, аргумент  указывает на объект, не являющийся каталогом (InappropriateType).

Определение:

renameDirectory :: FilePath ->  FilePath ->  IO ()

Функция определена в виде примитива.

Функция: getDirectoryContents

Описание: возвращает список всех объектов в заданном каталоге. Данная функция может завершиться неуспешно в случаях: произошла ошибка ввода/вывода на физическом уровне (HardwareFault);  аргумент не является валидным идентификатором каталога  (InvalidArgument); запрашиваемого  каталога  не существует (isDoesNotExistError или NoSuchThing); у процесса недостаточно  прав доступа, чтобы просканировать каталог  (isPermissionErrorPermissionDenied или PermissionDenied); недостаточно памяти или других ресурсов для выполнения операции (ResourceExhausted); и наконец, аргумент указывает на объект, не являющийся каталогом (InappropriateType).

Определение:

getDirectoryContents :: FilePath ->  IO  [FilePath]

Функция определена в виде примитива.

Функция: getCurrentDirectory

Описание: если в  операционной системе используется понятие  текущего каталога, то  эта  функция  возвращает путь  к нему.  Данная  функция  может завершиться неуспешно в случаях:  произошла ошибка ввода/вывода на физическом  уровне   (HardwareFault);    запрашиваемого каталога   не  существует  (isDoesNotExistError  или  NoSuchThing); у  процесса   недостаточно  прав доступа, чтобы  получить  каталог  (isPermissionErrorPermissionDenied  или PermissionDenied); недостаточно памяти или других ресурсов для выполнения операции (ResourceExhausted); и наконец, аргумент указывает на объект, не являющийся каталогом (InappropriateType).

Определение:

getCurrentDirectory ::  IO FilePath

Функция определена в виде примитива.

Функция: setCurrentDirectory

Описание: если в операционной системе используется понятие текущего каталога, то эта функция устанавливает новый текущий каталог по заданному пути. Дан-

ная функция может завершиться неуспешно в случаях: произошла ошибка ввода/вывода на физическом уровне (HardwareFault); аргумент не является валидным идентификатором каталога  (InvalidArgument); запрашиваемого каталога не существует (isDoesNotExistError или NoSuchThing); у процесса недостаточно прав доступа, чтобы сохранить каталог (isPermissionErrorPermissionDenied или PermissionDenied); недостаточно памяти или других ресурсов для выполнения операции (ResourceExhausted); и наконец, аргумент указывает на объект, не являющийся каталогом (InappropriateType).

Определение:

setCurrentDirectory :: FilePath  ->  IO ()

Функция определена в виде примитива.

Функция: getHomeDirectory

Описание:   возвращает  домашний  каталог    текущего   пользователя    (если такое   понятие  используется  в   текущей   операционной   системе).  Данная функция   может   завершиться  неуспешно  в    случаях:   операция  не   поддерживается (UnsupportedOperation);   получаемого каталога   не  существует (isDoesNotExistError или NoSuchThing).

Определение:

getHomeDirectory :: IO  FilePath

Функция определена в виде примитива.

Функция: getAppUserDataDirectory

Описание: возвращает каталог текущего пользователя для хранения приложений и релевантных данных (если такое понятие используется в текущей операционной системе). Данная функция может завершиться неуспешно в случаях: операция не поддерживается (UnsupportedOperation); получаемого каталога не существует (isDoesNotExistError или NoSuchThing).

Определение:

getAppUserDataDirectory :: String ->  IO  FilePath

Функция определена в виде примитива.

Функция: getUserDocumentsDirectory

Описание: возвращает каталог  текущего  пользователя для  хранения   документов (если такое понятие используется в текущей  операционной системе).

Данная функция может завершиться неуспешно в случаях:  операция не поддерживается (UnsupportedOperation);   получаемого каталога   не  существует (isDoesNotExistError или NoSuchThing).

Определение:

getUserDocumentsDirectory ::  IO FilePath

Функция определена в виде примитива.

Функция: getTemporaryDirectory

Описание: возвращает каталог  текущего пользователя,  используемый для хранения временных данных (если такое понятие используется в текущей операционной системе). Данная функция может завершиться неуспешно в случае, если операция не поддерживается (UnsupportedOperation).

Определение:

getTemporaryDirectory ::  IO FilePath

Функция определена в виде примитива.

Функция: removeFile

Описание: удаляет каталог  для заданного файла (который  сам  по  себе  каталогом не является). Реализация и  операционная  система могут  требовать выполнения дополнительных ограничений  перед удалением  каталога.  Данная функция  может  завершиться  неуспешно в  случаях: произошла ошибка ввода/вывода на  физическом уровне (HardwareFault);  аргумент не является валидным идентификатором каталога  (InvalidArgument);  удаляемого  каталога не существует (isDoesNotExistError или NoSuchThing); у процесса недостаточно прав доступа, чтобы удалить каталог (isPermissionErrorPermissionDenied или  PermissionDenied);   невыполненные требования для  удаления каталога (UnsatisfiedConstraints); и наконец, аргумент указывает на объект, не являющийся каталогом (InappropriateType).

Определение:

removeFile ::  FilePath ->  IO ()

Функция определена в виде примитива.

Функция: renameFile

Описание: изменяет идентификатор некоторого существующего  объекта файловой системы на  новый. Если объект, заданный  новым идентификатором,

уже  существует, он заменяется старым объектом. Данная функция  может завершиться неуспешно в случаях: произошла ошибка  ввода/вывода на физическом уровне (HardwareFault);   аргумент не  является валидным идентификатором  объекта (InvalidArgument);  переименовываемого  объекта не  существует (isDoesNotExistError  или NoSuchThing); у процесса недостаточно  прав доступа, чтобы   переименовать объект  (isPermissionErrorPermissionDenied или PermissionDenied);  недостаточно ресурсов для переименовывания объекта (ResourceExhausted); невыполненные требования для  переименования каталога (UnsatisfiedConstraints); операция по переименованию не поддерживается (UnsupportedOperation); и  наконец,  аргумент указывает на объект, не являющийся каталогом (InappropriateType).

Определение:

renameFile  :: FilePath ->  FilePath  ->  IO ()

Функция определена в виде примитива.

Функция: copyFile

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

Определение:

copyFile :: FilePath ->  FilePath  ->  IO ()

copyFile fromFPath  toFPath  = do readFile fromFPath  >>= writeFile  toFPath try  (copyPermissions  fromFPath  toFPath) return  ()

Функция: canonicalizePath

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

Определение:

canonicalizePath :: FilePath ->  IO  FilePath canonicalizePath fpath =  return fpath

Функция: findExecutable

Описание: для заданного имени файла ищет упоминание такового  в  переменной окружения PATH, возвращая, в случае наличия, абсолютный путь к файлу. Возвращает значение Nothing, если ничего не найдено.

Определение:

findExecutable :: String ->  IO  (Maybe FilePath) findExecutable  binary

= withCString binary $

\c_binary ->  withCString (’.’:exeExtension)  $

\c_ext ->  allocaBytes  long_path_size $

\pOutPath  ->  alloca $

\ppFilePart ->  do res  < c_SearchPath  nullPtr  c_binary c_ext

(fromIntegral long_path_size)  pOutPath  ppFilePart if res  > 0 &&  res  <  fromIntegral  long_path_size

then  do fpath < peekCString  pOutPath return  (Just fpath)

else  return  Nothing

Функция: doesFileExist

Описание: возвращает значение IO Bool в случае, если объект по заданному пути существует, а также не является каталогом.

Определение:

doesFileExist ::  FilePath  ->  IO Bool

Функция определена в виде примитива.

Функция: doesDirectoryExist

Описание: возвращает значение IO Bool в случае, если объект по заданному пути существует, а также не является файлом.

Определение:

doesDirectoryExist ::  FilePath  ->  IO Bool

Функция определена в виде примитива.

Тип: Permissions

Описание: тип, представляющий  набор прав доступа к  определённому объекту файловой системы. Единственный одноимённый конструктор параметризует четыре поля типа Bool.  Первое поле определяет флаг, возводимый тогда, когда объект доступен для чтения. Второй поле — флаг доступности для записи.

Третье поле —  флаг, указывающий на то, что объект является  исполняемым. Наконец, четвёртое  поле — флаг, указывающий на то, что объект можно найти средствами операционной системы.

Определение:

data  Permissions

=  Permissions

{

readable, writable,  executable,  searchable :: Bool

}

Данный тип является экземпляром следующих классов: Eq, Ord, Read и Show.

Функция: getPermissions

Описание: по заданному пути к объекту файловой системы  возвращает  набор прав доступа к нему. Данная функция может завершиться неуспешно в случаях: у пользователя нет доступа для получения прав доступа (isPermissionError); объект файловой системы не существует (isDoesNotExistError).

Определение:

getPermissions :: FilePath ->  IO  Permissions

Функция определена в виде примитива.

Функция: setPermissions

Описание: по заданному пути к объекту файловой системы устанавливает набор прав доступа к нему. Данная функция может завершиться неуспешно в случаях: у пользователя нет доступа для  установки прав доступа (isPermissionError); объект файловой системы не существует (isDoesNotExistError).

Определение:

setPermissions :: FilePath ->  Permissions  ->  IO ()

Функция определена в виде примитива.

Функция: getModificationTime

Описание: по заданному пути  к объекту файловой системы  возвращает дату и время последней  модификации этого объекта.  Данная функция  может завершиться неуспешно в случаях: у  пользователя  нет доступа для получения этой информации (isPermissionError); объект файловой системы не существует (isDoesNotExistError).

Определение:

getModificationTime :: FilePath ->  IO ClockTime

Функция определена в виде примитива.

11.3.1.    Модуль Internals

Служебный модуль Internals, в котором определяются функции для работы с путями, используемые в модуле Directory. Не должен использоваться напрямую, поскольку он сам всегда включён в модуль Directory из пакета System.

11.4.    Модуль Environment

В модуле Environment определены некоторые функции для работы программным окружением и с переменными, заданными в нём. Использование модуля:

import  System.Environment

В модуле определено шесть функций для чтения и работы с  содержимым окружения.

Функция: getArgs

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

Определение:

getArgs  ::  IO  [String]

Функция определена в виде примитива.

Функция: getProgName

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

Определение:

getProgName  :: IO String

Функция определена в виде примитива.

Функция: getEnv

Описание: возвращает значение заданной переменной окружения. Если переменной окружения не существует, генерируется исключение isDoesNotExistError. Определение:

getEnv  :: String ->  IO  String

Функция определена в виде примитива.

Функция: withArgs

Описание: выполняет монадическое  действие ввода/вывода (второй  аргумент), во время которого функция getArgs вернёт значение, заданное первым аргументом.

Определение:

withArgs :: [String] ->  IO a  ->  IO a

Функция определена в виде примитива.

Функция: withProgName

Описание: выполняет монадическое  действие ввода/вывода (второй  аргумент), во время которого функция getProgName вернёт значение, заданное первым аргументом.

Определение:

withProgName :: String ->  IO a  ->  IO a

Функция определена в виде примитива.

Функция: getEnvironment

Описание:  возвращает  весь  набор  переменных  окружения   в    виде    пар (имя, значение). Если переменная не содержит значения, то в соответствующей паре второй элемент является пустой строкой.

Определение:

getEnvironment :: IO [(String,  String)]

Функция определена в виде примитива.

11.4.     Модуль Exit

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

import  System.Exit

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

Тип: ExitCode

Описание: представляет значения кода выхода из программы. Первый конструктор представляет  успешное завершение программы, в то  время как второй — неуспешное. Второй конструктор параметризует целочисленное значение, которое используется операционной  системой для понимания причины, по которой программа была завершена с ошибкой (код ошибки).

Определение:

data  ExitCode

=  ExitSuccess

| ExitFailure Int

Данный тип имеет экземпляры  следующих классов: Eq, Ord, Read и Show.

Функция: exitWith

Описание: генерирует исключение ExitException с заданным  кодом  ошибки. Обычно это завершает программу. Перед тем как программа будет завершена, все открытые источники будут закрыты. Любая программа, которая завершается иным способом, трактуется как завершённая функцией exitFailure. Программа, которая завершена успешно, трактуется как завершённая при помощи команды exitWith ExitSuccess.

Определение:

exitWith ::  ExitCode  ->  IO a

exitWith ExitSuccess   = throwIO  (ExitException  ExitSuccess)

exitWith  code@(ExitFailure n)  | n /=  0 = throwIO  (ExitException  code)

Поскольку тип ExitException не является ошибкой  ввода/вывода IOError, он не может быть обработан функцией catch (см. стр. 506). Однако это исключение в любом случае является типом Exception,  поэтому может обрабатываться силами модуля Exception  (см. раздел 7.4.). Это значит, что произвольные завер-

шающие вычисления выполняются в этом случае также  при помощи  функции

bracket (см. стр. 209).

Функция: exitFailure

Описание: эквивалент функции exitWith, который возвращает код ошибки, зависящий от реализации библиотеки.

Определение:

exitFailure :: IO a

exitFailure = exitWith (ExitFailure  1)

11.6.     Модуль Info

Модуль, содержащий функции для получения информации об операционной системе, в которой была запущена программа. Использование модуля:

import System.Info

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

Функция: os

Описание: возвращает наименование операционной системы, в которой выполняется программа.

Определение:

os :: String

Функция определена в виде примитива.

Функция: arch

Описание: возвращает наименование машинной архитектуры, в которой выполняется программа.

Определение:

arch  :: String

Функция определена в виде примитива.

Функция: compilerName

Описание: возвращает наименование транслятора языка Haskell, при помощи которого была создана программа.

Определение:

compilerName :: String

Функция определена в виде примитива.

Функция: compilerVersion

Описание: возвращает версию транслятора языка Haskell, при помощи которого была создана программа. О типе Version  см. раздел 8.33..

Определение:

compilerVersion :: Version

Функция определена в виде примитива.

Источник: Душкин Р. В., Справочник по языку Haskell. М.: ДМК Пресс, 2008. 544 с., ил.

По теме:

  • Комментарии