Add `--porcelain` and other flags for formatting command output

[Stratus3D]

Is your feature request related to a problem? Please describe

Currently asdf commands generate output that is intended to be read by humans and also consumed by other programs on the command line. Humans and computers often need different information, and need output formatted in different ways.

Describe the proposed solution

I propose we add a --porcelain flag to all asdf commands. The --porcelain flag should cause the output to conform to the following rules:

• No column headers
• No variable formatting (e.g. wrapping after a certain number of columns)
• When outputting tabular data, easy to parse rows and columns (need more specifics here)

Additionally, each command could have a small number of flags specific to the fields the command can output that turns that field on or off. For example, asdf current outputs plugin name, current version, and place the version was set for each row. Each of these fields could be toggled on or off with a flag. Alternatively we could possibly use a format flag with a format string that we pass to printf. For example:

$ asdf current --format="%s:%s"

Describe similar asdf features and why they are not sufficient

None

Describe other workarounds you've considered

None

Related

• https://github.com/asdf-vm/asdf/pull/762#issuecomment-1176877365
• https://github.com/asdf-vm/asdf/issues/646#issuecomment-650210276
• https://github.com/asdf-vm/asdf/issues/866#issuecomment-776612435

[jthegedus]

Are we set on --porcelain? What are your thoughts on using a more specific flag that implies the format, eg --tsv. See my comment about --porcelain being parse-able, but not predictable across different tooling, like --json would be. It seems a source of confusion there is a concept of porcelain commands & porcelain flags.

[Stratus3D]

@jthegedus I might be missing something here. Are you asking about the flag name (I'm open to anything that makes sense) or the actual output? I like Git's --porcelain output because it's very stripped down and uses symbols instead of human readable text for easier parsing (the ?? test.txt output in the example you show in your comment). I do think we could come up with a better flag name though.

I'm also not opposed to --tsv but I think there is more to easily parsable output on the command line than just tab delimited fields if that makes sense (e.g. using symbols for certain fields as mentioned above).

[jthegedus]

I think the flag name should convey the format, as with CLIs with the --json flag.

Aside from the flag name, what I dislike about the porcelain concept is that it is a tool-specific format. It requires more documentation and is more difficult to consume without the understanding the specific symbols and usage. That's not to say we can't have a flag with the notion of porcelain with it's specific symbols.

As a starting point to separate out human-readable and machine-specific/easily-parsable outputs, a whitespace separated format without the human readable decorations (eg: * markers for installed/not and table headings) would be preferable to me. It would be easier to implement and most consumption would be grep into awk or cut, which is more accessible to more devs.

I definitely think there is space for both types of flags, but I feel we will get somewhere more quickly with a space separated solution. Use of a space separated solution will probably breed ideas for symbol-specific solutions.

I say all this without actually exploring the creation of a grammar for --pocelain symbols.

[jsejcksn]

I think the flag name should convey the format, as with CLIs with the --json flag.

While this is certainly ergonomic to type, I think that supporting a key=value argument is useful for future extensibility — in this case, for example: --format=json,--format=tsv, etc.

[log2]

Our dependency management system (see here and here for a use case) is heavily based on asdf and chokes with the "*" added in front of a version (see here). So, having a flag to force machine-readable output is highly desirable in the long term, especially if other visual cues (great for humans, bad for algorithms) are expected to be merged in, sooner or later. Looking forward to this issue's outcomes, since 0.11.0 currently is a no-go for us. Thank you!