GHC.IO.Handle.Text

base-4.20.0.0: Core data structures and operations

Copyright | (c) The University of Glasgow 1992-2008
License | see libraries/base/LICENSE
Maintainer | libraries@haskell.org
Stability | internal
Portability | non-portable
Safe Haskell | Safe
Language | Haskell2010

GHC.IO.Handle.Text

Description

String I/O functions

The API of this module is unstable and not meant to be consumed by the general public. If you absolutely must depend on it, make sure to use a tight upper bound, e.g., `base < 4.X` rather than `base < 5`, because the interface can change rapidly without much warning.

Synopsis

- hWaitForInput :: Handle -> Int -> IO Bool
- hGetChar :: Handle -> IO Char
- hGetLine :: Handle -> IO String
- hGetContents :: Handle -> IO String
- hPutChar :: Handle -> Char -> IO ()
- hPutStr :: Handle -> String -> IO ()
- commitBuffer' :: RawCharBuffer -> Int -> Int -> Bool -> Bool -> Handle__ -> IO CharBuffer
- hGetBuf :: Handle -> Ptr a -> Int -> IO Int
- hGetBufSome :: Handle -> Ptr a -> Int -> IO Int
- hGetBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int
- hPutBuf :: Handle -> Ptr a -> Int -> IO ()
- hPutBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int
- memcpy :: Ptr a -> Ptr a -> CSize -> IO (Ptr ())
- hPutStrLn :: Handle -> String -> IO ()
- hGetContents' :: Handle -> IO String

# Documentation

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

Computation `hWaitForInput` `hdl t` waits until input is available on handle `hdl`. It returns `True` as soon as input is available on `hdl`, or `False` if no input is available within `t` milliseconds. Note that `hWaitForInput` waits until one or more full characters are available, which means that it needs to do decoding, and hence may fail with a decoding error.

If `t` is less than zero, then `hWaitForInput` waits indefinitely.

This operation may fail with:

- `isEOFError` if the end of file has been reached.
- a decoding error, if the input begins with an invalid byte sequence in this Handle's encoding.

NOTE for GHC users: unless you use the `-threaded` flag, `hWaitForInput hdl t` where `t >= 0` will block all other Haskell threads for the duration of the call. It behaves like a `safe` foreign call in this respect.

hGetChar :: Handle -> IO Char Source #

Computation `hGetChar` `hdl` reads a character from the file or channel managed by `hdl`, blocking until a character is available.

This operation may fail with:

- `isEOFError` if the end of file has been reached.

hGetLine :: Handle -> IO String Source #

Computation `hGetLine` `hdl` reads a line from the file or channel managed by `hdl`. `hGetLine` does not return the newline as part of the result.

A line is separated by the newline set with `hSetNewlineMode` or `nativeNewline` by default. The read newline character(s) are not returned as part of the result.

If `hGetLine` encounters end-of-file at any point while reading in the middle of a line, it is treated as a line terminator and the (partial) line is returned.

This operation may fail with:

- `isEOFError` if the end of file is encountered when reading the first character of the line.

#### Examples

Expand

    >>> 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 #

Computation `hGetContents` `hdl` returns the list of characters corresponding to the unread portion of the channel or file managed by `hdl`, which is put into an intermediate state, semi-closed. In this state, `hdl` is effectively closed, but items are read from `hdl` on demand and accumulated in a special list returned by `hGetContents` `hdl`.

Any operation that fails because a handle is closed, also fails if a handle is semi-closed. The only exception is `hClose`. A semi-closed handle becomes closed:

- if `hClose` is applied to it;
- if an I/O error occurs when reading an item from the handle;
- or once the entire contents of the handle has been read.

Once a semi-closed handle becomes closed, the contents of the associated list becomes fixed. The contents of this final list is only partially specified: it will contain at least all the items of the stream that were evaluated prior to the handle becoming closed.

