Let's use ghci to check on the type of openFile:

ghci> :m System.IO
ghci> :t openFile
openFile :: FilePath -> IOMode -> IO Handle
ghci> :m System.IO
ghci> :t openFile
openFile :: FilePath -> IOMode -> IO Handle

FilePath is simply another name for String. It is used in the types of I/O functions to help clarify that the parameter is being used as a filename, and not as regular data.

IOMode specifies how the file is to be managed. The possible values for IOMode are listed in Table 7.1, “Possible IOMode Values”.

FIXME: check formatting on this table for final book; openjade doesn't render it well

While we are mostly working with text examples in this chapter, binary files can also be used in Haskell. If you are working with a binary file, you should use openBinaryFile instead of openFile. Operating systems such as Windows process files differently if they are opened as binary instead of as text. On operating systems such as Linux, both openFile and openBinaryFile perform the same operation. Nevertheless, for portability, it is still wise to always use openBinaryFile if you will be dealing with binary data.

You've already seen that hClose is used to close file handles. Let's take a moment and think about why this is important.

As you'll see in the section called “Buffering”, Haskell maintains internal buffers for files. This provides an important performance boost. However, it means that if you fail to hClose a file that is open for writing, your data may not all be flushed out to disk until you call hClose.

Another reason to make sure to hClose files is that open files take up memory on the system. If your program runs for a long time, and opens many files but fails to close them, it is conceivable that your program could even crash due to resource exhaustion.

When a program exits, Haskell will normally take care of closing any files that remain open. However, there are some circumstances in which this may not happen^[4], so once again, it is best to be responsible and call hClose all the time.

When reading and writing from a file, the operating system maintains an internal idea of the current position. Each time you do another read, the operating system returns the next chunk of data that begins at the current position, and increments the position to reflect the data that you read.

You can use hTell to find out your current position in the file. When the file is initially created, it is empty and your position will be 0. After you write out 5 bytes, your position will be 5, and so on. hTell takes a Handle and returns an IO Integer with your position.

The companion to hTell is hSeek. hSeek lets you reposition the file position. It takes three parameters: a Handle, a SeekMode, and a position.

SeekMode can be one of three different values, which specify how the given position is to be interpreted. AbsoluteSeek means that the position is a precise location in the file. This is the same kind of information that hTell gives you. RelativeSeek means to seek from the current position. A positive number requests going forwards in the file, and a negative number means going backwards. FIXME: do we need an example? Finally, SeekFromEnd will seek to the specified number of bytes before the end of the file. hSeek handle SeekFromEnd 0 will take you to the end of the file.

FIXME: do we need an example?

Not all Handles are seekable. A Handle usually corresponds to a file, but it can also correspond to other things such as network connections, tape drives, or terminals. You can use hIsSeekable to see if a given Handle is seekable.

Earlier, I pointed out that for each non-"h" function, there is usually also a corresponding "h" function that works on any Handle. The non-"h" functions nothing more than shortcuts, in fact.

There are three pre-defined Handles in System.IO. These Handles are always available for your use.

They are stdin, which corresponds to standard input; stdout for standard output; and stderr for standard error. Standard input normally refers to the keyboard, standard output to the monitor, and standard error also normally goes to the monitor.

Functions such as getLine can thus be trivially defined like this:

getLine = hGetLine stdin
putStrLn = hPutStrLn stdout
print = hPrint stdout

getLine = hGetLine stdin
putStrLn = hPutStrLn stdout
print = hPrint stdout

Earlier, I told you what the three standard file handles "normally" correspond to. That's because some operating systems let you redirect the file handles to come from (or go to) different places -- files, devices, or even other programs. This feature is used extensively in shell scripting on POSIX (Linux, BSD, Mac) operating systems, but can also be used on Windows.

It often makes sense to use standard input and output instead of specific files. This lets you interact with a human at the terminal. But it also lets you work with input and output files -- or even combine your code with other programs -- if that's what's requested.

