The Setup of a Module

All GMT modules have a common section where key parameters of the module are defined. As an example, here is what psxy.c contains:

#define THIS_MODULE_NAME    "psxy" 
#define THIS_MODULE_LIB     "core" 
#define THIS_MODULE_PURPOSE "Plot lines, polygons, and symbols on maps" 
#define THIS_MODULE_KEYS    "<D{,CC(,T-<,>X},S?(=2" 
#define THIS_MODULE_NEEDS   "dJ" 

These constants are then passed into the module initialization function right after obtaining the option linked list:

if ((GMT = gmt_init_module (API, THIS_MODULE_LIB, THIS_MODULE_NAME, THIS_MODULE_KEYS, THIS_MODULE_NEEDS, &options, &GMT_cpy)) == NULL) bailout (API->error); /* Save current state */

The keys have the following purposes:

  1. THIS_MODULE_NAME is straightforward and contains the name of this module. Modules whose name starts with "gmt" must have that prefix included, as it is GMT_Call_Module job to explore if the user gave a module name without the prefix (e.g., gmtspatial vs just spatial).
  2. THIS_MODULE_LIB specifies that the module belongs to the GMT core or the supplemental plugin, or in the case of custom modules, some other custom plugin library.
  3. THIS_MODULE_PURPOSE simply represents the synopsis statement that explains what this module does.
  4. THIS_MODULE_KEYS is the most complicated to explain and we refer you to the explanations for the GMT_Encode_Options function in gmt_api.c and the API documentation. In short, these cryptic codes inform external interfaces (e.g., MATLAB) what the primary and (if available) secondary inputs and outputs are and how they are provided to the module (i.e., which option). The keys may also contain various exceptions that inform us that the nature of the output may change depending on the options given (e.g., normally pscoast produces PostScript but with -M it instead produces a data set).
  5. THIS_MODULE_NEEDS is used to communicate if the module requires the -R and/or the -J options to operate and how these should be provided if missing. This setting is only consulted when the GMT_RUNMODE is set to modern. If it contains "R" then we must supply a -R option and if none is given then we look to the gmt.history for the previous setting. If "g" is given instead then we use the input grid to set -R, and if it is "d" we auto-determine the region from the input dataset(s).
  6. THIS_MODULE_OPTIONS lists all the common GMT options that this particular module accepts. To handle backwards compatibility we may (as in this example) append deprecated options via the GMT_OPT macro, and depending on the compatibility mode these are processed yielding a warning or an error.