feat: Support YAML literal blocks for multiline strings

[ivov]

Thanks for the project!

This PR adds opt-in support for YAML literal blocks for multiline strings in snapshot metadata fields like description and expression. Trailing newlines are preserved via chomping indicators (|-, |, |+).

Set INSTA_YAML_BLOCK_STYLE=1 to enable.

Before:

expression: "fn add(a: i32, b: i32) -> i32 {\n    a + b\n}"

After:

expression: |-
  fn add(a: i32, b: i32) -> i32 {
      a + b
  }

I noticed the YAML lib is vendored and assumed extending it was acceptable - please let me know if you'd prefer a different approach.

Closes #782

[max-sixty]

thanks for the contribution

what's the standard for frontmatter — are these allowed?

I agree this makes it more readable. OTOH it adds another option + introduces backward-compat issues, so need to weigh those...

[ivov]

Thanks for the quick reply :)

what's the standard for frontmatter — are these allowed?

Yes! Literal blocks are standard YAML so any compliant parser handles them, and frontmatter is YAML between --- markers, not a separate spec.

I agree this makes it more readable. OTOH it adds another option + introduces backward-compat issues, so need to weigh those...

Added as opt-in so users control the switch. Older insta versions support this because the parser already supports literal blocks - this PR only extends the emitter. But indeed it's a new option to maintain.

[max-sixty]

yes, another option would be "min-version", which we've thought about a bit before... I think the versioning is basically the only reason to have the config here; so in that case we could just adopt the "min-version" config. Or push this to #456

let me leave this open for a bit to see if others have thoughts (including @mitsuhiko )

thank you again

[ivov]

Hi @max-sixty! I was wondering if you or @mitsuhiko had time to think about this one. Happy to close it out if the tradeoff isn't worth it for you. In any case thanks for the great lib.

[max-sixty]

I think this is an improvement, but I'm very keen to avoid backward compat breaks

Would you be up for:

• Merging the reading of these snapshots
• but not yet merging the writing of them

we could add a settings or an env var to turn them writing them on, if you wanted, so that people have to selectively turn them on. I would prefer to wait a couple of versions to even add that, but if you wanted I'm happy to do it sooner

hope that's reasonable! my main focus is that anyone running on default doesn't start getting compatibility errors because one person on the team upgraded before others...

[ivov]

Thanks for your quick reply! I want to make sure I'm understanding you correctly.

There are two things "compatibility errors" can mean: (1) old reader chokes on |- blocks, and (2) reader parses them fine, but on --accept rewrites the metadata back to quoted form, so the file alternates styles depending on who last accepted.

For (1), this is not an issue. From what I see, the scanner has handled | and > block scalars in every insta release. So "merge reading first" would be a no-op, there is nothing to merge in that case, unless I'm misreading you.

For (2), default behavior is unchanged. In this PR the writer is already behind INSTA_YAML_BLOCK_STYLE=1 so anyone upgrading without setting it sees no change. The risk is mixed env var settings within a team, so if some members set it and others don't, files will alternate styles on accept. This risk cannot be prevented by rollout, but it could be prevented if we consider e.g. a style-preserving emitter, as in, capture each scalar's source style on read and re-emit in that same style, but that'd be a bigger change.

Options, as far as I understand:

• Merge, documenting what to expect in team settings when enabling this env var.
• Build a style-preserving emitter before merging.
• Close this out if not worth it to you. I can fork and add this myself.

For context on the motivation, I maintain the lisette compiler, which makes heavy use of snapshot tests, and most of them embed multiline source as snapshot metadata.

[max-sixty]

sorry! it had been a while and I should have reminded myself of the PR before launching into a proposal, which your code already did!

merging + thank you very much for the code & patience!