typed-encoding: Type safe string transformations

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

See README.md in the project github repository.

[Skip to Readme]

Properties

Versions	0.1.0.0, 0.2.0.0, 0.2.1.0, 0.2.2.0, 0.2.2.0, 0.3.0.0, 0.3.0.1, 0.3.0.2, 0.4.0.0, 0.4.1.0, 0.4.2.0, 0.5.0.0, 0.5.1.0, 0.5.2.0, 0.5.2.1, 0.5.2.2, 0.5.2.3
Change log	ChangeLog.md
Dependencies	base (>=4.10 && <5), base64-bytestring (>=1.0 && <1.1), bytestring (>=0.10 && <0.11), symbols (>=0.3 && <0.3.1), text (>=1.2 && <1.3) [details]
License	BSD-3-Clause
Copyright	2020 Robert Peszek
Author	Robert Peszek
Maintainer	robpeszek@gmail.com
Category	Data, Text
Home page	https://github.com/rpeszek/typed-encoding#readme
Bug tracker	https://github.com/rpeszek/typed-encoding/issues
Source repo	head: git clone https://github.com/rpeszek/typed-encoding
Uploaded	by rpeszek at 2020-05-16T02:25:24Z

Modules

[Index]

Downloads

typed-encoding-0.2.2.0.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

Package maintainers

rpeszek

For package maintainers and hackage trustees

edit package information

Readme for typed-encoding-0.2.2.0

[back to package description]

typed-encoding

Type level annotations, string transformations, and other goodies that make programming strings safer.

Motivation

I have recently spent a lot of time troubleshooting various Base64, quoted-printable, and UTF-8 encoding issues.
I decided to write a library that will help avoiding issues like these.

This library allows to specify and work with types like

-- some data encoded in base 64
mydata :: Enc '["enc-B64"] ByteString

-- some text (utf8) data encoded in base 64 
myData :: Enc '["enc-B64", "r-UTF8"] ByteString

It allows to define precise string content annotations like:

ipaddr :: Enc '["r-IpV4"] Text

and provides ways for

encoding
decoding
recreation (encoding validation)
type conversions
converting types to encoded strings
typesafe conversion of encoded strings to types

... but this approach seems to be a bit more...

-- upper cased text encoded as base64
example :: Enc '["enc-B64", "do-UPPER"] () T.Text
example = encodeAll . toEncoding () $ "some text goes here"

It becomes a type directed, declarative approach to string transformations.

Transformations can be

used with parameters
applied or undone partially (if encoding is reversible)

One of more interesting uses of this library are encoding restrictions.
(Arbitrary) bounded alpha-numeric (r-ban) restrictions and a simple annotation Boolean algebra are both provided.

phone :: Enc '["r-ban:999-999-9999"] () T.Text
phone = ...

-- simple boolean algebra:
phone' :: Enc '["boolOr:(r-ban:999-999-9999)(r-ban:(999) 999-9999)"] () T.Text
phone' = ...

Examples

Please see Examples.TypedEncoding it the module list.

Other encoding packages

My approach will be to write specific encodings (e.g. HTTP) or wrap encodings from other packages using separate "bridge" projects.

Currently typed-encoding depends on

base64-bytestring because it was my driving example, this is likely to move out to a separate bridge project at some point.

Bridge work:

typed-encoding-encoding bridges encoding package

Plans, some TODOs

lensifying conversions
better implementation type safety

Tested with

stack (1.9.3) lts-14.27 (ghc-8.6.5)
needs ghc >= 8.2.2, base >=4.10 for GHC.TypeLits support

Known issues

running test suite: cabal has problems with doctest, use stack
https://github.com/haskell/cabal/issues/6087