GHC.IO.Handle

тип данных Handle Исходный код

Haskell определяет операции для чтения и записи символов из файлов и в файлы, представленные значениями типа Handle. Каждое значение этого типа — это дескриптор: запись, используемая системой выполнения Haskell для управления Ввод/выводом с объектами файловой системы. Дескриптор имеет как минимум следующие свойства:

• управление вводом, выводом или обоими;
• открытый, закрытый или полузакрытый;
• является ли объект позиционируемым;
• буферизация отключена или включена на основе строк или блоков;
• буфер (длина которого может быть нулевой).

Большинство дескрипторов также будут иметь текущую позицию ввода/вывода, указывающую, где произойдет следующая операция ввода/вывода. Дескриптор является читаемым, если он управляет только вводом или и вводом, и выводом; аналогично, он является записываемым, если он управляет только выводом или и вводом, и выводом. Дескриптор открыт при первом выделении. После закрытия он больше не может использоваться ни для ввода, ни для вывода, хотя реализация не может повторно использовать его хранилище, пока к нему остаются ссылки. Дескрипторы находятся в классах Show и Eq. Строка, полученная при отображении дескриптора, зависит от системы; она должна содержать достаточно информации для идентификации дескриптора при отладке. Дескриптор равен согласно == только самому себе; не делается попыток сравнения внутреннего состояния разных дескрипторов на равенство.

тип данных BufferMode Исходный код

Поддерживаются три вида буферизации: буферизация по строкам, буферизация по блокам или отсутствие буферизации. Эти режимы имеют следующие эффекты. Для вывода элементы выводятся или сбрасываются из внутреннего буфера в соответствии с режимом буферизации:

• буферизация по строкам: весь буфер вывода сбрасывается всякий раз, когда выводится символ новой строки, буфер переполняется, выводится hFlush, или дескриптор закрывается.
• буферизация по блокам: весь буфер записывается всякий раз, когда он переполняется, выводится hFlush, или дескриптор закрывается.
• без буферизации: вывод записывается немедленно и никогда не хранится в буфере.

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

Аналогично, ввод происходит в соответствии с режимом буферизации для дескриптора:

• буферизация по строкам: если буфер дескриптора не пуст, следующий элемент берется из буфера; в противном случае, когда буфер пуст, символы до и включая следующий символ новой строки читаются в буфер. Символы недоступны, пока символ новой строки не будет доступен или буфер не будет заполнен.
• буферизация по блокам: если буфер дескриптора становится пустым, следующий блок данных считывается в буфер.
• без буферизации: следующий элемент ввода читается и возвращается. Операция hLookAhead подразумевает, что даже дескриптор без буферизации может потребовать буфер длиной в один символ.

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

mkFileHandle Исходный код

создает новый Handle

mkDuplexHandle :: (RawIO dev, IODevice dev, BufferedIO dev, Typeable dev) => dev -> FilePath -> Maybe TextEncoding -> NewlineMode -> IO Handle Source

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

hFileSize :: Handle -> IO Integer Source

Для дескриптора hdl, который прикреплён к физическому файлу, hFileSize hdl возвращает размер этого файла в байтах.

hSetFileSize :: Handle -> Integer -> IO () Source

hSetFileSize hdl size обрезает физический файл с дескриптором hdl до size байтов.

hIsEOF :: Handle -> IO Bool Source

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

ПРИМЕЧАНИЕ: hIsEOF может заблокироваться, потому что ему необходимо попытаться прочитать данные из потока, чтобы определить, есть ли еще данные для чтения.

isEOF :: IO Bool Source

Вычисление isEOF идентично hIsEOF, за исключением того, что оно работает только с stdin.

hLookAhead :: Handle -> IO Char Source

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

Эта операция может завершиться ошибкой:

• isEOFError если достигнут конец файла.

hSetBuffering :: Handle -> BufferMode -> IO () Source

Вычисление hSetBuffering hdl mode устанавливает режим буферизации для дескриптора hdl для последующих операций чтения и записи.

