This module provides the type File which represents an actual file. A file is a scarce resource, that is, in certain IOModes it can only be used by one user at a time. Because of the scarcity, a file needs to be opened to grant temporary sole access to the file. When the file is no longer needed it should be closed a.s.a.p to grant others access to the file.

The contributions of this module are as follows:

• First of all this module provides an instance for Resource for File which allows it to be used with the regions package. The regions package provides the region monad transformer RegionT. Scarce resources, like files for example, can be opened in a region. When the region terminates, all opened resources will be automatically closed. The main advantage of regions is that the handles to the opened resources can not be returned from the region which ensures no I/O with closed resources is possible. The primary technique used in regions is called "Lightweight monadic regions" which was invented by Oleg Kiselyov and Chung-chieh Shan. See: http://okmij.org/ftp/Haskell/regions.html#light-weight
• Secondly this module provides all the file operations of System.IO lifted to the region monad.
• The final contribution of this module is that file handles are parameterised with the IOMode in which the file was opened. This can be either R, W, A or RW. All operations on files explicitly specify the needed IOMode using the ReadModes and WriteModes type classes. This way it is impossible to read from a write-only handle or write to a read-only handle for example.

See the safer-file-handles-examples package for examples how to use this package:

darcs get http://code.haskell.org/~basvandijk/code/safer-file-handles-examples

Note that this package is early work and still very experimental. Take note of the following warnings:

• WARNING: You are able to lift an arbitrary IO action into a region. This action may throw an IOError which may contain a low-level handle to a file. This handle can be retrieved from the IOError using ioeGetHandle from System.IO.Error. So when an IOError is thrown you will be able to manually close the respected file! This will defeat the safety-guarantees that this package promises to provide. TODO: Think about how to solve this... The solution that Oleg provides in his paper is to filter out the low-level handle in an IOError when it's thrown. I can't easily do this because I have to modify the catch method of the MonadCatchIO instance for RegionT in the regions package. It feels like an ugly hack to solve this safer-file-handles specific problem in the independent general regions package.
• WARNING: Currenly the handling of the standard files (stdin, stdout and stderr) is not to my liking. See the documentation for details.
• NOTE: This module also provides functions from System.IO which don't directly work with file handles like putStrLn or getLine for example. These functions implicitly use the standard handles. I actually provide more general versions of these that work in any MonadIO. It could be argued that these functions don't belong in this module because they don't have anything to do with regions and explicit IOModes. However I provide them as a convenience. But be warned that in the future these lifted functions may move to their own package!

Note that this module re-exports the Control.Monad.Trans.Region module from the regions package which allows you to:

• open a File in a RegionT.
• Run a region using runRegionT.
• Concurrently run a region inside another region using forkTopRegion.
• Duplicate a regional file handle to a parent region using dup.

Convenience function for opening a file which yields a regional handle to it. This provides a safer replacement for System.IO.openFile.

Note that: openFile filePath ioMode = open $ File False filePath ioMode.

Note that the returned regional file handle is parameterized by the region in which it was created. This ensures that handles can never escape their region. And it also allows operations on handles to be executed in a child region of the region in which the handle was created.

Note that if you do wish to return a handle from the region in which it was created you have to duplicate the handle by applying dup to it.

Convenience function which opens a file, applies the given continuation function to the resulting regional file handle and runs the resulting region. This provides a safer safer replacement for System.IO.withFile.

Note that: withFile filePath ioMode = with $ File False filePath ioMode.

WARNING: I'm not satisfied with my current implementation of the standard handles (stdin, stdout and stderr)! Currently the standard handles are regional computations that return the regional file handles to the respected standard handles. There are 4 problems with this approach:

• When the region terminates in which you call one of the standard handles the respected handle will be closed. I think this is not the expected behaviour. I would expect the standard handles to always remain open.
• In System.IO the standard handles are pure values. My standard handles are monadic computations which makes them harder to work with.
• There is no way to explicitly close a standard handle. Indeed, the whole purpose of lightweight monadic regions is to automatically close handles. However, when writing a Unix daemon for example, you need to be able to explicitly close the standard handles.
• When reading 'man stdin' I'm confused if the standard handles are always open on program startup:

quote 'man stdin':

"...Under normal circumstances every Unix program has three streams opened for it when it starts up, one for input, one for output, and one for printing diagnostic or error messages..."

"...The stdin, stdout, and stderr macros conform to C89 and this standard also stipulates that these three streams shall be open at program startup...."

So now I'm confused... are these standard file handles always open on program startup or are there abnormal situations when they are closed?

Maybe I just have to believe the documentation in System.IO which specifies that they are always initially open.

If the standard handles are closed on startup using a handle returned from one of the standard handles will result in an exception! This would be a violation of my safety guarantees which is unacceptable.

Does anyone have a solution?

Convenience function for returning a regional handle to standard input. This provides a safer replacement for System.IO.stdin.

Note that: stdin = open $ Std In.

Convenience function for returning a regional handle to standard output. This provides a safer replacement for System.IO.stdout.

Note that: stdin = open $ Std Out.

Convenience function for returning a regional handle to standard error. This provides a safer replacement for System.IO.stderr.

Note that: stdin = open $ Std Err.

TODO:

The standard handles have concrete IOModes by default which work for the majority of cases. In the rare occasion that you know these handles have different IOModes you should be able to cast them to the expected IOMode.

The explicit-iomodes package defines this cast function. I should also define it here:

cast :: forall anyIOMode castedIOMode
     . (pr `ParentOf` cr, LiftIO cr, CheckMode castedIOMode)
     => RegionalFileHandle anyIOMode pr
     -> cr (Maybe (RegionalFileHandle castedIOMode pr))

However I'm not sure yet how to implement it...

A convenience function which opens a file in binary mode, applies the given continuation function to the resulting regional file handle and runs the resulting region. This provides a safer replacement for System.IO.withBinaryFile.

Note that: withBinaryFile filePath ioMode = with $ File True filePath ioMode.

Convenience function whichs opens a file in binary mode yielding a regional handle to it. This provides a safer replacement for System.IO.openBinaryFile.

Note that: openBinaryFile filePath ioMode = open $ File True filePath ioMode.

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.

Do no newline translation at all.

Map '\r\n' into '\n' on input, and '\n' to the native newline represetnation on output. This mode can be used on any platform, and works with text files using any newline convention. The downside is that readFile >>= writeFile might yield a different file.

Use the native newline representation on both input and output