Clarify that --raw, --json, --json-stream and --json-translate

[matsduf]

The options --raw, --json and --json-stream give alternative output of the test case results. If none of them are given, the default output is provided. If more than one of them are given, one is respected and the other or others are ignored.

The option --json-translate can only be used in combination with --json-stream, else it is ignored.

1. Clarify the documentation that three formats cannot be combined.
2. Make the code raise an exception if format options are combinded.
3. Make the code raise an exception if --json-translate is used without --json-stream

Input from #246.

[mattias-p]

I suggest that we introduce a --mode=MODE option that takes the values raw, json and json-stream. The original options could be deprecated and kept around for a while, but defined to just set the value of the --mode option and they would not be allowed to be specified together with the --mode option.

[matsduf]

There are pros and cons. With "mode" it is probably easier to see how the different output formats relate to each other, but "--raw" is shorter and simpler to write than "--mode=raw", and probably easier to remember.

Secondly, there is also the "--json-translate" to be handled in a good way.

Is there a good use case for both "json" and "json-stream"? Is there a good reason why "translate" is only implemented with "json-stream" and not "json"?

[mattias-p]

Translation should probably be implemented for both json and json-stream.

I guess it's useful to have both json and json-stream for integration. json-stream is better for stream processing but some tools might not support it. I don't have any examples though.

Can you expand on what you mean with --json-translate being handled in a good way?

Oh, and there's also the dump-profile mode we need to consider. Another possibility is to use sub-commands instead of a --mode option to control the execution mode. zonemaster-cli raw is even shorter than zonemaster-cli --raw.

[matsduf]

Translation should probably be implemented for both json and json-stream.

It is called "translation" but what happens is that an extra field "message" is added. It could be added by default in both cases, and then deprecate "--json-translate".

Can you expand on what you mean with --json-translate being handled in a good way?

Nothing more than the description says. "--json-translate" is silently ignored if "--json-stream" is not selected.

Oh, and there's also the dump-profile mode we need to consider. Another possibility is to use sub-commands instead of a --mode option to control the execution mode. zonemaster-cli raw is even shorter than zonemaster-cli --raw.

Today a bareword is taken to be a domain name. If the domain name is "raw" how should the command be?

[mattias-p]

It is called "translation" but what happens is that an extra field "message" is added. It could be added by default in both cases, and then deprecate "--json-translate".

Ah, I didn't realize. But it's really nice for machines to consume a terse format that doesn't contain a lot of redundant information. The way I see it is that the --json-translate option has an inaccurate name. Since what it really does is to add the message string to the output it would be better if its name reflected that. I'm beginning to feel that the entire CLI interface could use a redesign.

Today a bareword is taken to be a domain name. If the domain name is "raw" how should the command be?

Depends on what mode you want to use. E.g. zonemaster-cli json-stream raw or zonemaster-cli raw raw. We need a good name for the "normal" mode or output format too. I don't think we have one.

[matsduf]

I'm beginning to feel that the entire CLI interface could use a redesign.

I do not disagree, but I am not sure that is priority one.

Today a bareword is taken to be a domain name. If the domain name is "raw" how should the command be?

Depends on what mode you want to use. E.g. zonemaster-cli json-stream raw or zonemaster-cli raw raw. We need a good name for the "normal" mode or output format too. I don't think we have one.

I think I prefer to have zonemaster-cli raw testing TLD raw without having to add an extra command for the mode. Short and sweet for a simple test.

Regarding this issue and #246, I find the documentation very clear. However our implementation is definitely not aligned with the documentation. I would rather suggest that we update our implementation instead of making our documentation cumbersome to fit our weird implementation.

My understanding of the documentation:

• --[no-]raw will translate or not the message tag
• --[no-]json the output will be in JSON format (and dumped at the end)
• --[no-]json-stream the output will be in JSON and streamed to the output
• --[no-]json-translate the JSON output would have a message field with the translated message tag
• --[no-]show-... display or not the associated field

It seems to me that:

1. --json-stream implies --json without the final dump
2. --json-translate does the same job as --no-raw (and --no-json-translate = --raw)
3. --[no-]show-... options do not work with --json or --json-stream

Therefore, I suggest we:

a. make --[no-]show-... options available with --json and --json-stream (see #308)
b. refactor the implementation to make it clear that --json-stream implies --json (without the final JSON dump) and that --raw should be used to keep untranslated message tag (see #309)
c. deprecate --[no-]json-translate and replace it with --[no-]raw (see #309)
d. make the code raise an exception if some options are mutually exclusive (see #309)