Provides the Framer data type that combines an Attoparsec Parser with a a few additional combinators that allow the parser to be used to process frames from the framed byte streams commonly used in network protocol implementations.

A Framer specifies how the processing function runFramer should parse a byte stream.

Minimally, a Framer specifies

• An Parser, used to extract frames from the byte stream
• a FrameHandler responsible using the parsed frames
• the bytestream source, represented a ByteSource

runFramer the FrameHandler is invoked repeatedly; on each invocation it returns a Progression, which indicates if processing should continue. This makes it possible to terminate for the FrameHandler to signal that frame processing should terminate.

On failures, runFramer throws Exceptions using MonadThrow rather than using an Either or MonadError

This is because it is intended to be used to parse framed protocol byte streams; where parsing or connection errors here are typically not recoverable. In haskell non-recoverable failures are better modelled using Exceptions.

Although it throws NoMoreInput or BrokenFrame when appropriate, it provides hooks to override these when constructing a Framer.

By use of setOnClosed and setOnBadParse, the caller of runFramer can completely override the exception type that is raised when runFramer encounters any failure.