Add a Stdin Specification

[jfly]

This described the Stdin Specification, and adds a new formatter.stdin_options config to enable treefmt to invoke formatters in "stdin mode".

[jfly]

@brianmcgee @zimbatm, is there anything I can do to help move this forward?

[brianmcgee]

It's unclear to me if this documents the current behaviour or the desired behaviour. If it's the desired behaviour, isn't there some work needing to be done in treefmt to support that before we publish a spec?

[jfly]

If it's the desired behaviour, isn't there some work needing to be done in treefmt to support that before we publish a spec?

Yes, treefmt needs changes to support this. I'm happy to implement that (in this PR or a separate one). I just don't want to put in the effort until I know we like this approach.

[brianmcgee]

I'll try to put my brain on this in the next few days. Been a busy few weeks 😫

[jfly]

@brianmcgee, friendly ping

[brianmcgee]

I agree with some of your own musings in the comments you'd left. Otherwise, it seems like a sane spec and one which should be easy enough for formatters to follow.

I also like that this is opt-in.

[brianmcgee]

P.S. Thanks for taking the time to flesh this out, and sorry for taking a while to get around to reviewing this.

[infinisil]

LGTM!

[jfly]

@brianmcgee @zimbatm, I could use another review on this. If we're happy with the state of this, then I'd like to work on the underlying implementation.

[zimbatm]

Some minor things, but directionally it makes sense.

[zimbatm]

this is a bit hard to read

[jfly]

I agree, but I don't know how to fix it. Does flipping the sentence around help? Suggestions appreciated.

If a formatter's behavior can depend on the name of the file being formatted, then it MUST implement the Stdin Specification.

[cstrahan]

Any remaining work to be done here, or is this just waiting for review?

I'd be happy to lend a hand, if there's any way I can help.

[jfly]

@cstrahan I think this is ready for implementation. I'm pretty swamped right now. If you're up for putting together an implementation, I'd be happy to code review!