OSGeo
Create a standardize format name for the shell script style (the g flag)
Background
Recently, we were introducing JSON outputs and in the past, we already introduced the format parameter to tools like v.db.select. One question which remains is how the key-value format usually enabled by -g should be called? Documentation usually calls it something along the lines of "shell script style". The format is usually =-separated key-value pairs, one per line and unique keys (not always though). The original idea was that it can be put directly to Bash's eval function. This is the format typically parsed in the past by grass.script.parse_command to create a Python dictionary with keys and values provided by -g (side note: now that parses JSON as well but still defaults to expecting =-separated key-values).
Question
How the following flag should be replaced with a format option/parameter? Specifically, which value to use for the format option?
-g Print the stats in shell script style
Examples
This flag is, for example, found in r.univar and format option allows switching only between plain and json. -g right now acts as a modifier of the plain format. However, the idea is to present that as its own format which is likely more precise and fits with other tools with multiple formats. See these formats in v.db.select:
plain: Configurable plain text output
csv: CSV (Comma Separated Values)
json: JSON (JavaScript Object Notation)
vertical: Plain text vertical output (instead of horizontal)
r.univar has only:
plain: Plain text output
json: JSON (JavaScript Object Notation)
but should have something like:
plain: Plain text output
json: JSON (JavaScript Object Notation)
shell: Shell script style
Suggestions
Options:
shell: Shell script style
bash: Shell script style
bash: Bash-like script style
bash: Bash-like key-value pairs
bash: Key-value pairs in Bash-like syntax
eval: Values in Bash eval syntax
key-value: Key-value pairs in Bash-like syntax
keyval: Key-value pairs separated by equal sign
Feel free to add your suggestions or combinations of the above.
The description will be easy to change in the future, but the value is part of the API, so we need to set it and stick to it. Thus, the big decision is really between sh, shell, bash, script, eval, key-value, keyvalue, keyval, eqsep, ...
Implementation in v8 versus v9
In v8, we would add this to existing tools which now have format option and -g flag, for example r.univar. -g would stay there for compatibility. In v9, we can remove -g and only format would be used to change the output format. (This is similar to what happened with -v Vertical output (instead of horizontal) in v.db.select between v7 and v8.)
I'm putting this a blocker for the next major/minor release because it would be good to get it right for the release. (A backward compatible change in the future is possible, but it is avoidable if we decide soon.)
Relation to the Tools API
In the Tools API, I'm using keyval:
tools = Tools()
assert tools.g_region(flags="p", format="shell").keyval["nsres"] == 1
On the other hand, the new format option is still going with shell. For the tools, shell would look strange:
assert tools.g_region(flags="p", format="shell").shell["nsres"] == 1
It is not a big deal for the Tools because the idea is that everything will have JSON, so keyval can be even removed without much impact (that's not the case now, but we are close).
Assuming we keep keyval in Tools, it is important to note that keyval in Tools really parses only the key-value pairs Bash's eval would parse as variables. So, the names don't have to be the same because keyval in Tools is more limited than what format="shell" can be because we don't constrain it to the key-value pairs.
Does -g break down to more formats?
This brings the question whether format="shell" is actually an appropriate universal name of the format when the format is sometimes key-value pairs (which can be processed by Bash's eval, keyval in Tools, and the current parse_command), while sometimes the format is simply something easy enough to parse in a scripting language, but not necessarily key-values. An example of this is currently v.category:
v.category input=bridges option=report format=shell
1 point 10938 1 10938
1 all 10938 1 10938
So, this is definitely not Bash eval friendly, so it goes away from the original idea of shell, but it is still easily parsable/parseable in different shell languages or other scripting languages. This would suggest that the format would be parsable to indicate the intention without specifying the actual format.
A possible alternative, at least here, would be to output CSV, so format="csv" rather than format="shell". This replaces the -g flag, but replaces the flag by something else than format="shell".
Keeping format="shell" to always be the same key-value pairs format seems beneficial regardless of the name. However, with a clear definition, more descriptive name might be more appropriate and easier to pick.