☂️ Move Rome CLI to use bpaf

[ematipico]

Description

I have been experimenting with some possible CLI libraries (more potent than pico_args), and I find bpaf really pleasant to work with!

I did a small PoC and it seems that it can work inside the Rome code base, although there are some restrictions and compromises that we have to make:

• we can't use our internal markup! for the help section;
• error handling will be different, and we have to rely on bpaf error messages when the parsing of an argument fails;

I am happy to accept the trade-off! bpaf allows to define arguments in two ways: combinatoric or derive. For Rome, the derive feature works better. The combinatoric way forces you to define every type inside a struct, which differs from what we're looking for inside Rome.

Although, before moving everything to bpaf, some more work needs to be done to lay off the foundations and make the migration smoother.

Below the list of things that we need to do:

First batch:

• Create a new-type for the ignore arguments #4398
• Make every type optional via Option #4399
• Implement rome_deserialize for formatter options #4400

Second batch:

• Move global options to their own struct
• format subcommand via bpaf
• check subcommand via bpaf
• ci subcommand via bpaf
• rage subcommand via bpaf

[Conaclos]

Which other candidates did you review?

[ematipico]

Which other candidates did you review?

Another option is clap but it's super heavy and I'd prefer to avoid it.

Another one was argh but it has less features.

Here's a great community project that compares some libraries: https://github.com/rosetta-rs/argparse-rosetta-rs

I like bpaf because:

• it has multiple styles for composing the parsing of arguments
• it has third party auto completion in case we want to opt-in
• it's actively maintained

[Boshen]

I agree with your conclusion on clap and argh.

Can't wait to see bpaf being used. Maybe I'll convert it in Oxc before Rome does, if I get the time 😁

[pacak]

we can't use our internal markup! for the help section;

Can you tell me a bit more what makes markup! macro great or where can I read about it? I'm looking into changing help/documentation generation so might be able to make it more compatible...

[ematipico]

we can't use our internal markup! for the help section;

Can you tell me a bit more what makes markup! macro great or where can I read about it? I'm looking into changing help/documentation generation so might be able to make it more compatible...

Hi @pacak , thank you for reaching out! :)

The markup! macro is an internal macro that accepts a string HTML-like:

markup!{
	"Something"<Emphasis>"bold"</Emphasis>" or "<Dim>"dimmed"</Dim>
}

This macro creates MarkupElements with an internal implementation of rome_console::fmt::Display. Then, we have different writers based on where we want to write this elements. We have a Terminal writer and an HTML writer.

Here's some internal, useful links:

• The formatter implementation: https://github.com/rome/tools/blob/main/crates/rome_console/src/fmt.rs
• The terminal writer: https://github.com/rome/tools/blob/main/crates/rome_console/src/write/termcolor.rs
• The HTML writer: https://github.com/rome/tools/blob/main/crates/rome_console/src/write/html.rs
• The definition of the markup elements: https://github.com/rome/tools/blob/main/crates/rome_console/src/markup.rs

[pacak]

I see. I'm adding something similar with goals to write to terminal, markdown (well, technically a mix of html and markdown) and manpages, there should be a way to get those two to talk to each other :)