Limited multi-argument option parsing

[roberth]

Hi @HuwCampbell, it's been a while, but I think I've figured this one out, based loosely on your idea of changing ReadM.

My realisation was that both your concerns, breaking ReadM and users' ability to do crazy stuff with it, could be addressed by means of a tiered system of ConsumeM and the original ReadM.
This separates the concerns nicely and lets us hide the undesired operations that the ConsumeM would otherwise provide.

This way you can have a straightforward but powerful core, as well as a limited user interface that only exposes whatever we deem sensible argument handling strategies. For now that's statically fixed sets of 0, 1 or 2 arguments, where of course only the 2-argument case is truly new. The 0 and 1 just fall out of the design naturally, and could perhaps play a role in someone's code if they have a use for abstracting over their options' arity somewhat.

Anyway, this is now entirely "simple" Haskell if that's the right term for it. No new extensions.

My only worry in terms of code complexity is the extra indirections due to the Internal module. I suppose what we could do instead is inline that into the ConsumeA module, "hide" its symbols there and drop the tests for it. They're not too interesting anyway. Then we can get rid of some type parameters and type aliases.
I'd be happy to do that if you prefer.

Example:

  parser :: Parser (String, String)
  parser = consumeOption (consumePair str (metavar "KEY") str (metavar "VALUE"))
    (long "set" <> help "Set a configuration value")

->

     Available options:
       --set KEY VALUE          Set a configuration value

References

• Replaces Add biOption for two-argument options #415
  • janky, GADTs
• Closes Parsers that consume multiple arguments #284
  • many-readers
  • "really easy to write really bad user interfaces"
  • breaks compat
• Brief conversation Options with multiple arguments #271