Re-export #1058 operators from Control.Lens.Operators, fix incorrect documentation

[RyanGlScott]

Fixes #1067.

[endgame]

Thanks for fixing this up, I can only see one doc nit. While we're here, I think we should add the << variants (which return the old result), because the consistency of lens' operator language is one of its greatest strengths. They're also fairly simple to implement.

[RyanGlScott]

While we're here, I think we should add the << variants (which return the old result)

What names would you propose for these? We're in a bit of a weird situation as some of these operators already begin with < and <<, so the usual convention of adding << to the front of the name to indicate returning the old result doesn't work for all of these operators.

[endgame]

I don't think that's a blocker: we already have (<<<>=) for "<> onto part of a MonadState and return the old value".

There are only really three new operators in 5.3.1:

• (<>:~) (prepend front via (<>))
• (<|~) (cons via (<|))
• (|>~) (snoc via (|>))

The PR that added them added the the "return new result variants" (beginning with <) and the MonadState variants (s/~/=). I am just suggesting we fill out the rest of the established pattern:

• (<<<>:~) (prepend front via (<>) and return old result)
• (<<<>:=) (prepend front via (<>) and return old result, MonadState version)
• (<<<|~) (prepend front via (<|) and return old result)
• (<<<|=) (prepend front via (<|) and return old result, MonadState version)
• (<<|>~) (append back via (|>) and return old result)
• (<<|>=) (append back via (|>) and return old result, MonadState version)

Personally, I have never really needed the operators in Control.Lens.Cons and would have expected <|>~ to mean "combine the target of the lens with a new value according to its Alternative instance", but since it's in lens now it's probably best to build out the matching operator variants for consistency.

[RyanGlScott]

I've pushed a commit which implements the operators suggested in #1068 (comment). Let me know if this covers everything.

[endgame]

Seems right to me. Just some whitespace lint which you can take or leave.

Thanks for tidying this up!