The through-text package

[Tags:bsd3, library]

Convert textual types through Text without needing O(n^2) instances.

See the README for more information: https://github.com/bergmark/through-text/blob/master/README.md


[Skip to Readme]

Properties

Versions 0.1.0.0
Change log CHANGELOG.md
Dependencies base (>=4.3 && <4.10), bytestring (>=0.9 && <0.11), case-insensitive (>=0.1 && <1.3), text (>=0.11 && <1.3) [details]
License BSD3
Copyright (c) 2015 Adam Bergmark
Author Adam Bergmark
Maintainer adam@bergmark.nl
Stability Unknown
Category Data
Home page https://www.github.com/bergmark/through-text
Bug tracker https://www.github.com/bergmark/through-text
Source repository head: git clone https://github.com/bergmark/through-text.git
Uploaded Thu May 7 17:42:48 UTC 2015 by AdamBergmark
Updated Tue May 24 10:25:25 UTC 2016 by AdamBergmark to revision 1
Distributions LTSHaskell:0.1.0.0, NixOS:0.1.0.0, Stackage:0.1.0.0, Tumbleweed:0.1.0.0
Downloads 192 total (10 in the last 30 days)
Votes
0 []
Status Docs available [build log]
Last success reported on 2015-05-07 [all 1 reports]

Modules

[Index]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees

Readme for through-text

Readme for through-text-0.1.0.0

through-text Build Status

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 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 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 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 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

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.