Skip to content

Commit d39cbda

Browse files
committed
ADR: Total conversion functions conventions
1 parent 6b2d51f commit d39cbda

File tree

1 file changed

+88
-0
lines changed

1 file changed

+88
-0
lines changed
Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Status
2+
3+
- [ ] Proposed 2024-05-21
4+
5+
# Context
6+
7+
## The Problem
8+
In `cardano-api` we have multiple functions performing conversions between one value of the type to the other, for example:
9+
10+
```haskell
11+
toShelleyScriptHash :: ScriptHash -> ScriptHash
12+
fromShelleyScriptHash :: ScriptHash -> ScriptHash
13+
```
14+
15+
There are multiple naming conventions for the conversion functions which makes them hard to locate.
16+
Some conversion functions with lengthy names, are not very convenient to use.
17+
18+
## Solution Proposal
19+
20+
### Type classes
21+
22+
For total functions, which are simply converting a value from one type to another, we can use type classes [`Inject` (from `cardano-ledger`)](https://cardano-ledger.cardano.intersectmbo.org/cardano-ledger-core/Cardano-Ledger-BaseTypes.html#t:Inject) & [`Convert`](https://cardano-api.cardano.intersectmbo.org/cardano-api/Cardano-Api-Internal-Eras.html#t:Convert):
23+
```haskell
24+
class Inject t s where
25+
inject :: t -> s
26+
27+
class Convert (f :: a -> Type) (g :: a -> Type) where
28+
convert :: forall a. f a -> g a
29+
```
30+
31+
The use of those conversion functions is limited to **internal use only**.
32+
The library should still export conversion functions with explicit type names for better readability.
33+
34+
>![NOTE]
35+
>The difference between `Inject` and `Convert` class is that `Convert` is better typed for rank 1 types.
36+
>In other words, when writing `instance Inject (Foo a) (Bar a)` the GHC's typechecker needs some help to understand the code using `inject`:
37+
>```haskell
38+
>let x = inject @_ @(Bar Bool) $ Foo True
39+
>```
40+
41+
#### Injection laws
42+
43+
The `Inject` and `Convert` classes are meant to be used for trivial conversions.
44+
The `inject` implementation should be injective
45+
```math
46+
\forall_{x,x' \in X}, \ \ f(x) = f(x') \implies x = x'
47+
```
48+
49+
### Explicit conversion functions
50+
51+
For explicit conversion functions, the following naming convention should follow:
52+
53+
```haskell
54+
fooToBar :: Foo -> Bar
55+
```
56+
57+
#### Qualified imports
58+
If the module exporting conversion functions is meant to be imported qualified, and provides functions for operating on a single data type, a shorter name with `from` prefix is allowed:
59+
60+
```haskell
61+
module Data.Foo where
62+
63+
fromBar :: Bar -> Foo
64+
```
65+
66+
where the usage would look like:
67+
```haskell
68+
import Data.Foo qualified as Foo
69+
70+
Foo.fromBar bar
71+
```
72+
73+
# Decision
74+
75+
TBD
76+
77+
# Consequences
78+
79+
## Advantages
80+
- An uniform API for total conversions
81+
- A list of `Inject` instances lists all available conversions for the type
82+
- Less maintenance burden with regards to the naming conventions of the conversion functions
83+
84+
## Disadvantages
85+
- It may be a bit surprising how to discover available conversions, because one would have to browse the type's `Inject` instances to find the conversion functions they are looking for - instead of looking for exported functions.
86+
87+
88+
[modeline]: # ( vim: set spell spelllang=en: )

0 commit comments

Comments
 (0)