As an example, we can provide input to callingpure.hs in advance like this:

$ echo John | runhaskell callingpure.hs
Greetings once again.  What is your name?
Pleased to meet you, John.
Your name contains 4 characters.
      
$ echo John | runhaskell callingpure.hs
Greetings once again.  What is your name?
Pleased to meet you, John.
Your name contains 4 characters.
      

FIXME: does this work on windows?

While callingpure.hs was running, it did not wait for input at the keyboard; instead it received John from the echo program. Notice also that the output didn't contain the word John on a separate line as it did when this program was run at the keyboard. The terminal normally echoes everything you type back to you, but that is technically input, and this not included in the output stream.

So far in this chapter, we've discussed the contents of the files. Let's now talk a bit about the files themselves.

System.Directory provides two functions you may find useful. removeFile takes a single argument, a filename, and deletes that file.^[5] renameFile takes two filenames: the first is the old name and the second is the new name. If the new filename is in a different directory, you can also think of this as a move. The old filename must exist prior to the call to renameFile. If the new file already exists, it is removed before the rename takes place.

There are many other functions in System.Directory for doing things such as creating and removing directories, finding lists of files in directories, and testing for file existance. These are discussed in FIXME: add ref to appropriate section of chapter 19.

Programmers frequently have a need for temporary files. These files may be used to store large amounts of data needed for computations, data to be used by other programs, or any number of other uses.

While you could craft a way to manually open files with unique names, the details of doing this in a secure way differ from platform to platform. Haskell provides a convenient function called openTempFile (and a corresponding openBinaryTempFile) to handle the difficult bits for you.

openTempFile takes two parameters: the directory in which to create the file, and a "template" for naming the file. The directory could simply be "." for the current working directory. Or you could use System.Directory.getTemporaryDirectory to find the best place for temporary files on a given machine. The template is used as the basis for the file name; it will have some random characters added to it to ensure that the result is truly unique.

The result of this function is IO (FilePath, Handle). The first part of the tuple is the name of the file created, and the second is a Handle opened in ReadWriteMode over that file. When you're done with the file, you'll want to hClose it and then call removeFile to delete it. See the following example for a sample function to use.

One novel way to approach I/O is the hGetContents function.^[7] hGetContents has the type Handle -> IO String. The String it returns represents the entire data in the file given by the Handle.^[8]

In an imperative language, use of such a function is often a bad idea. It may be fine to read the entire contents of a 2KB file, but if you try to read the entire contents of a 500GB file, you are likely to crash due to lack of RAM to store all that data.

But hGetContents is different. The String it returns is evaluated lazily. At the moment you call hGetContents, nothing is actually read. Data is only read from the Handle as the elements (characters) of the list are processed. As elements of the String are no longer used, Haskell automatically frees that memory. All of this happens completely transparently to you. And since you have what looks like -- and, really, is -- a pure String, you can pass it to pure (non-IO) code.

Let's take a quick look at an example. Back in the section called “Working With Files and Handles”, you saw an imperative program that converted the entire content of a file to uppercase. Its imperative algorithm was similar to what you'd see in many other languages. Here now is the much simpler lazy algorithm:

-- ch06/toupper-lazy1.hs

import System.IO
import Data.Char(toUpper)

main = do 
       inh <- openFile "input.txt" ReadMode
       outh <- openFile "output.txt" WriteMode
       inpStr <- hGetContents inh
       let result = processData inpStr
       hPutStr outh result
       hClose inh
       hClose outh

processData :: String -> String
processData = map toUpper-- ch06/toupper-lazy1.hs

import System.IO
import Data.Char(toUpper)

main = do 
       inh <- openFile "input.txt" ReadMode
       outh <- openFile "output.txt" WriteMode
       inpStr <- hGetContents inh
       let result = processData inpStr
       hPutStr outh result
       hClose inh
       hClose outh

processData :: String -> String
processData = map toUpper