Если режим буферизации изменился с BlockBuffering или LineBuffering на NoBuffering, то

• если hdl доступен для записи, буфер очищается так же, как и для hFlush;
• если hdl недоступен для записи, содержимое буфера отбрасывается.

Эта операция может завершиться ошибкой:

• isPermissionError если дескриптор уже использовался для чтения или записи, и реализация не позволяет изменить режим буферизации.

hSetBinaryMode :: Handle -> Bool -> IO () Source

Выбор двоичного режима (True) или текстового режима (False) для открытого дескриптора. (См. также openBinaryFile.)

Это эквивалентно вызову hSetEncoding с char8, вместе с hSetNewlineMode с noNewlineTranslation.

hSetEncoding :: Handle -> TextEncoding -> IO () Source

Действие hSetEncoding hdl encoding меняет кодировку текста для дескриптора hdl на encoding. По умолчанию при создании Handle используется кодировка localeEncoding, а именно, кодировка по умолчанию для текущего локали.

Чтобы создать Handle без кодировки, используйте openBinaryFile. Чтобы остановить дальнейшую кодировку или декодирование на существующем Handle, используйте hSetBinaryMode.

hSetEncoding может потребоваться очистить данные в буфере, чтобы изменить кодировку.

hGetEncoding :: Handle -> IO (Maybe TextEncoding) Source

Возвращает текущую TextEncoding для указанного Handle, или Nothing если Handle находится в двоичном режиме.

Обратите внимание, что TextEncoding не запоминает ничего о состоянии используемого кодера/декодера в данном Handle. Например, если используемая кодировка UTF-16, то использование hGetEncoding и hSetEncoding для сохранения и восстановления кодировки может привести к записи дополнительного байтового порядка в файл.

hFlush :: Handle -> IO () Source

Действие hFlush hdl заставляет все элементы, буферизованные для вывода в дескрипторе hdl, немедленно отправляться в операционную систему.

Эта операция может завершиться ошибкой:

• isFullError если устройство заполнено;
• isPermissionError если будет превышен лимит системных ресурсов. В этих случаях не определено, отбрасываются или сохраняются ли символы в буфере.

hFlushAll :: Handle -> IO () Source

Действие hFlushAll hdl очищает все данные в буфере hdl, включая данные, буферизованные для чтения. Буферизованные данные чтения очищаются путем возврата позиции файла к позиции до чтения буферизованных данных, поэтому работает только если hdl допускает перемещение по файлу (см. hIsSeekable).

Эта операция может завершиться ошибкой:

• isFullError если устройство заполнено;
• isPermissionError если будет превышен лимит системных ресурсов. Не определено, отбрасываются или сохраняются ли символы в буфере в этих случаях;
• isIllegalOperation если hdl имеет буферизованные данные чтения, и не допускает перемещение по файлу.

hDuplicate :: Handle -> IO Handle Source

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

hDuplicateTo :: Handle -> Handle -> IO () Source

Делает второй дескриптор дубликатом первого дескриптора. Второй дескриптор будет закрыт сначала, если он ещё не закрыт.

Это можно использовать для перенаправления стандартных дескрипторов, например:

do h <- openFile "mystdout" WriteMode
   hDuplicateTo h stdout

hClose :: Handle -> IO () Source

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

hClose является прерываемой операцией в смысле, описанном в Control.Exception. Если hClose прерывается асинхронным исключением в процессе сброса буферов, то устройство ввода-вывода (например, файл) будет закрыто в любом случае.

hClose_help :: Handle__ -> IO (Handle__, Maybe SomeException) Source

data LockMode Source

Указывает режим, в котором должен быть заблокирован файл.

hLock :: Handle -> LockMode -> IO () Source

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

Важные моменты:

1) Эта функция может заблокироваться внутри вызова C. Если это произойдёт, для того чтобы иметь возможность прервать её с помощью асинхронных исключений и/или чтобы другие потоки могли продолжить работу, НУЖНО использовать многопоточную версию системы выполнения.

