Bookkeeper

Preamble

The examples here presume the following setup:

>>> import Data.Char (toUpper)
>>> type Person = Book '[ "name" :=> String , "age" :=> Int ]
>>> let julian :: Person = emptyBook & #age =: 28 & #name =: "Julian K. Arni"

The OverloadedLabels and TypeOperators extensions are also required.

A word of warning: The signatures for most of the functions are quite arcane, even though their behaviour is intuitive.

Initialization

emptyBook :: Book '[]

A book with no records. You'll usually want to use this to construct books.

Getters

type Gettable field book val = (Submap '[field :=> val] book, Contains book field val)

Gettable field val book is the constraint needed to get a value of type val from the field field in the book of type Book book.

(?:) :: forall field book val. Gettable field book val => Book' book -> Key field -> val infixl 3

Flipped and infix version of get.

>>> julian ?: #name
"Julian K. Arni"

get :: forall field book val. Gettable field book val => Key field -> Book' book -> val

Get a value by key, if it exists.

>>> get #age julian
28

If the key does not exist, throws a type error >>> get #moneyFrom julian ... ... • The provided Book does not contain the field "moneyFrom" ... Book type: ... '["age" ':-> Int, "name" ':-> String] ... • In the expression: get #moneyFrom julian ...

Setters

type Settable field val old new = (Submap (AsMap (old :\ field)) old, Unionable '[field :=> val] (AsMap (old :\ field)), new ~ AsMap ((field :=> val) ': AsMap (old :\ field)))

'Settable field val old new' is a constraint needed to set the the field field to a value of type val in the book of type 'Book old'. The resulting book will have type 'Book new'.

set :: forall field val old new. Settable field val old new => Key field -> val -> Book' old -> Book' new

Sets or updates a field to a value.

>>> set #likesDoctest True julian
Book {age = 28, likesDoctest = True, name = "Julian K. Arni"}

(=:) :: Settable field val old new => Key field -> val -> Book' old -> Book' new infix 3

Infix version of set

>>> julian & #age =: 29
Book {age = 29, name = "Julian K. Arni"}

Modifying

type Modifiable field val val' old new = (Settable field val' old new, AsMap new ~ new, Contains old field val, Submap '[field :=> val] old)

Modifiable field val val' old new is a constraint needed to apply a function of type val -> val' to the field field in the book of type Book old. The resulting book will have type Book new.

modify :: Modifiable field val val' old new => Key field -> (val -> val') -> Book' old -> Book new

Apply a function to a field.

>>> julian & modify #name (fmap toUpper)
Book {age = 28, name = "JULIAN K. ARNI"}

If the key does not exist, throws a type error >>> modify #height (_ -> 132) julian ... ... • The provided Book does not contain the field "height" ... Book type: ... '["age" ':-> Int, "name" ':-> String] ... • In the expression: modify #height ( _ -> 132) julian ...

(%:) :: Modifiable field val val' old new => Key field -> (val -> val') -> Book' old -> Book new infixr 3

Infix version of modify.

>>> julian & #name %: fmap toUpper
Book {age = 28, name = "JULIAN K. ARNI"}

Deleting

delete :: forall field old. Submap (AsMap (old :\ field)) old => Key field -> Book' old -> Book (old :\ field)

Delete a field from a Book, if it exists. If it does not, returns the Book unmodified.

>>> get #name $ delete #name julian
...
...  • The provided Book does not contain the field "name"
...    Book type:
...    '["age" ':-> Int]
...  • In the expression: get #name
...

Types

type Book a = Book' (AsMap a)

type (:=>) a b = a :-> b

An alias for :-> because otherwise you'll have to tick your constructors.

data Key (a :: Symbol)

Key is simply a proxy. You will usually not need to generate it directly, as it is generated by the OverlodadedLabels magic.

Instances

(~) Symbol s s' => IsLabel s (Key s')

Methods

fromLabel :: Key s'

Eq (Key a)

Methods

(==) :: Key a -> Key a -> Bool

(/=) :: Key a -> Key a -> Bool

Read (Key a)

Methods

readsPrec :: Int -> ReadS (Key a)

readList :: ReadS [Key a]

readPrec :: ReadPrec (Key a)

readListPrec :: ReadPrec [Key a]

Show (Key a)

Methods

showsPrec :: Int -> Key a -> ShowS

show :: Key a -> String

showList :: [Key a] -> ShowS

Generic (Key a)

Associated Types

type Rep (Key a) :: * -> *

Methods

from :: Key a -> Rep (Key a) x

to :: Rep (Key a) x -> Key a

type Rep (Key a)

type Rep (Key a) = D1 * (MetaData "Key" "Bookkeeper.Internal" "bookkeeper-0.2.5-7Bfa1Oe73gjGQk0shmMf9V" False) (C1 * (MetaCons "Key" PrefixI False) (U1 *))

From Haskell record

fromRecord :: (Generic a, FromGeneric (Rep a) bookRep) => a -> Book' bookRep

Generate a Book from an ordinary Haskell record via GHC Generics.

>>> data Test = Test {  field1 :: String, field2 :: Int, field3 :: Char } deriving Generic
>>> fromRecord (Test "hello" 0 'c')
Book {field1 = "hello", field2 = 0, field3 = 'c'}

Trying to convert a datatype which is not a record will result in a type error:

>>> data SomeSumType = LeftSide | RightSide deriving Generic
>>> fromRecord LeftSide
...
... • Cannot convert sum types into Books
...

>>> data Unit = Unit deriving Generic
>>> fromRecord Unit
...
... • Cannot convert non-record types into Books
...

Re-exports

(&) :: a -> (a -> b) -> b infixl 1

& is a reverse application operator. This provides notational convenience. Its precedence is one higher than that of the forward application operator $, which allows & to be nested in $.

Since: 4.8.0.0