An experimental module for splitting a borrow of a record by pattern matching on it. If you want to split out a field gradually and partially, see also Data.Record.Linear.Borrow.Experimental.Split.

The API is subject to future change.

Overview

(.#) is handy when you need only one field of a borrowed record, but not applicable when you need to access more than one fields. For that purpose, we provide (.@) operator for splitting a borrow of a record into FieldBorrows of its fields. Consider the following:

>>> import Data.Ref.Linear (Ref)
>>> import Data.Vector.Mutable.Linear.Borrow (Vector)
>>> import Control.Monad.Borrow.Pure.BO
>>> data MyRecord = MyRecord { int :: Ref Int, strs :: Vector String, bool :: Ref Bool }

Suppose we have a mutable borrow of some MyRecord:

>>> :{
mutRec :: Mut α (MyRecord)
mutRec = undefined
:}

So, let's divide the mutable borrow into several pieces with (.@). First, we need to enable OverloadedLabels extension to construct RecordLabels:

>>> :set -XOverloadedLabels

First, we just want to divide into all the fields, in arbitrary order:

>>> (mutStrs, mutBool, mutInt) = mutRec .@ (#strs, #bool, #int)
>>> :t mutStrs
mutStrs :: Borrow 'Mut α (Vector String)

>>> :t mutBool
mutBool :: Borrow 'Mut α (Ref Bool)

>>> :t mutInt
mutInt :: Borrow 'Mut α (Ref Int)

Or, we can just divide into some of the fields (say, bool and strs):

>>> (mutStrs, mutBool) = mutRec .@ (#strs, #bool)
>>> :t mutStrs
mutStrs :: Borrow 'Mut α (Vector String)

>>> :t mutBool
mutBool :: Borrow 'Mut α (Ref Bool)

Specifying the same field more than once results in a type error:

mutRec .@ (#strs, #bool, #strs)
-- error: Split record fields must be distinct, but got duplicate field: "strs"

In genral, (.@) accepts any eliminator of a record borrow, which is typically one of the following:

1. A tuple of RecordLabels without duplcations (currently 2 to 5 components), or
2. A heterogeneous list RecordLabels of RecordLabels, constructed with (:#-) and RNil, without duplcations on fields.

And fields not listed within the eliminator are not accessible after the split. The examples so far uses tuples as eliminators, but you can also use RecordLabels as follows:

>>> mutStrs :#- mutBool :#- RNil = mutRec .@ #strs :#- #bool :#- RNil

RecordLabels will be mapped to FieldBorrows after the split, and you can also use (:#-) and RNil for pattern-matching.

Indeed, RecordLabel itself is also a RecordEliminator, but if you are using `#f` syntax for constructing RecordLabel, you cannot use it with .@ operator without type annotation because of the ambiguity. If you just want to access one field, you can use (.#) operator.