Notice that hGetContents handled all of the reading for us. Also, take a look at processData. It's a pure function since it has no side-effects and always returns the same result each time it is called. It has no need to know -- and no way to tell -- that its input is being read lazily from a file in this case. It can work perfectly well with a 20-character literal or a 500GB data dump on disk.

You can even verify that with ghci:

ghci> :l toupper-lazy1.hs
[1 of 1] Compiling Main             ( toupper-lazy1.hs, interpreted )
Ok, modules loaded: Main.
ghci> processData "Hello, there!  How are you?"
"HELLO, THERE!  HOW ARE YOU?"
ghci> :t processData
processData :: String -> String
ghci> :t processData "Hello!"
processData "Hello!" :: String
ghci> :l toupper-lazy1.hs
[1 of 1] Compiling Main             ( toupper-lazy1.hs, interpreted )
Ok, modules loaded: Main.
ghci> processData "Hello, there!  How are you?"
"HELLO, THERE!  HOW ARE YOU?"
ghci> :t processData
processData :: String -> String
ghci> :t processData "Hello!"
processData "Hello!" :: String

This program was a bit verbose to make it clear that there was pure code in use. Here's a bit more concise version, which we will build on in the next examples:

-- ch06/toupper-lazy2.hs

import System.IO
import Data.Char(toUpper)

main = do 
       inh <- openFile "input.txt" ReadMode
       outh <- openFile "output.txt" WriteMode
       inpStr <- hGetContents inh
       hPutStr outh (map toUpper inpStr)
       hClose inh
       hClose outh-- ch06/toupper-lazy2.hs

import System.IO
import Data.Char(toUpper)

main = do 
       inh <- openFile "input.txt" ReadMode
       outh <- openFile "output.txt" WriteMode
       inpStr <- hGetContents inh
       hPutStr outh (map toUpper inpStr)
       hClose inh
       hClose outh

You are not required to ever consume all the data from the input file when using hGetContents. Whenever the Haskell system determines that the entire string hGetContents returned can be garbage collected -- which means it will never again be used -- the file is closed for you automatically. The same principle applies to data read from the file. Whenever a given piece of data will never again be needed, the Haskell environment releases the memory it was stored within.

Haskell programmers use hGetContents as a filter quite often. They read from one file, do something to the data, and write the result out elsewhere. This is so common that there are some shortcuts for doing it. readFile and writeFile are shortcuts for working with files as strings. They handle all the details of opening files, closing files, reading data, and writing data. readFile uses hGetContents internally.

Can you guess the Haskell types of these functions? Let's check with ghci:

-- ch06/toupper-lazy3.hs

import Data.Char(toUpper)

main = do 
       inpStr <- readFile "input.txt"
       writeFile "output.txt" (map toUpper inpStr)-- ch06/toupper-lazy3.hs

import Data.Char(toUpper)

main = do 
       inpStr <- readFile "input.txt"
       writeFile "output.txt" (map toUpper inpStr)

Look at that -- the guts of the program takes up only two lines! readFile returned a lazy String, which we stored in inpStr. We then took that, processed it, and passed it to writeFile for writing.

By now, you should understand how lazy input works in Haskell. But what about laziness during output?

As you know, nothing in Haskell is evaluated before its value is needed. Since functions such as putStr write out the entire String passed to them, that entire String must be evaluated. So you are guaranteed that the argument to putStr will be evaluated in full.^[9]

But what does that mean for laziness of the input? In the examples above, will the call to putStr or writeFile force the entire input string to be loaded into memory at once, just to be written out?

The answer is no. putStr (and all the similar output functions) write out data as it becomes available. They also have no need for keeping around data already written, so as long as nothing else in the program needs it, the memory can be freed immediately.

You can verify this yourself by generating a large input.txt for toupper-lazy3.hs. It may take a bit to process, but you should see a constant -- and low -- memory usage while it is being processed.