Any I/O errors encountered while a handle is semi-closed are simply discarded.

This operation may fail with:

- `isEOFError` if the end of file has been reached.

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

Computation `hPutChar` `hdl ch` writes the character `ch` to the file or channel managed by `hdl`. Characters may be buffered if buffering is enabled for `hdl`.

This operation may fail with:

- `isFullError` if the device is full; or
- `isPermissionError` if another system resource limit would be exceeded.

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

Computation `hPutStr` `hdl s` writes the string `s` to the file or channel managed by `hdl`.

This operation may fail with:

- `isFullError` if the device is full; or
- `isPermissionError` if another system resource limit would be exceeded.

commitBuffer' :: RawCharBuffer -> Int -> Int -> Bool -> Bool -> Handle__ -> IO CharBuffer Source #

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

`hGetBuf` `hdl buf count` reads data from the handle `hdl` into the buffer `buf` until either EOF is reached or `count` 8-bit bytes have been read. It returns the number of bytes actually read. This may be zero if EOF was reached before any data was read (or if `count` is zero).

`hGetBuf` never raises an EOF exception, instead it returns a value smaller than `count`.

If the handle is a pipe or socket, and the writing end is closed, `hGetBuf` will behave as if EOF was reached.

`hGetBuf` ignores the prevailing `TextEncoding` and `NewlineMode` on the `Handle`, and reads bytes directly.

hGetBufSome :: Handle -> Ptr a -> Int -> IO Int Source #

`hGetBufSome` `hdl buf count` reads data from the handle `hdl` into the buffer `buf`. If there is any data available to read, then `hGetBufSome` returns it immediately; it only blocks if there is no data to be read.

It returns the number of bytes actually read. This may be zero if EOF was reached before any data was read (or if `count` is zero).

`hGetBufSome` never raises an EOF exception, instead it returns a value smaller than `count`.

If the handle is a pipe or socket, and the writing end is closed, `hGetBufSome` will behave as if EOF was reached.

`hGetBufSome` ignores the prevailing `TextEncoding` and `NewlineMode` on the `Handle`, and reads bytes directly.

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

`hGetBufNonBlocking` `hdl buf count` reads data from the handle `hdl` into the buffer `buf` until either EOF is reached, or `count` 8-bit bytes have been read, or there is no more data available to read immediately.

`hGetBufNonBlocking` is identical to `hGetBuf`, except that it will never block waiting for data to become available, instead it returns only whatever data is available. To wait for data to arrive before calling `hGetBufNonBlocking`, use `hWaitForInput`.

If the handle is a pipe or socket, and the writing end is closed, `hGetBufNonBlocking` will behave as if EOF was reached.

`hGetBufNonBlocking` ignores the prevailing `TextEncoding` and `NewlineMode` on the `Handle`, and reads bytes directly.

NOTE: on Windows, this function does not work correctly; it behaves identically to `hGetBuf`.

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

`hPutBuf` `hdl buf count` writes `count` 8-bit bytes from the buffer `buf` to the handle `hdl`. It returns ().

`hPutBuf` ignores any text encoding that applies to the `Handle`, writing the bytes directly to the underlying file or device.

`hPutBuf` ignores the prevailing `TextEncoding` and `NewlineMode` on the `Handle`, and writes bytes directly.

This operation may fail with:

- `ResourceVanished` if the handle is a pipe or socket, and the reading end is closed. (If this is a POSIX system, and the program has not asked to ignore SIGPIPE, then a SIGPIPE may be delivered instead, whose default action is to terminate the program).

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

memcpy :: Ptr a -> Ptr a -> CSize -> IO (Ptr ()) Source #

hPutStrLn :: Handle -> String -> IO () Source #

The same as `hPutStr`, but adds a newline character.

hGetContents' :: Handle -> IO String Source #

The `hGetContents'` operation reads all input on the given handle before returning it as a `String` and closing the handle.

@since base-4.15.0.0