# grab: Applicative non-linear consumption

### The Grab type

A grab consumes some portion (none, part, or all) of
its input `bag`

, and returns a `residue`

consisting of
the unconsumed input, some monoidal `log`

(e.g. a list
of error messages), and some `desideratum`

(the object
of desire) produced from the consumed input, or
`Nothing`

if the grab failed.

newtype Grab bag residue log desideratum = Grab ( bag -> (residue, log, Maybe desideratum) )

Grabs are useful as parsers for inputs such as JSON objects or lists of form parameters, where the input data is not necessarily given linearly in the same order in which we want to consume it.

### Applicative composition

A `Simple`

grab (where the `bag`

and `residue`

are the
same type) has an `Applicative`

instance.

instance (bag ~ residue, Monoid log) => Applicative (Grab bag residue log)

For example, we can create two simple list grabs, one that grabs multiples of two, and the other that grabs multiples of three:

twos, threes :: Monoid log => Control.Grab.Simple [Integer] log [Integer] twos = partition (Data.List.partition (\x -> mod x 2 == 0)) threes = partition (Data.List.partition (\x -> mod x 3 == 0))

λ> runGrabMaybe ((,) <$> twos @() <*> threes @()) [1..10] Just ([2,4,6,8,10],[3,9])

Notice that the second part of the resulting tuple contains only
the *odd* multiples of three. Because `twos`

runs first, it
consumes `6`

before the `threes`

can get it.

### Pipeline composition

`a / b`

is a pipeline of two grabs, where the desideratum from
`a`

is the `bag`

for `b`

.
.
> (/) :: Semigroup log
> => Grab bag residue log x
> -> Grab x _residue log desideratum
> -> Grab bag residue log desideratum

λ> runGrabMaybe (twos @() / threes @()) [1..10] Just [6]

λ> runGrabMaybe ((,) <$> (twos @() / threes @()) <*> threes @()) [1..10] Just ([6],[3,9])

## Downloads

- grab-0.0.0.8.tar.gz [browse] (Cabal source package)
- Package description (revised from the package)

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

#### Maintainer's Corner

For package maintainers and hackage trustees

Candidates

- No Candidates

Versions [RSS] | 0.0.0.1, 0.0.0.4, 0.0.0.6, 0.0.0.7, 0.0.0.8 |
---|---|

Change log | changelog.md |

Dependencies | base (>=4.12 && <4.18) [details] |

License | MIT |

Copyright | 2021 Mission Valley Software LLC |

Author | Chris Martin |

Maintainer | Chris Martin, Julie Moronuki |

Revised | Revision 1 made by chris_martin at 2023-05-31T21:23:27Z |

Category | Control |

Home page | https://github.com/typeclasses/grab |

Bug tracker | https://github.com/typeclasses/grab/issues |

Uploaded | by chris_martin at 2022-06-20T19:18:02Z |

Distributions | NixOS:0.0.0.8 |

Reverse Dependencies | 1 direct, 0 indirect [details] |

Downloads | 868 total (7 in the last 30 days) |

Rating | 2.0 (votes: 1) [estimated by Bayesian average] |

Your Rating | |

Status | Docs available [build log] Last success reported on 2022-06-20 [all 1 reports] |