cabal-version: 3.0
name: lawful-conversions
version: 0.1.6
synopsis: Lawful typeclasses for bidirectional conversion between types
category: Conversion
homepage: https://github.com/nikita-volkov/lawful-conversions
bug-reports: https://github.com/nikita-volkov/lawful-conversions/issues
author: Nikita Volkov <nikita.y.volkov@mail.ru>
maintainer: Nikita Volkov <nikita.y.volkov@mail.ru>
copyright: (c) 2022 Nikita Volkov
license: MIT
license-file: LICENSE
extra-source-files:
CHANGELOG.md
description:
= Summary
Lawful typeclasses capturing three patterns of bidirectional mapping and forming a layered hierarchy with an ascending strictness of laws.
1. Smart constructor
2. Canonicalization or lossy conversion
3. Isomorphism or lossless conversion
= The conversion problem
Have you ever looked for a @toString@ function? How often do you
import @Data.Text.Lazy@ only to call its @fromStrict@? How
about importing @Data.ByteString.Builder@ only to call its
@toLazyByteString@ and then importing
@Data.ByteString.Lazy@ only to call its @toStrict@?
Those all are instances of one pattern. They are conversions between different
representations of the same information. Codebases that don't attempt to
abstract over this pattern tend to be sprawling with this type of
boilerplate. It's noise to the codereader, it's a burden to the
implementor and the maintainer.
= Why another conversion library?
Many libraries exist that approach the conversion problem. However most of
them provide lawless typeclasses leaving it up to the author of the
instance to define what makes a proper conversion. This results in
inconsistencies across instances, their behaviour not being evident to
the user and no way to check whether an instance is correct.
This library tackles this problem with a lawful typeclass hierarchy, making it
evident what any of its instances do and it provides property-tests for you
to validate your instances.
= Prior work and acknowledgements
This library is a direct successor of the "[isomorphism-class](https://hackage.haskell.org/package/isomorphism-class)" library, expanding upon the patterns discovered there. It also shares some ideas with "[control-iso](https://hackage.haskell.org/package/control-iso)" and "[type-iso](https://hackage.haskell.org/package/type-iso)".
source-repository head
type: git
location: git://github.com/nikita-volkov/lawful-conversions.git
common base
default-language: Haskell2010
default-extensions:
BlockArguments
DefaultSignatures
FlexibleContexts
FlexibleInstances
MagicHash
MultiParamTypeClasses
NoImplicitPrelude
ScopedTypeVariables
TypeApplications
UndecidableSuperClasses
library
import: base
hs-source-dirs: src/library
exposed-modules: LawfulConversions
other-modules:
LawfulConversions.Classes
LawfulConversions.Classes.Is
LawfulConversions.Classes.IsMany
LawfulConversions.Classes.IsSome
LawfulConversions.Optics
LawfulConversions.Prelude
LawfulConversions.Properties
LawfulConversions.Proxies
LawfulConversions.Proxies.ViaIsSome
LawfulConversions.Relations
LawfulConversions.Relations.BoxedVectorAndList
LawfulConversions.Relations.BoxedVectorAndSeq
LawfulConversions.Relations.ByteArrayAndByteString
LawfulConversions.Relations.ByteArrayAndLazyByteString
LawfulConversions.Relations.ByteArrayAndLazyByteStringBuilder
LawfulConversions.Relations.ByteArrayAndShortByteString
LawfulConversions.Relations.ByteArrayAndTextArray
LawfulConversions.Relations.ByteArrayAndWord8List
LawfulConversions.Relations.ByteStringAndLazyByteString
LawfulConversions.Relations.ByteStringAndLazyByteStringBuilder
LawfulConversions.Relations.ByteStringAndLazyText
LawfulConversions.Relations.ByteStringAndShortByteString
LawfulConversions.Relations.ByteStringAndString
LawfulConversions.Relations.ByteStringAndText
LawfulConversions.Relations.ByteStringAndTextArray
LawfulConversions.Relations.ByteStringAndWord8List
LawfulConversions.Relations.DayAndLazyText
LawfulConversions.Relations.DayAndLazyTextBuilder
LawfulConversions.Relations.DayAndStrictTextBuilder
LawfulConversions.Relations.DayAndString
LawfulConversions.Relations.DayAndText
LawfulConversions.Relations.Int16AndWord16
LawfulConversions.Relations.Int32AndWord32
LawfulConversions.Relations.Int64AndWord64
LawfulConversions.Relations.Int8AndWord8
LawfulConversions.Relations.IntAndWord
LawfulConversions.Relations.IntMapAndMapOfInt
LawfulConversions.Relations.IntSetAndSetOfInt
LawfulConversions.Relations.LazyByteStringAndLazyByteStringBuilder
LawfulConversions.Relations.LazyByteStringAndLazyText
LawfulConversions.Relations.LazyByteStringAndShortByteString
LawfulConversions.Relations.LazyByteStringAndString
LawfulConversions.Relations.LazyByteStringAndText
LawfulConversions.Relations.LazyByteStringAndTextArray
LawfulConversions.Relations.LazyByteStringAndWord8List
LawfulConversions.Relations.LazyByteStringBuilderAndShortByteString
LawfulConversions.Relations.LazyByteStringBuilderAndTextArray
LawfulConversions.Relations.LazyByteStringBuilderAndWord8List
LawfulConversions.Relations.LazyTextAndLazyTextBuilder
LawfulConversions.Relations.LazyTextAndStrictTextBuilder
LawfulConversions.Relations.LazyTextAndString
LawfulConversions.Relations.LazyTextAndText
LawfulConversions.Relations.LazyTextAndUtcTime
LawfulConversions.Relations.LazyTextAndUuid
LawfulConversions.Relations.LazyTextBuilderAndStrictTextBuilder
LawfulConversions.Relations.LazyTextBuilderAndString
LawfulConversions.Relations.LazyTextBuilderAndText
LawfulConversions.Relations.LazyTextBuilderAndUtcTime
LawfulConversions.Relations.LazyTextBuilderAndUuid
LawfulConversions.Relations.ListAndSeq
LawfulConversions.Relations.ShortByteStringAndTextArray
LawfulConversions.Relations.ShortByteStringAndWord8List
LawfulConversions.Relations.StrictTextBuilderAndString
LawfulConversions.Relations.StrictTextBuilderAndText
LawfulConversions.Relations.StrictTextBuilderAndUtcTime
LawfulConversions.Relations.StrictTextBuilderAndUuid
LawfulConversions.Relations.StringAndText
LawfulConversions.Relations.StringAndUtcTime
LawfulConversions.Relations.StringAndUuid
LawfulConversions.Relations.TextAndUtcTime
LawfulConversions.Relations.TextAndUuid
LawfulConversions.Relations.TextArrayAndWord8List
LawfulConversions.TextCompat.Array
build-depends:
QuickCheck >=2.13 && <3,
base >=4.12 && <5,
bytestring >=0.10 && <0.13,
containers >=0.6 && <0.8,
hashable >=1 && <2,
primitive >=0.7 && <0.10,
profunctors >=5 && <6,
text >=1.2 && <2.2,
time >=1.9 && <2,
unordered-containers >=0.2 && <0.3,
uuid-types >=1.0 && <1.1,
vector >=0.12 && <0.14,
test-suite test
import: base
type: exitcode-stdio-1.0
hs-source-dirs: src/test
main-is: Main.hs
other-modules: Test.ExtraInstances
build-depends:
QuickCheck >=2.13 && <3,
bytestring >=0.11.1.0 && <0.13,
lawful-conversions,
primitive >=0.7 && <0.10,
quickcheck-instances >=0.3.32 && <0.4,
rebase >=1.15 && <2,
tasty >=1.2.3 && <2,
tasty-quickcheck >=0.11 && <0.12,
text >=1.2 && <3,