2) Реализация использует LockFileEx в Windows и flock в противном случае, поэтому все их замечания также применимы здесь.

3) На платформах, не являющихся Windows, не поддерживающих flock (например, Solaris), эта функция выбрасывает FileLockingNotImplemented. Мы намеренно не предоставляем блокировку на основе fcntl из-за её некорректных семантик.

Since: base-4.10.0.0

hTryLock :: Handle -> LockMode -> IO Bool Source

Неблокирующая версия hLock.

Возвращает True если захват блокировки был успешным и False в противном случае.

Since: base-4.10.0.0

type HandlePosition = Integer Source

data HandlePosn Source

hGetPosn :: Handle -> IO HandlePosn Source

Вычисление hGetPosn hdl возвращает текущую позицию ввода-вывода hdl в виде значения абстрактного типа HandlePosn.

hSetPosn :: HandlePosn -> IO () Source

Если вызов hGetPosn hdl возвращает позицию p, то вычисление hSetPosn p устанавливает позицию hdl на позицию, которая была у неё во время вызова hGetPosn.

Эта операция может завершиться ошибкой:

• isPermissionError если будет превышен лимит системного ресурса.

data SeekMode Source

Режим, определяющий эффект hSeek hdl mode i.

hSeek :: Handle -> SeekMode -> Integer -> IO () Source

Вычисление hSeek hdl mode i устанавливает положение дескриптора hdl в зависимости от mode. Смещение i указано в байтах.

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

Эта операция может завершиться ошибкой:

• isIllegalOperationError если дескриптор не может быть перемещён или не поддерживает указанный режим перемещения.
• isPermissionError если будет превышен системный лимит ресурсов.

hTell :: Handle -> IO Integer Source

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

Эта операция может завершиться ошибкой:

• isIllegalOperationError если дескриптор не может быть перемещён.

hIsOpen :: Handle -> IO Bool Source

hIsOpen hdl возвращает, открыт ли дескриптор. Если haType hdl ClosedHandle или SemiClosedHandle, это возвращает False, в противном случае True.

hIsClosed :: Handle -> IO Bool Source

hIsOpen hdl возвращает, закрыт ли дескриптор. Если haType hdl ClosedHandle, это возвращает True, в противном случае False.

hIsReadable :: Handle -> IO Bool Source

hIsReadable hdl возвращает, можно ли читать из дескриптора.

hIsWritable :: Handle -> IO Bool Source

hIsWritable hdl возвращает, можно ли писать в дескриптор.

hGetBuffering :: Handle -> IO BufferMode Source

Вычисление hGetBuffering hdl возвращает текущий режим буферизации для hdl.

hIsSeekable :: Handle -> IO Bool Source

hIsSeekable hdl возвращает, можно ли hSeek с заданным дескриптором.

hSetEcho :: Handle -> Bool -> IO () Source

Установить состояние эха для дескриптора, подключённого к терминалу.

hGetEcho :: Handle -> IO Bool Source

Получить состояние эха для подключения к терминалу.

hIsTerminalDevice :: Handle -> IO Bool Source

Подключено ли подключение к терминалу?

В Windows результат hIsTerminalDevide может быть вводящим в заблуждение, так как нестандартные терминалы, такие как MinTTY, используемые в средах MSYS и Cygwin, реализованы с помощью перенаправления. Используйте System.Win32.Types.withHandleToHANDLE System.Win32.MinTTY.isMinTTYHandle для его распознавания. Также рассмотрите пакет ansi-terminal для кроссплатформенной поддержки терминалов.

hSetNewlineMode :: Handle -> NewlineMode -> IO () Source

Установить режим NewlineMode для указанного Handle. Все буферизованные данные сначала сбрасываются.

data Newline Source

Представление новой строки во внешнем файле или потоке.

'\n'

'\r\n'

тип NewlineMode Исходный код

