prettyprinter: generalise alterAnnotationsS to lists

[ners]

We can very simply support reannotating to a list of annotations if we store a counter instead of a boolean in the stack.

[sjakobi]

Since this is a breaking change, it would be good to understand the motivation behind it. Could you explain why you want this change?

[ners]

Hey @sjakobi, thank you for the speedy reply.

The background of the motivation is a little bit involved:

• I maintain the following library which uses a combination of prettyprinter and terminal: https://github.com/ners/terminal-widgets
  The prettyprinter annotation in use here is Attribute m, an associated data type to the MonadMarkupPrinter typeclass.
• I've authored another library which produces SimpleDocStream ann from skylighting output.
  The intention of this library is having skylighted inputs in terminal-widgets.
• Finally, I've also written a CLI tool that uses terminal-widgets to construct an API query and then pretty-prints the JSON result using the aforementioned skylighting prettyprinter and aeson-pretty.
• To print the result, I use prettyprinter-ansi-terminal, which has a different annotation type: AnsiStyle
• The mapping from terminal's Attribute m to AnsiStyle is nontrivial because you don't really know what Attribute m is.
• The mapping from AnsiStyle to Attribute m is easy to implement if we are able to have this fanout.

I've implemented the function first in my own codebase, to confirm that it works as intended.

Then I researched the Prettyprinter codebase to see why such a function does not yet exist. The alterAnnotationsS is a natural fit, but for some reason it is implemented with a boolean stack. This change gives it power parity with alterAnnotations, which means we can remove all the comments that warn users that it's less powerful.

I think it's worth the breaking change to generalise this function. That's what semver is for after all. Another possibility is exposing this a separate function, but then I'd question the need for alterAnnotationsS.

[sjakobi]

I agree that this would improve the API.

What I'd like to be more sure of:

• Is this change correct? Unfortunately there's only a single test for alterAnnotationsS in the testsuite. Are there any properties that we could test for alterAnnotationsS?
• Is the performance good? In particular I'm suspicious of the length bit – it seems a bit unfortunate that the result list has to be traversed twice. I don't see an obvious way to avoid that though. Maybe n should be strict?!