@@ -1,2 +1,32 @@
11# generic-records
2−Magic record operations using generics
2+Magic record operations using generics (i.e. both type- and morally safe - no TH)
3+
4+This package uses the GHC8 Generic representation of records to derive magic classes (siilar to the OverloadedRecordLabels proposal), and prove structural subtyping relationship between records.
5+The latter can be used to upcast the "sub-record" to the more general "interface".
6+
7+This is made possible by GHC-8's new Generics API, which provides the meta-data
8+at the type-level (previously only value-level meta-data was available).
9+
10+An example can be found in the `examples` folder.
11+
12+## Magic getters
13+
14+```haskell
15+getName :: HasField r "name" a => r -> a
16+getName r = getField r (Proxy @"name")
17+```
18+defines a function that accepts any record that has a `name` field of type `a`,
19+then simply returns the field.
20+
21+## Structural subtyping
22+
23+```haskell
24+data R1 = R1 { a :: String, b :: Int }
25+data R2 = R2 { a :: String }
26+
27+upcast (R1 "hello" 5) :: R2
28+-- => R2 "hello"
29+```
30+
31+# TODO
32+[ ] port to `generics-sop` that now also supports type-level meta-data