Add options for adding delimiters in output formatter

[westonruter]

In the AMP plugin for WordPress a fork of PHP-CSS-Parser is being used to implement a CSS tree shaker. This tree shaking is done at runtime to remove CSS rules that do not apply to the current document. In order to do this efficiently, it is important the PHP-CSS-Parser not be invoked for each request, but rather that a pre-processed CSS data structure be used to quickly filter out which rules are relevant to the current page.

The the way that this is done in the fork is to add additional delimiter options to the output formatter so that CSS comments can be injected before/after at-rules, and then also prepend comments before declaration blocks, after the selector list, and then after the declaration block. This allows the entire CSS to be serialized and then split by these comments to obtain a flattened data structure for use by the tree shaker at runtime.

This PR proposes the additional formatting options to be merged back upstream.

[westonruter]

@sabberworm I wasn't sure on the best way to extend the output formatter with new properties, so I welcome your feedback.

[sabberworm]

For me this is fine though I think it’s weird to allow a user to insert literal (i.e. unescaped) content during formatting. I know I don’t actually check if the whitespace options contains contain only whitespace but at least there it’s clear from their names that you’re not supposed to set them to non-whitespace strings.

Isn’t the issue actually that it’s impossible to insert comments at arbitrary points in the data structure before rendering? Maybe we should address that?

In the beginning I’d already thought about how best to handle comments and I’ve always found the benefit not worth the additional complexity so I just swallowed them. Then, later there was the patch that enabled to keep some comments that appeared before rules or blocks (I think). I had found this good enough but now it seems we should either correctly handle all comments or not handle any. It feels strange to support only a subset…

[westonruter]

Thank you.

For me this is fine though I think it’s weird to allow a user to insert literal (i.e. unescaped) content during formatting. I know I don’t actually check if the whitespace options contains contain only whitespace but at least there it’s clear from their names that you’re not supposed to set them to non-whitespace strings.

Yes, it does feel a bit weird. Though a CSS comment is somewhat like whitespace, though not exactly, so it doesn't feel completely off.

Isn’t the issue actually that it’s impossible to insert comments at arbitrary points in the data structure before rendering? Maybe we should address that?

Yes, if that were possible then there it wouldn't be necessary to add these additional formatting options.

In the beginning I’d already thought about how best to handle comments and I’ve always found the benefit not worth the additional complexity so I just swallowed them.

It does seem of little value to support comments everywhere possible in the object model.