rbdavis
commented
2 years ago Paul, this certainly helps, but many questions remain.
I do not understand how a long-option with multiple directives and/or multiple modifiers would be expressed, nor how any particular directive or modifier with multiple arguments (if that's possible) would be expressed. It seems that there must somehow be special separator characters between (i) one directive set (i.e., a directive and all its arguments together) and the next, (ii) a directive and its first argument, and (iii) each succeeding argument for the same directive after the first argument (if that's possible). And similarly for modifiers. With the latter, + is clearly the separator that indicates a modifier is to follow, but that's perhaps not a surefire guarantee as some arguments may be numeric values which may be plus-signed (either mantissa or exponent)?
Can you give me an example of a long-option specification with (i) three directives, where the first takes 0 arguments, the second takes 1 argument, and the third takes 2 arguments, and (ii) three modifiers, where again the first takes 0 arguments, the second takes 1 argument, and the third takes 2 arguments? Is such an option even possible, or are there restrictions as to how many directives or modifiers can be present and/or how many arguments any particular directive or modifier can take?
Here is my uninformed attempt at providing such an example for module longopttestmodule with long-option longopt, using a syntax format which is hopefully somewhat like what you have in mind (but almost certainly not exactly the same, I'm sure). longopt has 3 possible directives ld0, ld1, and ld2 taking 0, 1 and 2 arguments respectively. It also has 3 possible modifiers lm0, lm1 and lm2 again taking 0, 1 and 2 arguments respectively. Does the following look anything like what you have in mind?
gmt longopttestmodule \ --longopt=ld0::ld1:ld1arg::ld2:ld2arg0:ld2arg1+lm0+lm1:lm1arg+lm2:lm2arg0:lm2arg1
Here all arguments for any particular directive or modifier are separated from the preceding directive or modifier keyword and any other argument for that same directive or modifier by a single colon, while each directive set (i.e., a directive and its arguments) is separated from an adjacent directive set by a double-colon. Each modifier set (i.e., a modifier and its arguments) is separated from any adjacent modifier set and from any preceding directive set by the plus sign.
The above is not meant as a proposal (although I suppose it could be made one) but rather only an attempt by me to figure out how you are thinking that multiple directives/modifiers (each with possibly multiple arguments) will be specified. Actual use of the syntax I have imagined here could fail of course if existing GMT arguments make any use of single- or double-colons (as they may well do, I expect).
PaulWessel
Background
The most recent NSF proposal for GMT support discussed introducing more human-readable command-line options in GMT so that it would be possible to understand what GMT options are doing without having to consult a manual for translation. For instance, current a GMT command line might look like this:
gmt blockmean infile.txt -R0/30/0/30 -I2/1 -Wi > out.txtwhere it is not clear to anyone new what this means. The anticipated long-format version of the same command would be
gmt blockmean infile.txt --region=0/30/0/30 --increment=2/1 --weights=in > out.txtwhich is much clearer. GMT modules all rely on two parsers: _GMT_ParseCommon (an API function) for all common options (-R -J, etc.) and the static local functions parse (one in every module C file) for the module-specific options (e.g., -W above). In order to implement long-options the decision was made to introduce a translator from the long-format syntax to the corresponding short-format syntax that can be called just before the established parsers are called. A prototype translator called gmtinit_translate_to_short_options was coded and is tested just for the common options. The translator will depend on two arrays of structures:
The _gmt_initmodule function does lots of stuff, now including the translation based on these two vocabularies. For now only a few modules have local structures, e.g., blockm*.c.
Option Template
The premise for the translation is that the two forms (long and short) are equivalent. This is not necessarily true for everything even though it certainly is true for many options. Ideally, short-format options should follow this template:
-<short_option>[<short_directives>][+<short_modifier1>[<argument1>]][+<short_modifier2>[<argument2>]][...]while the long-format options look like
--<long_option>[=<long_directives>[:][<arg>][+<long_modifier1>[=<arg1>]][+<long_modifier2>[=<arg2>]][...]Thus, depending if an option has directives or not, and if those take values, things can look like this (keeping modifiers off for now):
I think some options may take more than one directives or arguments, and these may be separated by commas or slashes (as specified in the structure).
Historically, some short options in GMT have changed from being extremely long and cumbersome to now still being complicated even after being split into multiple options. The most important one of those is the -B option for basemap annotation and frame selection. To not get bogged down in intractable situations I propose we simply wait with -B which I suspect will be a special case that cannot simply be translated back and forth. But I do not know yet. Below, we can explore which options satisfy or do not satisfy the round-trip translation criterion.
surface
Here is the list of non-common options available in surface:
First problem is the -G output grid where we historically have used = to append a specific grid format code. Hence, that might look like a long-format directive but it is short-format syntax. However, all the rest seems straightforward to make into long-options:
The -I is a near-common option and it is already implemented via the constant GMT_INCREMENT_KW defined in gmt_constants.h. I lists '/' as separator, meaning the arguments may be repeated with a slash between them.
Here is a surface command from one of the tests (test/surface/limits.sh) in short and then as a plausible long-format:
Selecting suitable long-format words for directives and modifiers
Because both PyGMT and especially GMT.jl have moved ahead and implemented lots of keyword/value pairs, we should strive to use their word choices unless we feel it is just the wrong phrase. Thus, it is likely that Paul will have opinions on any selection. Hence, the initial selection of words is not crucial since they are just a set of unique strings (per module). Roger can invent suitable phrases that he things makes sense and fill out the KW structure arrays. Once a module has long-options that work we can revise the actual words as we see fit.