Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bergmark/through-text

Convert textual types to, from, and through(!) Text without needing O(n^2) instances
https://github.com/bergmark/through-text

Last synced: 25 days ago
JSON representation

Convert textual types to, from, and through(!) Text without needing O(n^2) instances

Awesome Lists containing this project

README 

        
[![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).