Repository files navigation

Get your IO right on the first try.

Reading files in Haskell is trickier than it could be due to the non-obviousinteractions between file encodings and system locale. This library is meantto make it easy once and for all by providing “defaults” that make more sensein the modern world.

Seethis blog post for more details on why this library needs toexists and an explanation of some of the opinionated decisions it is based on.

See the documentation on Hackage for details, this is a quick summary.

Thelibrary is on Hackage,go ahead and add it to the dependencies of your project.

ImportwithUtf8 fromMain.Utf8 and wrap it around yourmain:

importMain.Utf8 (withUtf8)main::IO()main= withUtf8${- ... your main function ...-}

This will make sure that if your program reads something fromstdin oroutputs something tostdout/stderr, it will not fail with a runtimeerror due to encoding issues.

If you are going to read a text file (to be precise, if you are going to opena file in text mode), you’ll probably usewithFile,openFile, orreadFile.Grab the first two fromSystem.IO.Utf8 or the latter fromData.Text.IO.Utf8.Starting fromtext-2.1,Data.Text.IO.Utf8 is available in thetext packageitself, hence this module inwith-utf8 is now deprecated.

Note: it is best to import these modules qualified.

Note: there is noSystem.IO.Utf8.readFile because it’s 2024 andyou should not readStrings from files.

All these functions will make sure that the content will be treated as if itwas encoded in UTF-8.

If, for some reason, you really need to usewithFile/openFile frombase,or you got your file handle from somewhere else, wrap the code that workswith it in a call towithHandle fromSystem.IO.Utf8:

importqualifiedSystem.IOasIOimportqualifiedSystem.IO.Utf8asUtf8doSomethingWithAFile::IO.Handle->IO()doSomethingWithAFile h=Utf8.withhandle h$do{- ... work with the file ...-}

When writing a file either open it usingwithFile/openFile fromSystem.IO.Utf8 or write to it directly withwriteFile fromData.Text.IO.Utf8.Starting fromtext-2.1,Data.Text.IO.Utf8 is available in thetext packageitself, hence this module inwith-utf8 is now deprecated.

Note: it is best to import these modules qualified.

Note: there is noSystem.IO.Utf8.writeFile.

If, for some reason, you really need to usewithFile/openFile frombase,do the same as in the previous step.

Locales are pretty straightforward, but some people might have their terminalsmisconfigured for various reasons. To help troubleshoot any potential issues,this package comes with a tool calledutf8-troubleshoot.

This tool outputs some basic information about locale settings in the OS andwhat they end up being mapped to in Haskell. If you are looking for help,please, provide the output of this tool, or if you are helping someone,ask them to run this tool and provide the output.

If you encounter any issues when using this library or have improvement ideas,please open report in issue on GitHub. You are also very welcome to submitpull request, if you feel like doing so.

MPL-2.0 ©Serokell