Указывает перевод, если таковой имеется, символов новой строки между внутренними строками и внешним файлом или потоком. Предполагается, что Haskell-строки представляют новые строки символом '\n'; режим новой строки указывает, как переводить '\n' при выводе и что переводить в '\n' при вводе.

nativeNewline :: Newline Исходный код

Представление новой строки для текущей платформы: LF на системах Unix, CRLF на Windows.

noNewlineTranslation :: NewlineMode Исходный код

Отсутствует перевод новой строки.

noNewlineTranslation  = NewlineMode { inputNL  = LF, outputNL = LF }

universalNewlineMode :: NewlineMode Исходный код

Преобразует '\r\n' в '\n' при вводе и '\n' в символ новой строки текущей платформы при выводе. Этот режим можно использовать на любой платформе и с текстовыми файлами, использующими любой способ обозначения новой строки. Недостаток заключается в том, что readFile >>= writeFile может привести к изменению файла.

universalNewlineMode  = NewlineMode { inputNL  = CRLF,
                                      outputNL = nativeNewline }

nativeNewlineMode :: NewlineMode Исходный код

Используйте символ новой строки текущей платформы как при вводе, так и при выводе.

nativeNewlineMode  = NewlineMode { inputNL  = nativeNewline
                                   outputNL = nativeNewline }

hShow :: Handle -> IO String Source

hShow находится в IO монаде и предоставляет более подробный вывод, чем (чистый) экземпляр Show для Handle.

hWaitForInput :: Handle -> Int -> IO Bool Source

Вычисление hWaitForInput hdl t ожидает, пока на обработчике hdl станет доступен ввод. Оно возвращает True как только ввод станет доступным на hdl, или False, если ввод не будет доступен в течение t миллисекунд. Обратите внимание, что hWaitForInput ожидает, пока будет доступен один или несколько полных символов, что означает необходимость декодирования, а значит, может завершиться ошибкой декодирования.

Если t меньше нуля, то hWaitForInput ожидает неопределенно долго.

Эта операция может завершиться ошибкой:

• isEOFError если достигнут конец файла.
• ошибкой декодирования, если ввод начинается с недопустимой последовательности байтов в кодировке этого обработчика.

ПРИМЕЧАНИЕ для пользователей GHC: если вы не используете флаг -threaded, hWaitForInput hdl t где t >= 0 заблокирует все остальные потоки Haskell на время вызова. В этом отношении он ведет себя как safe вызов внешней функции.

hGetChar :: Handle -> IO Char Source

Вычисление hGetChar hdl считывает символ из файла или канала, управляемого hdl, блокируя до тех пор, пока символ не станет доступным.

Эта операция может завершиться ошибкой:

• isEOFError если достигнут конец файла.

hGetLine :: Handle -> IO String Source

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

Строка отделяется символом новой строки, установленным с помощью hSetNewlineMode или nativeNewline по умолчанию. Символ(ы) новой строки, прочитанные из файла, не возвращаются как часть результата.

Если hGetLine сталкивается с концом файла в любой момент во время чтения строки, он рассматривается как разделитель строк, и возвращается (частичная) строка.

Эта операция может завершиться ошибкой:

• isEOFError если при чтении первого символа строки встречается конец файла.

Примеры

>>> withFile "/home/user/foo" ReadMode hGetLine >>= putStrLn
this is the first line of the file :O

>>> withFile "/home/user/bar" ReadMode (replicateM 3 . hGetLine)
["this is the first line","this is the second line","this is the third line"]

hGetContents :: Handle -> IO String Source

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

Любая операция, которая завершается ошибкой из-за закрытого обработчика, также завершается ошибкой, если обработчик полузакрыт. Исключение составляет hClose. Полузакрытый обработчик становится закрытым:

• если к нему применяется hClose;
• если возникает ошибка ввода-вывода при чтении элемента из обработчика;
• или после того, как весь контент обработчика был прочитан.

