Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Try supporting Blueprints written in TOML #1684

Draft
wants to merge 2 commits into
base: trunk
Choose a base branch
from

Conversation

brandonpayton
Copy link
Member

Motivation for the change, related issues

@adamziel mentioned the possibility of supporting Blueprints written in TOML:
WordPress/blueprints-library#114

JSON is a great data format, but lack of multiline strings can make writing Blueprints in it annoying. TOML seems like a reasonable alternative that supports multiline strings, has a less verbose syntax, and none of the YAML downsides (ambiguity, refs).

Implementation details

This PR adds a dependency on the smol-toml library and simply tries parsing as TOML when JSON parsing fails.

Testing Instructions (or ideally a Blueprint)

If we want this, we need unit tests, but for now, you can test locally with:

@brandonpayton
Copy link
Member Author

This is just an exploratory PR. If we want this, we'll at least need to update the Blueprints Builder as well.

@brandonpayton
Copy link
Member Author

Adding the smol-toml dependency adds 40K to the from the built wasm-wordpress-net/assets dir.

@adamziel
Copy link
Collaborator

adamziel commented Aug 27, 2024

Thank you for exploring this! Let's hold on with merging for now, but let's keep it around for the time when we focus on the configuration more.

What I already like:

  • It's just a different way of parsing the input
  • The same validation mechanism works

What I wonder about:

  • Can we make the input shape more ergonomic for TOML? Or is it fine now?
  • Can we provide some TOML-specific niceties that we cannot in JSON?
  • Would the above ideas translate neatly into the PHP Blueprints library?

smol-toml

❤️

@brandonpayton
Copy link
Member Author

Thank you for exploring this! Let's hold on with merging for now, but let's keep it around for the time when we focus on the configuration more.

That sounds good. Moved to "Future work".

What I already like:

  • The same validation mechanism works

I like this too!

What I wonder about:

  • Can we make the input shape more ergonomic for TOML? Or is it fine now?
  • Can we provide some TOML-specific niceties that we cannot in JSON?

These are good questions. Offhand, it just seems like this is a more human-friendly format that can be parsed to a data structure that is similar to those derived from JSON and YAML. Is there anything particular you had in mind?

One possible drawback for TOML authoring is a lack of autocomplete support compared to what we get from JSON + JSON Schema. But it seems possible to use a JSON schema to hint at the expected structure of a TOML doc. This is discussed a bit here in the TOML repo.

smol-toml

❤️

😄

@adamziel adamziel force-pushed the trunk branch 2 times, most recently from 680cd19 to 2e376d2 Compare October 4, 2024 09:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants