build_arg_string: Accept a dict containing configurable GMT parameters

Co-authored-by: Michael Grund <[email protected]>
Co-authored-by: Wei Ji <[email protected]>

Author: 3 people

pygmt/helpers/utils.py

@@ -119,16 +119,17 @@ def dummy_context(arg):
     yield arg
 
 
-def build_arg_string(kwdict, infile=None, outfile=None):
+def build_arg_string(kwdict, confdict=None, infile=None, outfile=None):
     r"""
-    Convert a dict and optional input/output files into a GMT argument string.
+    Convert keyword dictionaries and input/output files into a GMT argument
+    string.
 
     Make sure all values in ``kwdict`` have been previously converted to a
     string representation using the ``kwargs_to_strings`` decorator. The only
     exceptions are True, False and None.
 
     Any lists or tuples left will be interpreted as multiple entries for the
-    same command line argument. For example, the kwargs entry ``'B': ['xa',
+    same command line option. For example, the kwargs entry ``'B': ['xa',
     'yaf']`` will be converted to ``-Bxa -Byaf`` in the argument string.
 
     Note that spaces `` `` in arguments are converted to the equivalent octal
@@ -139,7 +140,9 @@ def build_arg_string(kwdict, infile=None, outfile=None):
     Parameters
     ----------
     kwdict : dict
-        A dict containing parsed keyword arguments.
+        A dictionary containing parsed keyword arguments.
+    confdict : dict
+        A dictionary containing configurable GMT parameters.
     infile : str or pathlib.Path
         The input file.
     outfile : str or pathlib.Path
@@ -149,8 +152,10 @@ def build_arg_string(kwdict, infile=None, outfile=None):
     -------
     args : str
         The space-delimited argument string with '-' inserted before each
-        keyword. The arguments are sorted alphabetically, with optional input
-        file at the beginning and optional output file at the end.
+        keyword, or '--' inserted before GMT configuration key-value pairs.
+        The keyword arguments are sorted alphabetically, followed by GMT
+        configuration key-value pairs, with optional input file at the
+        beginning and optional output file at the end.
 
     Examples
     --------
@@ -199,11 +204,12 @@ def build_arg_string(kwdict, infile=None, outfile=None):
     >>> print(
     ...     build_arg_string(
     ...         dict(A="0", B=True, C="rainbow"),
+    ...         confdict=dict(FORMAT_DATE_MAP="o dd"),
     ...         infile="input.txt",
     ...         outfile="output.txt",
     ...     )
     ... )
-    input.txt -A0 -B -Crainbow ->output.txt
+    input.txt -A0 -B -Crainbow --FORMAT_DATE_MAP="o dd" ->output.txt
     """
     gmt_args = []
 
@@ -227,6 +233,10 @@ def build_arg_string(kwdict, infile=None, outfile=None):
                 _value = str(kwdict[key]).replace(" ", "")
             gmt_args.append(rf"-{key}{_value}")
     gmt_args = sorted(gmt_args)
+
+    if confdict:
+        gmt_args.extend(f'--{key}="{value}"' for key, value in confdict.items())
+
     if infile:
         gmt_args = [str(infile)] + gmt_args
     if outfile: