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 of 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

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

runFramer reads chunks from the ByteSource, parses these into frames and invokes the FrameHandler. Each invocation returns a Progression, which indicates if processing should continue. This allows the FrameHandler to trigger termination of runFramer.

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

This is because its intended use is for parsing framed protocol byte streams; where parsing or connection errors 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.