Let pscoast -E accept reading other DCW type files made by users. (#8546

)

In GMT.jl I added a function that reads an OGR file containing country borders and attributes describing each country polygon with 2 or 3 chars ISO codes and create a file with the same structure as the dcw-gmt.nc file.

That file can then be read by pscoast via -E like the official DCW file. In order to do it the +f<file> modifier was added.

Besides that, this PR adds also the _continent_ **WD**  to mean the entire world.

doc/rst/source/coast.rst

@@ -111,7 +111,7 @@ Optional Arguments
 
 .. _-E:
 
-**-E**\ *code1,code2,...*\ [**+l**\|\ **L**\|\ **n**][**+c**\|\ **C**][**+e**][**+g**\ *fill*][**+p**\ *pen*][**+r**][**+R**][**+z**]
+**-E**\ *code1,code2,...*\ [**+f**\ *file*][**+l**\|\ **L**\|\ **n**][**+c**\|\ **C**][**+e**][**+g**\ *fill*][**+p**\ *pen*][**+r**][**+R**][**+z**]
     Select painting, clipping or dumping country polygons from the Digital Chart of the World (DCW).
     This is another dataset independent of GSHHG and hence the |-A| and |-D| options do not apply. The following codes
     are supported:
@@ -121,15 +121,19 @@ Optional Arguments
       (e.g., NO for Norway) or the full country name (e.g., Norway). Append .\ *state* to a country code to select a
       state of a country (if available), e.g., US.TX for Texas.
     - Append =\ *continent* to specify a continent, using the abbreviations AF (Africa),
-      AN (Antarctica), AS (Asia), EU (Europe), OC (Oceania), NA (North America), or SA (South America).
+      AN (Antarctica), AS (Asia), EU (Europe), OC (Oceania), NA (North America), SA (South America) or WD (World).
     - To specify a :ref:`DCW collection <dcw-collections>` or named region, give either the code or the full name.
 
     The following modifiers are supported:
 
+    - **+f**\ *file* to indicate that we want to use another netCDF file than the default DCW file. *file*, without extension,
+      can be either just the absolute file name, case in which the `file.nc` is expected to be found in the
+      shared folder that also contains the `dcw-gmt.nc` file, or the full file name, case in which the `file`
+      can be located anywhere.
     - **+l** to just list the countries and their codes (no data extraction or plotting takes place).
     - **+L** to see states/territories for Argentina, Australia, Brazil, Canada, China, India, Norway, Russia and the US.
-    - **+l**\|\ **+L** to **-E**\ =\ *continent* or **-E**\ *code* to only list countries or states in that continent or country, respectively;
-      repeat if more than one continent or country is requested.
+    - **+l**\|\ **+L** to **-E**\ =\ *continent* or **-E**\ *code* to only list countries or states in that continent
+      or country, respectively; repeat if more than one continent or country is requested.
     - **+n** to list the named :ref:`DCW collections <dcw-collections>` or regions (**-E**\ *code*\ **+n** will list
       collections that contains the listed codes). All names are case-insensitive.
     - **+c** to set up an inside clip path based on your selection.

src/gmt_dcw.h

@@ -31,7 +31,7 @@
 #ifndef GMT_DCW_H
 #define GMT_DCW_H
 
