System.IO.Utils

MissingH-1.1.1.0: Large utility library

Portability | portable
Stability | provisional
Maintainer | John Goerzen <jgoerzen@complete.org>

System.IO.Utils

Contents

- Entire File Handle Utilities
  - Opened Handle Data Copying
  - Disk File Data Copying
- Line Processing Utilities
- Lazy Interaction
  - Character-based
  - Line-based
  - Misc. Lazy
- Optimizations

Description

Synopsis

- hCopy :: (HVIO a, HVIO b) => a -> b -> IO ()
- hCopyProgress :: (HVIO b, HVIO c, Integral a) => b -> c -> (Maybe a -> Integer -> Bool -> IO ()) -> Int -> Maybe a -> IO Integer
- hLineCopy :: (HVIO a, HVIO b) => a -> b -> IO ()
- lineCopy :: IO ()
- copyFileLinesToFile :: FilePath -> FilePath -> IO ()
- hPutStrLns :: HVIO a => a -> [String] -> IO ()
- hGetLines :: HVIO a => a -> IO [String]
- hInteract :: (HVIO a, HVIO b) => a -> b -> (String -> String) -> IO ()
- hLineInteract :: (HVIO a, HVIO b) => a -> b -> ([String] -> [String]) -> IO ()
- lineInteract :: ([String] -> [String]) -> IO ()
- lazyMapM :: (a -> IO b) -> [a] -> IO [b]
- optimizeForBatch :: IO ()
- optimizeForInteraction :: IO ()

# Entire File Handle Utilities

## Opened Handle Data Copying

hCopy :: (HVIO a, HVIO b) => a -> b -> IO ()

Copies from one handle to another in raw mode (using hGetContents).

hCopyProgress

Arguments

:: (HVIO b, HVIO c, Integral a) |
=> b | Input handle
-> c | Output handle
-> (Maybe a -> Integer -> Bool -> IO ()) | Progress function -- the bool is always False unless this is the final call
-> Int |
-> Maybe a |
-> IO Integer |

Copies from one handle to another in raw mode (using hGetContents). Takes a function to provide progress updates to the user.

hLineCopy :: (HVIO a, HVIO b) => a -> b -> IO ()

Copies from one handle to another in text mode (with lines). Like `hBlockCopy`, this implementation is nice:

     hLineCopy hin hout = hLineInteract hin hout id

lineCopy :: IO ()

Copies from `stdin` to `stdout` using lines. An alias for `hLineCopy` over `stdin` and `stdout`.

## Disk File Data Copying

copyFileLinesToFile :: FilePath -> FilePath -> IO ()

Copies one filename to another in text mode.

Please note that the Unix permission bits are set at a default; you may need to adjust them after the copy yourself.

This function is implemented using `hLineCopy` internally.

# Line Processing Utilities

hPutStrLns :: HVIO a => a -> [String] -> IO ()

Given a list of strings, output a line containing each item, adding newlines as appropriate. The list is not expected to have newlines already.

hGetLines :: HVIO a => a -> IO [String]

Given a handle, returns a list of all the lines in that handle. Thanks to lazy evaluation, this list does not have to be read all at once.

Combined with `hPutStrLns`, this can make a powerful way to develop filters. See the `lineInteract` function for more on that concept.

Example:

     main = do
            l <- hGetLines stdin
            hPutStrLns stdout $ filter (startswith "1") l

# Lazy Interaction

## Character-based

hInteract :: (HVIO a, HVIO b) => a -> b -> (String -> String) -> IO ()

This is similar to the built-in `interact`, but works on any handle, not just stdin and stdout.

In other words:

     interact = hInteract stdin stdout

## Line-based

hLineInteract :: (HVIO a, HVIO b) => a -> b -> ([String] -> [String]) -> IO ()

Line-based interaction over arbitrary handles. This is similar to wrapping hInteract with `lines` and `unlines`.

One could view this function like this:

     hLineInteract finput foutput func =
         let newf = unlines . func . lines in
             hInteract finput foutput newf

Though the actual implementation is this for efficiency:

     hLineInteract finput foutput func =
         do
         lines <- hGetLines finput
         hPutStrLns foutput (func lines)

lineInteract :: ([String] -> [String]) -> IO ()

Line-based interaction. This is similar to wrapping your interact functions with `lines` and `unlines`. This equality holds:

     lineInteract = hLineInteract stdin stdout

Here's an example:

     main = lineInteract (filter (startswith "1"))

This will act as a simple version of grep -- all lines that start with 1 will be displayed; all others will be ignored.

## Misc. Lazy

lazyMapM :: (a -> IO b) -> [a] -> IO [b]

Applies a given function to every item in a list, and returns the new list. Unlike the system's mapM, items are evaluated lazily.

# Optimizations

optimizeForBatch :: IO ()

Sets stdin and stdout to be block-buffered. This can save a huge amount of system resources since far fewer syscalls are made, and can make programs run much faster.

optimizeForInteraction :: IO ()

Sets stdin and stdout to be line-buffered. This saves resources on stdout, but not many on stdin, since it it still looking for newlines.