mirror of
https://github.com/serokell/haskell-with-utf8.git
synced 2024-09-11 06:45:36 +03:00
Update documentation
* Add links to the prospective blog post everywhere. * Fix tiny issues. * Add package description for Hackage.
This commit is contained in:
parent
c68db4da46
commit
7cab5d1b7c
32
README.md
32
README.md
@ -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
14
package.yaml
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user