DRAFT: GMT 7 Long-options and keyword/argument review

[PaulWessel]

Our Task

As discussed at the Oslo Summit, we have tasked ourselves with reviewing the long-options that @rbdavis (and a little bit from @PaulWessel) have suggested. These are to be considered as first drafts for the @GenericMappingTools/long-options-review team to look at. Our task is to respond to calls for review, opine and suggest improved keywords or aliases as you see fit. We then do a quick debate and to with a consensus choice that is in line with equivalent keywords already implemented in PyGMT and GMT.jl. Because of the number of reviews we will give a time limit and if you do not get your 2-cents in then you missed you chance to change some keywords. Of course, it is likely we do a final review before an official GMT 7 is released, as anything in master is never a final decision.

Highlight of Technical Background

Top level summary of the C implementation is that we have written some functions that will translate a long-option command line to the equivalent short-option command line that our 150 module parser understand. We seek to translate

--<long_option>[=<long_directives>[:<arg>]][+<long_modifier1>[:<arg1>]][+<long_modifier2>[:<arg2>]][...]

to

-<short_option>[<short_directives>][+<short_modifier1>[<argument1>]][+<short_modifier2>[<argument2>]][...]

This translator code may be updated as needed if we run into problems. So far, so good, including implementing the use of colons we discussed in Oslo [We also have or will have the inverse converter to convert short options to long-options; more on that later). @rbdavis has completed ~30 of these files (and I have done the common options and a few modules) and these were merged into master between summer 2022 and this spring. There are also 3 PRs not yet reviewed or merged. Since it was mostly me who approved the mergers and sometimes @joa-quim looked at these we should include them all in our review goal. I did not do a thorough job of comparing to Julia/Python, for example (but @rbdavis does). If you want to peak under the hood at the translation functions you can search for USE_COMMON_LONG_OPTIONS in gmt_init.c and for common options you can peruse gmt_common_longoptions.h.

What Are We Reviewing?

Each module (e.g., grdedit) has a corresponding long-option include file (e.g., longopt/grdedit_inc.h). When the review calls us to examine long-options for module A, B, and C we just need to look at the three longopt/[ABC]_inc.h files. There will be 150 of these files.

Example of Submitted Include File

Here is the actual include file content for module batch that Roger did and I approved June 24 2023:

static struct GMT_KEYWORD_DICTIONARY module_kw[] = {
	/* separator, short_option, long_option,
	          short_directives,    long_directives,
	          short_modifiers,     long_modifiers */
	{ 0, 'D', "noautomove",    "", "", "", "" },
	{ 0, 'F', "templatenames", "", "", "", "" },
	{ 0, 'I', "include",       "", "", "", "" },
	{ 0, 'M', "onemaster",     "", "", "", "" },
	{ 0, 'N', "prefix",        "", "", "", "" },
	{ 0, 'Q', "debug",
	          "s",                 "noexec",
	          "",                  "" },
	{ 0, 'S', "optscript",
	          "b,f",               "preflight,postflight",
	          "",                  "" },
	{ 0, 'T', "njobs|minmax|timefile",
	          "",                  "",
	          "n,p,s,w,W",         "njobs,tagwidth,multisys,words,tabwords" },
	{ 0, 'W', "tmpdir",        "", "", "", "" },
	{ 0, 'Z', "erasescripts",  "", "", "", "" },
	{ 0, '\0', "", "", "", "", ""}  /* End of list marked with empty option and strings */
};

Our job is to examine this file, open up the current module man page, see if the keywords selected for the short options (e.g., -D, -F, etc) are the best one we can think of, and if we collectively cannot agree between two candidates or the best on is a bit long, we can add aliases. The email example was selecting secondaryfilter but add filter as an alias.

Restrictions on Keywords

The keywords for options, directives, and modifiers must adhere to a few rules because we wish them to (ideally) be used across the wrappers, and there they may be considered variable names and hence that adds common restrictions on variables:

1. Cannot start with a number or contain special characters (e.g.,--100div, --WTF!, --go&plot)
2. Only use lower case letters
3. For keywords that lexically are composed of more than a single word, we use underscore, not CameCase of hyphen (which is a subtraction in programming languages).

Format for Review

I suggest those who actually do a review keep it short. If you fully agree then just click your approve button. If you prefer some changes then say stuff like

-D and --noautomove I would prefer --donotmove since retains the starting letter d.
-F and --templatenames  How about --file_format  (again keeping starting f
-M and --onemaster   This should be just --master since it is always one anyway.

and optionally add a patch. When the review time expires I will be the decider on what changes we select based on your input.