-#define DCW_OPT "<code1,code2,...>[+l|L|n][+c|C][+g<fill>][+p<pen>][+z]"
+#define DCW_OPT "<code1,code2,...>[+f<file>][+l|L|n][+c|C][+g<fill>][+p<pen>][+z]"
 
 enum GMT_DCW_modes {
 	GMT_DCW_REGION	 = 1,
@@ -57,15 +57,16 @@ struct GMT_DCW_SELECT {	/* -F<DWC-options> */
 	unsigned int adjust;		/* Round/adjust the region from polygons using the incs */
 	unsigned int mode;	/* 1 get countries, 2 get countries and states */
 	unsigned int n_items;	/* Number of items (times) -F was given */
+	char *other_dcw_file;		/* Name of alternative dcw file (NULL if not used) */
 	struct GMT_DCW_ITEM **item;	/* Pointer to array of n_items items */
 	struct GMT_OPTION *options;	/* Pointer to the GMT options */
 };
 
-EXTERN_MSC int gmt_DCW_version (struct GMTAPI_CTRL *API, char *version);
-EXTERN_MSC unsigned int gmt_DCW_list (struct GMT_CTRL *GMT, struct GMT_DCW_SELECT *F);
-EXTERN_MSC unsigned int gmt_DCW_parse (struct GMT_CTRL *GMT, char option, char *args, struct GMT_DCW_SELECT *F);
-EXTERN_MSC void gmt_DCW_option (struct GMTAPI_CTRL *API, char option, unsigned int plot);
-EXTERN_MSC struct GMT_DATASET * gmt_DCW_operation (struct GMT_CTRL *GMT, struct GMT_DCW_SELECT *F, double wesn[], unsigned int mode);
-EXTERN_MSC void gmt_DCW_free (struct GMT_CTRL *GMT, struct GMT_DCW_SELECT *F);
+EXTERN_MSC int gmt_DCW_version(struct GMTAPI_CTRL *API, char *version);
+EXTERN_MSC unsigned int gmt_DCW_list(struct GMT_CTRL *GMT, struct GMT_DCW_SELECT *F);
+EXTERN_MSC unsigned int gmt_DCW_parse(struct GMT_CTRL *GMT, char option, char *args, struct GMT_DCW_SELECT *F);
+EXTERN_MSC void gmt_DCW_option(struct GMTAPI_CTRL *API, char option, unsigned int plot);
+EXTERN_MSC struct GMT_DATASET *gmt_DCW_operation(struct GMT_CTRL *GMT, struct GMT_DCW_SELECT *F, double wesn[], unsigned int mode);
+EXTERN_MSC void gmt_DCW_free(struct GMT_CTRL *GMT, struct GMT_DCW_SELECT *F);
 
 #endif /* GMT_DCW_H */

src/gmt_init.c

@@ -15125,7 +15125,7 @@ GMT_LOCAL unsigned int gmtinit_strip_R_from_E_in_pscoast (struct GMT_CTRL *GMT,
 		if (c) {	/* Now process the modifiers */
 			c[0] = '+';	/* Unhide the modifiers */
 			pos = 0;	/* Initialize position counter for this string */
-			while (gmt_getmodopt (GMT, 'E', c, "lLncCgprRwz", &pos, p, &n_errors) && n_errors == 0) {
+			while (gmt_getmodopt (GMT, 'E', c, "flLncCgprRwz", &pos, p, &n_errors) && n_errors == 0) {
 				switch (p[0]) {
 					case 'r': case 'R':
 						if (r_opt[0] == 0) {	/* Only set this once */

src/gmt_private.h

@@ -185,16 +185,16 @@ struct GMTAPI_CTRL {
 	char *session_dir;			/* GMT Session dir (NULL if not running in modern mode) */
 	char *gwf_dir;				/* GMT WorkFlow dir (NULL if not running in modern mode) */
 	char **tmp_header;			/* Temporary table headers held until we are able to write them to destination */
-	char *tmp_segmentheader;		/* Temporary segment header held until we are able to write it to destination */
+	char *tmp_segmentheader;	/* Temporary segment header held until we are able to write it to destination */
 	char *message;				/* To be allocated by Create_Session and used for messages */
-	char error_msg[4096];			/* The cached last error message */
+	char error_msg[4096];		/* The cached last error message */
 	bool internal;				/* true if session was initiated by gmt.c */
 	bool deep_debug;			/* temporary for debugging */
 	bool parker_fft_default;	/* Used to alter the default in -N FFT settings */
 	int (*print_func) (FILE *, const char *);	/* Pointer to fprintf function (may be reset by external APIs like MEX) */
-	unsigned int do_not_exit;		/* 0 by default, meaning it is OK to call exit  (may be reset by external APIs like MEX to call return instead) */
-	struct GMT_LIBINFO *lib;		/* List of shared libs to consider */
-	unsigned int n_shared_libs;		/* How many in lib */
+	unsigned int do_not_exit;	/* 0 by default, meaning it is OK to call exit  (may be reset by external APIs like MEX to call return instead) */
+	struct GMT_LIBINFO *lib;	/* List of shared libs to consider */
+	unsigned int n_shared_libs;	/* How many in lib */
 	/* Items used by GMT_Put_Record and sub-functions */
 	int (*api_put_record) (struct GMTAPI_CTRL *API, unsigned int, struct GMT_RECORD *);
 	/*   Items used by api_put_record_fp */
@@ -211,7 +211,7 @@ struct GMTAPI_CTRL {
 	struct GMT_VECTOR *current_put_V;
 	GMT_putfunction *current_put_V_val;
 	/* Items used by GMT_Put_Record and sub-functions */
-	struct GMT_RECORD * (*api_get_record) (struct GMTAPI_CTRL *, unsigned int, int *);
+	struct GMT_RECORD *(*api_get_record) (struct GMTAPI_CTRL *, unsigned int, int *);
 	struct GMTAPI_DATA_OBJECT *current_get_obj;
 	bool get_next_record;
 	/*   Items used by api_get_record_dataset */

src/gmt_shore.c

@@ -597,8 +597,8 @@ int gmt_init_shore (struct GMT_CTRL *GMT, char res, struct GMT_SHORE *c, double
 	if (!gmtshore_getpathname (GMT, stem, path, true, true))
 		return (GMT_GRDIO_FILE_NOT_FOUND); /* Failed to find file */
 
-		/* zap structure (nc_get_att_text does not null-terminate strings!) */
-		gmt_M_memset (c, 1, struct GMT_SHORE);
+	/* zap structure (nc_get_att_text does not null-terminate strings!) */
+	gmt_M_memset(c, 1, struct GMT_SHORE);
 
 	/* Open shoreline file */
 	gmt_M_err_trap (gmt_nc_open (GMT, path, NC_NOWRITE, &c->cdfid));

src/gmt_support.c

@@ -7368,12 +7368,12 @@ bool gmt_getpen (struct GMT_CTRL *GMT, char *buffer, struct GMT_PEN *P) {
 	bool set_NaN = false;
 	char def_width[GMT_LEN256] = {""}, width[GMT_LEN256] = {""}, color[GMT_LEN256] = {""}, style[GMT_LEN256] = {""}, line[GMT_BUFSIZ] = {""}, *c = NULL;
 
-	if (!buffer || !buffer[0]) return (false);		/* Nothing given: return silently, leaving P in tact */
+	if (!buffer || !buffer[0]) return (false);		/* Nothing given: return silently, leaving P intact */
 	assert (P);	/* P needs to not point to NULL */
 
 	strncpy (line, buffer, GMT_BUFSIZ-1);	/* Work on a copy of the arguments */
 	gmt_chop (line);	/* Remove trailing CR, LF and properly NULL-terminate the string */
-	if (!line[0]) return (false);		/* Nothing given: return silently, leaving P in tact */
+	if (!line[0]) return (false);		/* Nothing given: return silently, leaving P intact */
 
 	/* First chop off and processes any line modifiers :
 	 * +c[l|f] : Determine how a CPT (-C) affects pen and fill colors normally controlled via -W.