Long-form command-line argument support

[PaulWessel]

With a series of GMT wrappers being built for various computational environments (MATLAB, Python, Julia for now), a key difference with the classic GMT command-line interface is the use of more human-understandable (and longer) keywords and values. For instance, the modern interfaces will use expressions like 'region=20/30/30/50' and not expose users to GMT's short-form -R20/30/30/50 option directly. Because several wrappers are being developed we should insist that the keyword/value pairs be the same for all the wrappers, subject to any language limitations of course. With that as the goal, we will be adding such parsing to the GMT library itself instead of letting all the wrappers reimplement separate parsers. The wrappers are free to go beyond our implementation but should follow our guidelines for "approved" keyword and values for such.

UNIX command-line software often have short options flags (e.g., grep -e pattern) where a single hyphen is used, whereas whole word options use two (e.g., grep --binary-files=value). Thus, it seems reasonable that GMT should follow this well-established model. This means for setting the map or data region one should be able to use either
-Rxmin/xmax/ymin/ymax
or
--region=xmin/xmax/ymin/ymax
My solution for adding such parsing to GMT is simple and already tested at the rudimentary level:

1. All GMT common options and their long/short option names will reside in a single common structured list.

2. Each module will have a separate local list of its module-specific long/short option structured list

3. Each module currently starts with a call to gmt_init_module. We simply add the module-specific list as a new argument and let gmt_init_module convert any occurrence of long-usage option to the corresponding short-usage option. Then, no other changes in GMT are required (except for documentation).

4. Initially, we may only have keywords for the common option and all module lists are NULL, but this can then be expanded as we work our way through the 140+ modules.

To start this off for discussion and feedback, here is a list of GMT's single-character common options and proposed long-name keywords:

J project, projection
R region
U timestamp
V verbosity
X xoff, xoffset
Y yoff, yoffset
a aspatial
c panel
d nodata
e find
f coltype
g gap
h header
i incols, incolumns
o outcols, outcolumns
n interpolation
p perspective
r registration
s skip
t transparency
x cores
: order

So finally, here is an example of a pscoast plot for France that uses many of these, with a mix of single-char options since module options have not been proposed yet:

gmt pscoast --region=FR --projection=M15c -Baf -Gred --timestamp --transparency=30 -pdf map

[joa-quim]

In my view the double hyphens prefixing the keywords serve for nothing (the parsing is all done with the help of the '=' char, not the "--") and make a kind of visual noise that I find unpleasant.

It is true, however, that in the example above we couldn't just have timestamp, but this is the separate issue on how to deal with options that (may) have no flags. For example -: will have to be something like order=yx or use some other keyword like for example yx=true or swapp_xy=true.

[PaulWessel]

I suspect none of that matters too much. For instance, in MATLAB syntax it is common to have a quoted keyword and then a value (e.g., 'Range', [3 9]). Whether the wrapper turns that into --range=3/9 or range=3/9 under the hood is likely not important to the MATLAB/GMT users.
Also, I suspect that some users (and you) might not like the extra hyphens but they are likely to stick with the even shorter existing options or use the wrappers instead. Using the double hyphens then has the benefit of being consistent with UNIX CLI standard, and finally does not make us invent missing arguments to --timestamp and others.

[PaulWessel]

This is clearly something we will be discussing in Faro anyway.

[joa-quim]

Haven't change a bit on my aesthetic opinion nor convinced by the argument of CLI standard argument but I'm afraid the -- may turn out to be necessary, otherwise we would screw the grid=code mechanism.

[remkos]

I do like the --long syntax and I have started to use it already a while ago in my own software projects. In fact, there I have started supporting what is more commonly allowed on CLIs. For example, these ought to be all equivalent:
-R-180/180/-90/90
-R -180/180/-90/90 (with any white space separating the option from its argument)
--region=-180/180/-90/90
--region -180/180/-90/90 (replacing the '=' with any white space)
--reg=-180/180/-90/90 (assuming there is no other long option starting with 'reg')
Now we are only supporting the first alternative, and the above suggests implementing the third. But what about allowing all of these?
The is a GNU linux function getopt_long to deal with the long options. Unfortunately it has a rather silly limitation: long options always need to have a short option equivalent.

[PaulWessel]

One argument against having that space between option and argument has been the need to check if we are passing an optional argument to an option or if it is simply an option without an argument and the next word is an input file. Some options like -D[] would not work well as -D if the argument to D is optional. There would be no way to tell except in that particular module which could do further checking if existed etc. So I think best to keep the options as single words.
As for --reg versus -region: Yes, I think we can get away with just checking the first N unique characters in an option as long as the user only gave N chars. --regxx=g should fail, for instance.

[PaulWessel]

We are started a separate branch for those interested in checking out how this will work or who wants to contribute: #230.

[stale]

This issue has been automatically marked as stale because it has not had activity in the last 30 days. It will be closed if no further activity occurs within 7 days. Thank you for your contributions.

[maxrjones]

Will long-form argument support be available in classic and modern or only modern?

[PaulWessel]

As implemented so far it is mode-agnostic. I think there is no reason to prevent it from being available in one of the modes.

[maxrjones]

As implemented so far it is mode-agnostic. I think there is no reason to prevent it from being available in one of the modes.

OK, thanks for the explanation. I was asking to find out if -K -O -P should also be long-formed.