You learned that readFile and writeFile address the common situation of reading from one file, making a conversion, and writing to a different file. There's a situation that's even more common than that: reading from standard input, making a conversion, and writing the result to standard output. For that situation, there is a function called interact. interact takes one argument: a function of type String -> String. That function is passed the result of getContents -- that is, standard input read lazily. The result of that function is sent to stnadard output.

We can convert our example program to operate on standard input and standard input by using interact. Here's one way to do that:

-- ch06/toupper-lazy4.hs

import Data.Char(toUpper)

main = interact (map toUpper)-- ch06/toupper-lazy4.hs

import Data.Char(toUpper)

main = interact (map toUpper)

Look at that -- one line of code to achieve our transformation! To achieve the same effect as with the previous examples, you could run this one like this:

$ runghc toupper-lazy4.hs < input.txt > output.txt
      
$ runghc toupper-lazy4.hs < input.txt > output.txt
      

Or, if you'd like to see the output printed to the screen, you could type:

$ runghc toupper-lazy4.hs < input.txt
      
$ runghc toupper-lazy4.hs < input.txt
      

If you want to see that Haskell output truly does write out chunks of data as soon as they are received, run runghc toupper-lazy4.hs without any other command-line parameters. You should see each character echoed back out as soon as you type it, but in uppercase. Buffering may change this behavior; see the section called “Buffering” later in this chapter for more on buffering. If you see each line echoed as soon as you type it, or even nothing at all for awhile, buffering is causing this behavior.

You can also write simple interactive programs using interact. Let's start with a simple example: adding a line of text before the uppercase output.

-- ch06/toupper-lazy5.hs

import Data.Char(toUpper)

main = interact (map toUpper . (++) "Your data, in uppercase, is:\n\n")-- ch06/toupper-lazy5.hs

import Data.Char(toUpper)

main = interact (map toUpper . (++) "Your data, in uppercase, is:\n\n")

Here we add a string at the beginning of the output. Can you spot the problem, though?

Since we're calling map on the result of (++), that header itself will appear in uppercase. We can fix that in this way:

-- ch06/toupper-lazy6.hs

import Data.Char(toUpper)

main = interact ((++) "Your data, in uppercase, is:\n\n" . 
                 map toUpper)-- ch06/toupper-lazy6.hs

import Data.Char(toUpper)

main = interact ((++) "Your data, in uppercase, is:\n\n" . 
                 map toUpper)

This moved the header outside of the map.

-- ch06/filter.hs

main = interact (unlines . filter (elem 'a') . lines)-- ch06/filter.hs

main = interact (unlines . filter (elem 'a') . lines)

ghci> :t lines
lines :: String -> [String]
ghci> :t unlines
unlines :: [String] -> String
ghci> :t elem
elem :: (Eq a) => a -> [a] -> Bool
ghci> :t lines
lines :: String -> [String]
ghci> :t unlines
unlines :: [String] -> String
ghci> :t elem
elem :: (Eq a) => a -> [a] -> Bool

  $ runghc filter.hs < input.txt
  I like Haskell
  Haskell is great
        
  $ runghc filter.hs < input.txt
  I like Haskell
  Haskell is great
        

Most languages do not make a distinction between a pure function and an impure one. Haskell has functions in the mathematical sense: they are purely computations which cannot be impacted by anything external. Moreover, the computation can be performed at any time -- or even never, if its result is never needed.

Clearly, then, we need some other tool to work with I/O. That tool in Haskell is called actions. Actions resemble functions. They do nothing when they are defined, but perform some task when they are invoked. I/O actions are defined within the IO monad. Monads are actually a powerful way of chaining functions together purely and are covered in FIXME: insert ref. It's not necessary to understand monads in order to understand I/O. Just understand that the return value of actions is "tagged" with IO. Let's take a look at some types:

ghci> :t putStrLn
putStrLn :: String -> IO ()
ghci> :t getLine
getLine :: IO String
ghci> :t putStrLn
putStrLn :: String -> IO ()
ghci> :t getLine
getLine :: IO String

