serokell/haskell-with-utf8
1
1
Fork 0
mirror of https://github.com/serokell/haskell-with-utf8.git synced 2024-09-11 06:45:36 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse Source 
* Add links to the prospective blog post everywhere.
* Fix tiny issues.
* Add package description for Hackage.
This commit is contained in:
Kirill Elagin 2020-02-17 20:00:13 -05:00
parent c68db4da46
commit 7cab5d1b7c
2 changed files with 31 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
README.md
View File

@ -6,36 +6,40 @@ SPDX-License-Identifier: MPL-2.0
# utf8 _(haskell-utf8)_
Get your UTF-8 IO right on the first try.
Get your IO right on the first try.
Reading files in Haskell is trickier than it could be due to the non-obvious
interactions between file encodings and system locale. This library is meant
to make it easy once and for all by providing “defaults” that make more sense
in the modern world.
See [this blog post][blog:post] for more details on why this library need to
See [this blog post][blog:post] for more details on why this library needs to
exists and an explanation of some of the opinionated decisions it is based on.
<!-- TODO: Update link -->
[blog:post]: https://serokell.io/blog/...
[blog:post]: https://serokell.io/blog/haskell-utf8
## Use
See the documentation on Hackage for details, this is a quick summary.
### Step 1: Get it
The library is on [Hackage][hackage:utf8], just add it to the dependencies of
your project.
The [library is on Hackage][hackage:utf8],
go ahead and add it to the dependencies of your project.
[hackage:utf8]: https://hackage.haskell.org/package/utf8
### Step 2: Wrap your `main`
Import `withUtf8StdHandles` from `System.IO.Utf8` and wrap it around your `main`:
Import `withUtf8` from `Main.Utf8` and wrap it around your `main`:
```haskell
import Main.Utf8 (withUtf8)
main :: IO ()
main = withUtf8StdHandles $ {- ... your main function ... -}
main = withUtf8 $
{- ... your main function ... -}
```
This will make sure that if your program reads something from `stdin` or
@ -48,24 +52,24 @@ If you are going to read a text file (to be precise, if you are going to open
a file in text mode), you’ll probably use `withFile`, `openFile`, or `readFile`.
Grab the first two from `System.IO.Utf8` or the latter from `Data.Text.IO.Utf8`.
_Note: it is best to import these functions qualified._
_Note: it is best to import these modules qualified._
_Note: there is no `System.IO.Utf8.readFile` because it’s 2020 and
you should not read `String`s from files._
All these functions will make sure that the content will be treated as if it
was encoded in UTF-8 (it is 2020, what else can it be encoded in?).
was encoded in UTF-8.
If, for some reason, you really need to use `withFile`/`openFile` from `base`,
or you got your file handle from somewhere else, wrap the code that works
with it in a call to `hWithEncoding` from `System.IO.Utf8`:
with it in a call to `withHandle` from `System.IO.Utf8`:
```haskell
import qualified System.IO as IO
import qualified System.IO.Utf8 as Utf8
doSomethingWithAFile :: IO.Handle -> IO ()
doSomethingWithAFile h = Utf8.hWithEncoding h $ do
doSomethingWithAFile h = Utf8.withhandle h $ do
{- ... work with the file ... -}
```
@ -75,9 +79,9 @@ When writing a file either open it using `withFile`/`openFile` from
`System.IO.Utf8` or write to it directly with `writeFile` from
`Data.Text.IO.Utf8`.
_Note: it is best to import these functions qualified._
_Note: it is best to import these modules qualified._
_Note that there is no `System.IO.Utf8.writeFile`._
_Note: there is no `System.IO.Utf8.writeFile`._
If, for some reason, you really need to use `withFile`/`openFile` from `base`,
do the same as in the previous step.

14
package.yaml
View File

@ -4,7 +4,19 @@
name: utf8
version: 0.0.0
synopsis: Get your UTF-8 IO right on the first try
synopsis: Get your IO right on the first try
description: |
This minimalistic library helps you navigate the world of text encodings
avoiding @invalid argument (invalid byte sequence)@
and @invalid argument (invalid character)@ in runtime.
The two most important modules are:
* "Main.Utf8"
* "System.IO.Utf8"
See <https://serokell.io/blog/haskell-utf8 this blog post> for why this
library exists and what exactly it does.
author: Kirill Elagin <kirelagin@serokell.io>
copyright: 2020 Serokell