This package fixes a number of problems with the API that Attoparsec provides
for running parsers.

The difficulties stem from the that that Attoparsec's `IResult` type encompasses
three situations: When parsing has succeeded, when parsing has failed, and when
parsing is awaiting further input. This is insufficient to describe situations
in which we know we are dealing with a subset of these three cases. We address
this by introducing two smaller types: `FinalResult` and `ParseError`.

### FinalResult

`FinalResult` represents a result that we know not to be partial; for example,
the sort of result that we get when running a parser using `parseWith`.

```haskell
data FinalResult i a = FinalResult i (Either ParseError a)
```

### ParseError

`ParseError` represents only the case in which parsing has failed.

```haskell
data ParseError = ParseError [String] String
```

Our `showParseError` function gives an error string in the same format as
Attoparsec's `eitherResult` function.

```haskell
showParseError :: ParseError -> String
```

### BufferedInput

The `BufferedInput` type corresponds to two arguments of Attoparsec's
`parseWith`, the initial input and the action to obtain more input.

```haskell
data BufferedInput m i = BufferedInput i (m i)
```

In each of the modules `Data.Attoparsec.ByteString.Run` and
`Data.Attoparsec.Text.Run`, we provide a function called `parseStream`. This
closely corresponds to Attoparsec's `parseWith` function, but ours returns the
more specific `FinalResult` type, rather than `Result`, reflecting the fact that
a result returned here is never partial.

```haskell
parseStream :: Monad m =>
    BufferedInput m ByteString -> Parser a -> m (FinalResult ByteString a)
```

### RestorableInput

`RestorableInput` offers a new way to do streaming parsing that may be more
convenient than `parseStream` and `BufferedInput`. This type represents an input
stream with the ability to push unused input back to it.

```haskell
data RestorableInput m i = RestorableInput (m i) (i -> m ())
```

We use this type with the `parseAndRestore` function:

```haskell
parseAndRestore :: Monad m =>
    RestorableInput m ByteString -> Parser a -> m (Either ParseError a)
```

This shifts the burden of storing the unused remainder to feed back into the
next parsing step from the user of `parseStream` to the definer of the
`RestorableInput`.