The type of putStrLn is just another function. The function takes one parameter and returns an IO (). This IO () is the action. You can store and pass actions in pure code, though this is rarely done. An action doesn't do anything until it is invoked. Let's look at an example of this:

-- ch06/actions.hs

str2action :: String -> IO ()
str2action input = putStrLn ("Data: " ++ input)

list2actions :: [String] -> [IO ()]
list2actions = map str2action

numbers :: [Int]
numbers = [1..10]

strings :: [String]
strings = map show numbers

actions :: [IO ()]
actions = list2actions strings

printitall :: IO ()
printitall = runall actions

-- Take a list of actions, and execute each of them in turn.
runall :: [IO ()] -> IO ()
runall [] = return ()
runall (firstelem:remainingelems) = 
    do firstelem
       runall remainingelems

main = do str2action "Start of the program"
          printitall
          str2action "Done!"-- ch06/actions.hs

str2action :: String -> IO ()
str2action input = putStrLn ("Data: " ++ input)

list2actions :: [String] -> [IO ()]
list2actions = map str2action

numbers :: [Int]
numbers = [1..10]

strings :: [String]
strings = map show numbers

actions :: [IO ()]
actions = list2actions strings

printitall :: IO ()
printitall = runall actions

-- Take a list of actions, and execute each of them in turn.
runall :: [IO ()] -> IO ()
runall [] = return ()
runall (firstelem:remainingelems) = 
    do firstelem
       runall remainingelems

main = do str2action "Start of the program"
          printitall
          str2action "Done!"

FIXME: make sure that partial application has been covered

str2action is a function that takes one parameter and returns an IO (). As you can see at the end of main, you could use this directly in another action and it will print out a line right away. But you can store -- but not execute -- the action from pure code. You can see an example of that in list2actions -- we use map over str2action and return a list of actions, just like we would with other pure data. You can see that everything up through printitall is built up with pure tools.

Although we define printitall, it doesn't get executed until its action is evaluated somewhere else. Notice in main how we use str2action as an I/O action to be executed, but earlier we used it outside of the I/O monad and assembled results into a list.

You could think of it this way: every statement, except let, in a do block must yeild an I/O action which will be executed.

The call to printitall; finally executes all those actions. Actually, since Haskell is lazy, the actions aren't generated until here either.

When you run the program, your output will look like this:

Data: Start of the program
Data: 1
Data: 2
Data: 3
Data: 4
Data: 5
Data: 6
Data: 7
Data: 8
Data: 9
Data: 10
Data: Done!
      
Data: Start of the program
Data: 1
Data: 2
Data: 3
Data: 4
Data: 5
Data: 6
Data: 7
Data: 8
Data: 9
Data: 10
Data: Done!
      

We can actually write this in a much more compact way. Consider this revision of the example:

-- ch06/actions2.hs

str2message :: String -> String
str2message input = "Data: " ++ input

str2action :: String -> IO ()
str2action = putStrLn . str2message

numbers :: [Int]
numbers = [1..10]

main = do str2action "Start of the program"
          mapM_ (str2action . show) numbers
          str2action "Done!"-- ch06/actions2.hs

str2message :: String -> String
str2message input = "Data: " ++ input

str2action :: String -> IO ()
str2action = putStrLn . str2message

numbers :: [Int]
numbers = [1..10]

main = do str2action "Start of the program"
          mapM_ (str2action . show) numbers
          str2action "Done!"

Notice in str2action the use of the standard function composition operator. In main, there's a call to mapM_. This function is similar to map. It takes a function and a list. The function supplied to mapM_ is an I/O action that is executed for every item in the list. mapM_ throws out the result of the function, though you can use mapM to return a list of I/O results if you want them. Take a look at their types:

ghci> :t mapM
mapM :: (Monad m) => (a -> m b) -> [a] -> m [b]
ghci> :t mapM_
mapM_ :: (Monad m) => (a -> m b) -> [a] -> m ()
ghci> :t mapM
mapM :: (Monad m) => (a -> m b) -> [a] -> m [b]
ghci> :t mapM_
mapM_ :: (Monad m) => (a -> m b) -> [a] -> m ()

