Control.Grab

Types

The Grab type

newtype Grab bag residue log desideratum

A Grab:

1. Consumes some portion (none, part, or all) of its input bag;

2. Returns a Result:

   • A residue consisting of the unconsumed input;
   • Some monoidal log e.g. a list of error messages;
   • Some desideratum (the object of desire) produced from the consumed input, or Nothing if the grab failed.

Specializations of this type:

• If the bag and residue types are the same, the grab is a Simple grab and it has an Applicative instance.
• If the residue is (), the grab is a Dump; it dumps out the entire bag so there is nothing remaining.
• If the bag is (), the grab is just a single fixed Result, which consists of the residue, log, and maybe the desideratum.
• If both the bag and residue are (), the grab is just the Extract, which consists of the log and maybe the desideratum.

Constructors

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

Instances

Bifunctor (Grab bag residue)

Defined in Control.Grab

Methods

bimap :: (a -> b) -> (c -> d) -> Grab bag residue a c -> Grab bag residue b d

first :: (a -> b) -> Grab bag residue a c -> Grab bag residue b c

second :: (b -> c) -> Grab bag residue a b -> Grab bag residue a c

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

Defined in Control.Grab

Methods

pure :: a -> Grab bag residue log a

(<*>) :: Grab bag residue log (a -> b) -> Grab bag residue log a -> Grab bag residue log b

liftA2 :: (a -> b -> c) -> Grab bag residue log a -> Grab bag residue log b -> Grab bag residue log c

(*>) :: Grab bag residue log a -> Grab bag residue log b -> Grab bag residue log b

(<*) :: Grab bag residue log a -> Grab bag residue log b -> Grab bag residue log a

Functor (Grab bag residue log)

Defined in Control.Grab

Methods

fmap :: (a -> b) -> Grab bag residue log a -> Grab bag residue log b

(<$) :: a -> Grab bag residue log b -> Grab bag residue log a

Aliases: Simple, Dump, Result, Extract

type Simple bag log desideratum = Grab bag bag log desideratum

A Simple grab:

1. Consumes some portion (none, part, or all) of its input bag;

2. Returns a Result:

   • A modified bag representing the unconsumed portion of the input;
   • Some monoidal log e.g. a list of error messages;
   • Some desideratum (the object of desire) produced from the consumed input, or Nothing if the grab failed.

type Dump bag log desideratum = Grab bag () log desideratum

A Dump:

1. Consumes all of its input bag;

2. Returns a Extract:

   • Some monoidal log e.g. a list of error messages;
   • Some desideratum (the object of desire) produced from the consumed input, or Nothing if the grab failed.

type Result residue log desideratum = Grab () residue log desideratum

The result of performing a Grab. Consists of:

• A residue consisting of the unconsumed input;
• Some monoidal log e.g. a list of error messages;
• Some desideratum (the object of desire) produced from the consumed input, or Nothing if the grab failed.

type Extract log desideratum = Grab () () log desideratum

What is produced by performing a Dump. Consists of:

• Some monoidal log e.g. a list of error messages;
• Some desideratum (the object of desire) produced from the consumed input, or Nothing if the grab failed.

Creation

Making grabs

partition

Arguments

:: forall bag residue log desideratum. Monoid log

=> (bag -> (desideratum, residue))

Function that partitions the bag into desideratum and residue.

-> Grab bag residue log desideratum

A grab that always succeeds and never logs.

(/)

Arguments

:: forall bag residue _r log x desideratum. Semigroup log

=> Grab bag residue log x

The first grab a, whose desideratum x will be passed as input to the second grab b.

-> Grab x _r log desideratum

The second grab b. The residue of this grab will be ignored, so it usually ought to be a Dump.

-> Grab bag residue log desideratum

A grab whose result is the residue of a, the combined logs of both a and b, and the desideratum of b.

a / b is a pipeline of two grabs, using the output of a as the input to b.

Making dumps

dump

Arguments

:: forall bag log desideratum. (bag -> Extract log desideratum)

A function which, given the entire input, produces some log output and maybe a desideratum.

-> Dump bag log desideratum

A grab that consumes the entire bag, producing whatever the function extracted from its contents.

discardResidue

Arguments

:: forall bag residue log desideratum. Grab bag residue log desideratum

A grab which may produce some residue.

-> Dump bag log desideratum

A grab that produces no residue.

Making extracts

success

Arguments

:: forall log desideratum. Monoid log

=> desideratum

The desired object.

-> Extract log desideratum

A successful extract with an empty log.

failure

Arguments

:: forall log desideratum. log

Log output such as an error message.

-> Extract log desideratum

An extract with the given log and no desideratum.

warning

Arguments

:: forall log. log

Log output such as a warning message.

-> Extract log ()

An extract with the given log and a desideratum of ().

extract

Arguments

:: forall log desideratum. log

Log output, such as an error or warning message.

-> Maybe desideratum

Just some desideratum if the extract represents the outcome of a successful grab, or Nothing if it represents failure.

-> Extract log desideratum

An extract consisting of the given log and desideratum.

The most general way to construct an Extract.

Use

Applying a grab to an input

runGrab

Arguments

:: forall bag residue log desideratum. Grab bag residue log desideratum

A grab, which may consume some portion of the input.

-> bag

The input.

-> Result residue log desideratum

The result of performing the grab, which consists of the residue representing the remaining portion of input, a log for providing error output, and a desideratum if the grab was successful.

When residue is (), this function specializes to runDump.

runDump

Arguments

:: forall bag log desideratum. Dump bag log desideratum

A dump which consumes the input.

-> bag

The input.

-> Extract log desideratum

The result extracted from the input, which consists of a log for providing error output and a desideratum if the grab was successful.

This is a specialization of the more general runGrab function.

Deconstructing results

residue

Arguments

:: forall residue log desideratum. Result residue log desideratum

The result of running a Grab

-> residue

The portion of the bag that was not consumed by the grab.

log

Arguments

:: forall residue log desideratum. Result residue log desideratum

Either a Result or an Extract.

-> log

Any extra information produced during the grab, such as error messages.

desideratum

Arguments

:: forall residue log desideratum. Result residue log desideratum

Either a Result or an Extract.

-> Maybe desideratum

The desired object, if one was successfully extracted from the bag.

Both applying and deconstructing

runGrabMaybe :: forall bag residue log desideratum. Grab bag residue log desideratum -> bag -> Maybe desideratum

Run a grab, ignoring the residue and log, producing only the desideratum.

runGrabMaybe x = desideratum . runGrab x