Topiary; Channel Your Inner Tweag

Mixing it up a bit due to the chaos that is my new “normal”. Along with a mission (at the end), you also get a new resource to play with!

Time to dig into today’s assignment.

Topiary

Topiary is a Rust-based universal source formatter that is a member of the Tree-sitter ecosystem and aims to be a uniform formatter for simple languages. It’s named after the art of shaping plants into pleasing forms, and just like its namesake (i.e., Topiary shapes your code into a more readable and aesthetically pleasing form).

By leveraging Tree-sitter, Topiary can format code by understanding its syntax tree. This means it’s not just blindly applying text transformations; it deliberately reshapes code based on syntactic structure.

You don’t even have to install it to use it! Try the online playground before polluting your pristine system with yet-another binary.

Channeling Your Inner Tweag

Back in Q3 of 2023, Tweag blogged about their revamping of the UX of the Topiary CLI. Yes, CLI tools 100% have UX concerns, and Topiary’s UX was as mundane and sub-par as many tools you likely use on the regular.

In the article, they discuss the challenges and improvements. Some core issues prior to the revamp include:

• Simplicity: Common tasks were difficult to perform due to the combinatorial explosion of flags, options, and modifiers.
• Memorability: It was difficult to remember all the different options.
• Discoverability: The CLI did not effectively guide users towards the full range of possible actions.
• Familiarity: Users had to resort to guessing due to the lack of common idioms.
• Clarity: The output was not always clear, making it difficult to understand the results.

To address these issues, the following improvements were made:

• Make illegal states un-representable: Using Rust’s type system and the clap library, the CLI was redesigned to forbid invalid input.
• Separate modes of operation: Formatting and visualization were separated into distinct sub-commands, making the CLI more intuitive.
• Make use of familiar idioms: The CLI was updated to follow common behaviors and idioms found in other CLI tools.
• Make common tasks easy and unsurprising: The CLI was designed to make common tasks simple and predictable, while still allowing for customization.
• Don’t paint yourself into a corner: The CLI was designed to be flexible and not limit future development or user expectations.

These changes were implemented in Topiary v0.3.

Please digest the linked article as they explain things quite well, especially when emphasizing the “why”.

Your Mission

We’ve asked you to make some CLIs over these ~400 Drops, and you likely have your own, personal tools you maintain.

Use the principles provided by Tweag — and many of the articles we’ve read on command-line completion, CLI argument parsing, and manual page building — to level-up at least one CLI tool of yours over the weekend. Your future self will look back fondly on this time well spent.

FIN

Remember, you can follow and interact with the full text of The Daily Drop’s free posts on Mastodon via @dailydrop.hrbrmstr.dev@dailydrop.hrbrmstr.dev ☮️