These functions actually work for more than just I/O; they work for any Monad. For now, wherever you see "m", just think "IO".

Why a mapM when we already have map? Because map is a pure function that returns a list. It doesn't -- and can't -- actually execute anything directly. mapM is a utility that lives in the IO monad and thus can actually execute the actions.

Going back to main, mapM_ applies (straction . show) to every element in numbers. show converts each number to a String and str2action converts each String to an action. mapM_ then takes care of executing each action, which results in a line printed out.

We mentioned earlier that do blocks are a shortcut notation. This is true. There are two operators that you can use instead of do blocks: >> and >>=. Let's look at their types in ghci:

ghci> :t (>>)
(>>) :: (Monad m) => m a -> m b -> m b
ghci> :t (>>=)
(>>=) :: (Monad m) => m a -> (a -> m b) -> m b
ghci> :t (>>)
(>>) :: (Monad m) => m a -> m b -> m b
ghci> :t (>>=)
(>>=) :: (Monad m) => m a -> (a -> m b) -> m b

>> sequences two actions together: the first action is performed, then the second, and the result of the two will be the result of the second. The result of the first is thrown away. This is similar to simply having a new line in a do block.

>>= runs an action, passes its result to a function that returns an action. That action is run as well, and the result of the entire expression is the result of that second action.

Let's re-write one of our examples to avoid do blocks. Remember this example from the start of the chapter?

-- ch06/basicio.hs
main = do
       putStrLn "Greetings!  What is your name?"
       inpStr <- getLine
       putStrLn $ "Welcome to Haskell, " ++ inpStr ++ "!"-- ch06/basicio.hs
main = do
       putStrLn "Greetings!  What is your name?"
       inpStr <- getLine
       putStrLn $ "Welcome to Haskell, " ++ inpStr ++ "!"

Let's write that without a do block:

-- ch06/basicio-nodo.hs

main =
    putStrLn "Greetings!  What is your name?" >>
    getLine >>=
    (\inpStr -> putStrLn $ "Welcome to Haskell, " ++ inpStr ++ "!")-- ch06/basicio-nodo.hs

main =
    putStrLn "Greetings!  What is your name?" >>
    getLine >>=
    (\inpStr -> putStrLn $ "Welcome to Haskell, " ++ inpStr ++ "!")

The Haskell compiler is internally performing a translation just like this when you define a do block.

There are three different buffering modes in Haskell. They are defined as the BufferMode type.

NoBuffering does just what it sounds like -- no buffering. Data read via functions like hGetLine will be read from the OS one character at a time. Data written will be written immediately, and also often will be written one character at a time. For this reason, NoBuffering is usually a very poor performer and not suitable for general-purpose use.

LineBuffering causes the output buffer to be written whenever the newline character is output, or whenever it gets too large. On input, it will usually attempt to read whatever data is available in chunks until it first sees the newline character. When reading from the terminal, it should return data immediately after each press of Enter. It is often a reasonable default.

BlockBuffering causes Haskell to read or write data in fixed-size chunks when possible. This is the best performer whe processing large amounts of data in batch, even if that data is line-oriented. However, it is unusable for interactive programs because it will block input until a full block is read. BlockBuffering accepts one parameter: if Nothing, it will use an implementation-defined buffer size. Or, you can use a setting such as Just 4096 to set the buffer to 4096 bytes.

The default buffering mode is dependant upon the operating system and Haskell implementation. The current mode can be set with hSetBuffering, which accepts a Handle and BufferMode. You can ask the system for the current buffering mode by calling hGetBuffering. As an example, you can say hSetBuffering stdin (BlockBuffering Nothing).

For any type of buffering, you may sometimes want to force Haskell to write out any data is has saved up in the buffer. There are few times when this will happen automatically: a call to hClose, for instance. Sometimes you may want to instead call hFlush, which will force any pending data to be written immediately.