planet-mitchell-0.1.0: Planet Mitchell

File.Text

Description

Textual file handling.

Synopsis

# File path operations

withFile :: MonadUnliftIO m => FilePath -> IOMode -> (Handle -> m a) -> m a #

Unlifted version of withFile.

Since: unliftio-0.1.0.0

Like openFile, but opens the file in ordinary blocking mode. This can be useful for opening a FIFO for writing: if we open in non-blocking mode then the open will fail if there are no readers, whereas a blocking open will block until a reader appear.

Since: base-4.4.0.0

The readFile function reads a file and returns the contents of the file as a string. The entire file is read strictly, as with getContents.

## Writing

writeFile :: FilePath -> Text -> IO () #

Write a string to a file. The file is truncated to zero length before writing begins.

appendFile :: FilePath -> Text -> IO () #

Write a string the end of a file.

# File handle operations

Read a character from the standard input device (same as hGetChar stdin).

Read a single line of user input from stdin.

Read all user input on stdin as a single string.

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.

Read a single line from a handle.

Experimental. Read a single chunk of strict text from a Handle. The size of the chunk depends on the amount of input currently buffered.

This function blocks only if there is no data available, and EOF has not yet been reached. Once EOF is reached, this function returns an empty string instead of throwing an exception.

Read the remaining contents of a Handle as a string. The Handle is closed once the contents have been read, or if an exception is thrown.

Internally, this function reads a chunk at a time from the lower-level buffering abstraction, and concatenates the chunks into a single string once the entire file has been read.

As a result, it requires approximately twice as much memory as its result to construct its result. For files more than a half of available RAM in size, this may result in memory exhaustion.

## Writing

say :: MonadIO m => Text -> m () #

Send a Text to standard output, appending a newline, and chunking the data. By default, the chunk size is 2048 characters, so any messages below that size will be sent as one contiguous unit. If larger messages are used, it is possible for interleaving with other threads to occur.

Since: say-0.1.0.0

sayString :: MonadIO m => String -> m () #

Same as say, but operates on a String. Note that this will force the entire String into memory at once, and will fail for infinite Strings.

Since: say-0.1.0.0

sayShow :: (MonadIO m, Show a) => a -> m () #

Same as say, but for instances of Show.

If your Show instance generates infinite output, this will fail. However, an infinite result for show would generally be considered an invalid instance anyway.

Since: say-0.1.0.0

sayErr :: MonadIO m => Text -> m () #

Same as say, but data is sent to standard error.

Since: say-0.1.0.0

sayErrString :: MonadIO m => String -> m () #

Same as sayString, but data is sent to standard error.

Since: say-0.1.0.0

sayErrShow :: (MonadIO m, Show a) => a -> m () #

Same as sayShow, but data is sent to standard error.

Since: say-0.1.0.0

hSay :: MonadIO m => Handle -> Text -> m () #

Same as say, but data is sent to the provided Handle.

Since: say-0.1.0.0

hSayString :: MonadIO m => Handle -> String -> m () #

Same as sayString, but data is sent to the provided Handle.

Since: say-0.1.0.0

hSayShow :: (MonadIO m, Show a) => Handle -> a -> m () #

Same as sayShow, but data is sent to the provided Handle.

Since: say-0.1.0.0

### Writing (no newlines)

putStr :: Text -> IO () #

Write a string to stdout.

hPutStr :: Handle -> Text -> IO () #

Write a string to a handle.

# File encoding

data TextEncoding #

A TextEncoding is a specification of a conversion scheme between sequences of bytes and sequences of Unicode characters.

For example, UTF-8 is an encoding of Unicode characters into a sequence of bytes. The TextEncoding for UTF-8 is utf8.

Instances
 Since: base-4.3.0.0 Instance detailsDefined in GHC.IO.Encoding.Types MethodsshowList :: [TextEncoding] -> ShowS #

The action hSetEncoding hdl encoding changes the text encoding for the handle hdl to encoding. The default encoding when a Handle is created is localeEncoding, namely the default encoding for the current locale.

To create a Handle with no encoding at all, use openBinaryFile. To stop further encoding or decoding on an existing Handle, use hSetBinaryMode.

hSetEncoding may need to flush buffered data in order to change the encoding.

Return the current TextEncoding for the specified Handle, or Nothing if the Handle is in binary mode.

Note that the TextEncoding remembers nothing about the state of the encoder/decoder in use on this Handle. For example, if the encoding in use is UTF-16, then using hGetEncoding and hSetEncoding to save and restore the encoding may result in an extra byte-order-mark being written to the file.

The Latin1 (ISO8859-1) encoding. This encoding maps bytes directly to the first 256 Unicode code points, and is thus not a complete Unicode encoding. An attempt to write a character greater than '\255' to a Handle using the latin1 encoding will result in an error.

The UTF-8 Unicode encoding

The UTF-8 Unicode encoding, with a byte-order-mark (BOM; the byte sequence 0xEF 0xBB 0xBF). This encoding behaves like utf8, except that on input, the BOM sequence is ignored at the beginning of the stream, and on output, the BOM sequence is prepended.

The byte-order-mark is strictly unnecessary in UTF-8, but is sometimes used to identify the encoding of a file.

The UTF-16 Unicode encoding (a byte-order-mark should be used to indicate endianness).

The UTF-16 Unicode encoding (litte-endian)

The UTF-16 Unicode encoding (big-endian)

The UTF-32 Unicode encoding (a byte-order-mark should be used to indicate endianness).

The UTF-32 Unicode encoding (litte-endian)

The UTF-32 Unicode encoding (big-endian)