[PROPOSAL] Syntax convention for command output

[leopoldhub]

Hi there,

I would like to discuss and collectively decide on the
convention and format of our command output.

Currently, each of our commands returns human-readable messages that are barely parsable by machine.

I am working on third-party applications that need to interact with this project, and would like to define a convention for message returns to make them easier to parse.

Here is my proposal, feel free to express any doubts, concerns, improvements or objections, as well as any other possible solutions.

For the general format, I am thinking about using YAML because it is simple, minimal (opposite of XML/JSON), and human readable.

For example:
fw-fanctrl reload
actual:

Reloaded with success! Strategy in use: 'laziest'

YAML

status: success
strategy: laziest

My main concern is that we might lose a bit of readability for standard users.
To address this, I was thinking of a command option (e.g. --yaml) and still use human readable messages when necessary, except when this option is present.

What do you think about this?

[leopoldhub]

Hi, I would like to bring this proposal to your attention again so that we can decide which of the above options we should go with and allow me to work on this part as soon as possible.

After much consideration, YAML would be the best API data structure, as it is easily readable by humans, as well as easily parsable by programs and Unix commands.

However, unlike JSON, YAML parsing is not included in the standard Python libraries.
This means that we would have to install the Python library pyyaml, which itself requires work on both the project and its various packages to ensure compatibility with all systems.

So I would like to know your opinion on this.
Should we add a dependency to ensure readability with YAML, or use the standard json library at the expense of human readability and slightly harder Unix command parsing?

I would also like to know the impact that adding a dependency would have on the different packaging solutions, as well as what would be the best approach for this work if we opt for the YAML option.

@TamtamHero, @icedream, @Svenum, @tulilirockz

[Svenum]

I think json is the better option, if it is builtin in python. If you explicit need to use the --json flag only people who can read json would use it. So you dont need to make sure its more readable for all users.

[leopoldhub]

Hi @Svenum , how are you doing?

only people who can read json would use it

Fair enough I guess, the last thing that bothers me is the fact that it will be a bit harder to create bash scripts that parse the output, but I guess we can add a yaml option later if needed.

I am still curious about the effects that #94 would have on the Nix packaging.
Can you have a look at it when you have some free time?

Thanks a lot!

[Svenum]

If you want to use it in bash you could use tje small Programm named "jq" to parse and querry stuff.

I will take a look at the other one as soon as possible