[![through-text](https://budueba.com/hackage/through-text)](https://hackage.haskell.org/package/through-text)
[![Build Status](https://travis-ci.org/bergmark/through-text.svg?branch=master)](https://travis-ci.org/bergmark/through-text)

This is a small package defining two typeclasses `ToText` and
`FromText`. It's meant to be used in normal cases where you have some
control over data, hence UTF-8 is assumed for all types.

Currently supported packages are `text`, `bytestring`, and
`case-insensitive`, and `String` from `base` of course!

You can define `FromText` instances that may fail as `FromText (Maybe a)`.

There are alse type aliases `StrictText`, `LazyByteString` et.c. so
you don't need to import them yourself, it also makes code easier to
read than if you import `Text` unqualified.

Conversions from bytestrings use
[lenientDecode](http://hackage.haskell.org/package/text-1.2.0.4/docs/Data-Text-Encoding-Error.html#v:lenientDecode)
which replaces invalid characters with U+FFFD.

There are identity instances for `StrictText`. They allow you to use
`throughText` instead of `toText` and `fromText` when working with
`StrictText` itself. It is not meant as an encouragement to use type
class constraints such as `ToText a => a -> IO ()` in function
signatures, I instead recommend using the actual type you want.

## Motivation

In practice I've found that most textual conversions I do are just to
glue packages together. I either know or am satisfied with assuming
that the encoding is UTF-8 and I don't really care about the types
involved.

We should be using `Text` as the default textual type instead of
`String`. [tostring](https://www.hackage.org/package/tostring)
together with `Data.String.IsString` otherwise accomplishes the same
goal. A current advantage of using `String` is that you do not need to
enable `OverloadedStrings` for literals.

Multi-parameter type classes easily leads to ambiguity and leads to
O(n^2) instances if you want to convert between every type.
[string-conversions](https://www.hackage.org/package/string-conversions)
implements this idea with the benefit that you have to pay even less
attention of what types you are converting.

In most use sites conversions are total, encoding this possibility in
the type class leads to partial functions or the need to handle
impossible failures.
[convertible](https://www.hackage.org/package/convertible) throws an
exception if a failure occurs.

I don't want conversions from types just because they have a textual
representation such as `ToText Int` - most types have one after
all. It's unclear whether you want a pretty printed or structually
focused result. `Show` already suffers this conflict.


## Will instances for great-package be added?

Only if it's a popular library with no more than a couple of (new)
dependencies.  If you ask I will either accept or guarantee to do a
major version bump should I change my mind
([so you don't need to depend on a minor version](https://wiki.haskell.org/Package_versioning_policy)

For that reason I added
`[case-insensitive](https://www.haskell.org/package/case-insensitive)`,
it's a very useful package with only a one-module dependency
(`hashable`).

## When to avoid this library

If you don't know the encoding you should explicitly use other
libraries e.g. [text-icu](https://www.hackage.org/package/text-icu).