После того, как полузакрытый обработчик становится закрытым, содержимое связанного списка становится фиксированным. Содержимое этого конечного списка частично определяется: он будет содержать по меньшей мере все элементы потока, которые были обработаны до того, как обработчик стал закрытым.

Любые ошибки ввода-вывода, возникшие при работе с полузакрытым обработчиком, просто игнорируются.

Эта операция может завершиться ошибкой:

• isEOFError если достигнут конец файла.

hGetContents' :: Handle -> IO String Source

Операция hGetContents' считывает весь ввод на данном обработчике перед возвратом его как String и закрытием обработчика.

Это строгая версия hGetContents

Since: base-4.15.0.0

hPutChar :: Handle -> Char -> IO () Source

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

Эта операция может завершиться ошибкой:

• isFullError если устройство заполнено.
• isPermissionError если будет превышен другой системный лимит ресурсов.

hPutStr :: Handle -> String -> IO () Source

Вычисление hPutStr hdl s записывает строку s в файл или канал, управляемый hdl.

Обратите внимание, что hPutStr не является безопасной для одновременного доступа, если BufferMode hdl не установлен в LineBuffering или BlockBuffering:

>>> let f = forkIO . hPutStr stdout
>>> in do hSetBuffering stdout NoBuffering; f "This is a longer string"; f ":D"; f "Hello Haskell"; pure ()
This: HDiesl lao  lHoansgkeerl lstring

>>> let f = forkIO . hPutStr stdout
>>> in do hSetBuffering stdout LineBuffering; f "This is a longer string"; f ":D"; f "Hello Haskell"; pure ()
This is a longer string:DHello Haskell

Эта операция может завершиться ошибкой:

• isFullError если устройство заполнено.
• isPermissionError если будет превышен другой системный лимит ресурсов.

hGetBuf :: Handle -> Ptr a -> Int -> IO Int Source

hGetBuf hdl buf count считывает данные из обработчика hdl в буфер buf до тех пор, пока не будет достигнут конец файла или не будет прочитано count 8-битных байтов. Возвращает количество фактически прочитанных байтов. Может быть ноль, если конец файла был достигнут до прочтения каких-либо данных (или если count равно нулю).

hGetBuf никогда не генерирует исключение EOF, вместо этого возвращает значение меньше count.

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

hGetBuf игнорирует текущий TextEncoding и NewlineMode на Handle, и читает байты напрямую.

hGetBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int Source

hGetBufNonBlocking hdl buf count считывает данные из обработчика hdl в буфер buf до тех пор, пока не будет достигнут конец файла, или не будет прочитано count 8-битных байтов, или больше данных не будет доступно для немедленного чтения.

hGetBufNonBlocking идентично hGetBuf, за исключением того, что оно никогда не будет блокироваться в ожидании появления данных, а вместо этого возвращает только имеющиеся данные. Чтобы подождать появления данных перед вызовом hGetBufNonBlocking, используйте hWaitForInput.

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

hGetBufNonBlocking игнорирует текущий TextEncoding и NewlineMode на Handle, и читает байты напрямую.

ПРИМЕЧАНИЕ: в Windows эта функция работает неправильно; она ведет себя идентично hGetBuf.

hPutBuf :: Handle -> Ptr a -> Int -> IO () Source

hPutBuf hdl buf count записывает count 8-битные байты из буфера buf в обработчик hdl. Возвращает ().

hPutBuf игнорирует любые кодировки текста, которые применяются к Handle, записывая байты напрямую в базовый файл или устройство.

hPutBuf игнорирует текущие TextEncoding и NewlineMode в Handle, и записывает байты напрямую.

Эта операция может завершиться ошибкой:

• ResourceVanished если обработчик является каналом или сокетом, а конечный элемент чтения закрыт. (Если это система POSIX, и программа не запросила игнорирование SIGPIPE, то вместо этого может быть передано SIGPIPE, стандартное действие которого – завершение программы).

hPutBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int Source