Update docs to explain the hoist lift trick

[Gabriella439]

Writing intermediate transformations or lenses is cumbersome because of the need to do explicit state-passing. Normally, you'd want to simplify this using StateT, however the problem is that you don't get a type suitable for Parser. The type you want is:

StateT (Producer a m x) (Producer b m) r

... but that doesn't unify with Parser, so you can't embed Parsers within such a StateT block.

However, the solution is simple: you can wrap any Parser in hoist lift and then it will have the correct type:

parser :: StateT (Producer a m x) m r

hoist lift parser :: StateT (Producer a m x) (Producer b m) r

Then you can write transformations/lenses using StateT to manage all state-passing and still embed parsers within those blocks.

This ticket is to remind myself to update the documentation to explain this trick and to update the source code to use this trick, too.

[bgamari]

I find that you end up encountering this pretty often in practice. It would be great if the documentation were better here.