Convert Fortran interface binding file to JSON

Signed-off-by: Jake Tronge <jtronge@lanl.gov>

Author: jtronge

docs/developers/bindings.rst

@@ -69,23 +69,47 @@ generated file name must be of the form ``generated_${basename}.c``, where
 Fortran Bindings
 ----------------
 
-Adding a new Fortran binding may be as simple as adding an additional prototype
-to ``ompi/mpi/fortran/use-mpi-f08/interface.in``, as long as all the required
-types are already supported by the binding code. Below is an example prototype
-for ``MPI_Waitall``:
+To add a new Fortran binding, or update an existing one, one will need to
+modify the ``ompi/mpi/fortran/use-mpi-f08/interface.json`` file; this JSON file
+contains a list of prototype objects, including information about their name
+and each parameter passed. Below is an example for ``MPI_Waitall``:
 
 .. code-block::
 
-    .waitall(SHORTCUT_COUNT count, REQUEST_ARRAY array_of_requests[count=count],
-             STATUS_ARRAY array_of_statuses[count=count])
+    {
+        "name": "waitall",
+        "parameters": [
+            {
+                "type": "SHORTCUT_COUNT",
+                "name": "count"
+            },
+            {
+                "type": "REQUEST_ARRAY",
+                "name": "array_of_requests",
+                "dep_params": {
+                    "count": "count"
+                }
+            },
+            {
+                "type": "STATUS_ARRAY",
+                "name": "array_of_statuses",
+                "dep_params": {
+                    "count": "count"
+                }
+            }
+        ]
+    }
 
-First, notice that the function name is listed with the ``MPI_`` prefix removed
-and in all lowercase along with a ``.`` before the name---this makes it easier
-to delimit prototypes across multiple lines. Parameters are listed in a
-simplified ``TYPE NAME`` form, with an optional ``[key=value;...]`` attribute
-coming after if required for the specific type. This key-value attribute is
-used to specify dependencies betwen parameters, where the key is validated by
-the type and the value must be the name of another parameter.
+This object includes two properties: the ``name`` property holding the
+subroutine name, converted to lowercase and the ``mpi_`` prefix removed; and
+the ``parameters`` property describing all parameters, their types and
+dependencies. Some parameters may depend on other types and this is listed in
+the ``dep_params`` field. An example of this can be seen with
+``array_of_requests`` above, in which ``dep_params`` holds a key-value pair
+``"count": "count"``, where the key ``count`` corresponds to a key required by
+the ``REQUEST_ARRAY`` type and the value ``count`` to the name of another
+parameter. These parameter dependencies are specific to the types used and are
+validated by the binding scripts.
 
 The Fortran binding code not only generates Fortran, but also additional
 wrapping C code that calls into the C bindings, making conversions and checking

ompi/mpi/bindings/bindings.py

@@ -32,7 +32,7 @@ def main():
     # Fortran set up code
     parser_fortran = subparsers.add_parser('fortran', help='subcommand for generating Fortran code')
     parser_fortran.add_argument('--ts', action='store_true', help='generate bindings w/o TS 29113 support')
-    parser_fortran.add_argument('--template', required=True, help='template file to use')
+    parser_fortran.add_argument('--prototypes', required=True, help='JSON prototype file to use')
     subparsers_fortran = parser_fortran.add_subparsers()
     # Handler for generating actual code
     parser_code = subparsers_fortran.add_parser('code', help='generate binding code')

ompi/mpi/bindings/ompi_bindings/fortran.py

@@ -15,104 +15,36 @@
 listed.
 """
 from collections import namedtuple
+import json
 import re
 from ompi_bindings import compiler, consts, util
 from ompi_bindings.fortran_type import FortranType
 
 
 FortranParameter = namedtuple('FortranParameter', ['type_name', 'name', 'dep_params'])
-FortranPrototype = namedtuple('FortranPrototype', ['fn_name', 'lno', 'parameters'])
-
-
-def parse_prototype(lno, line):
-    """Parse a prototype for the given line and string."""
-    if consts.PROTOTYPE_RE.match(line) is None:
-        raise util.BindingError(
-            f'Invalid function prototype for Fortran interface starting on line {lno}'
-        )
-
-    start = line.index('(')
-    end = line.index(')')
-    fn_name = line[1:start].strip()
-    parameters = line[start+1:end].split(',')
-
-    # Attempt to parse each parameter
-    parsed_parameters = []
-    try:
-        for param in parameters:
-            param = param.strip()
-            param_parts = param.split()
-            type_name = param_parts[0]
-            name = ''.join(param_parts[1:])
-            type_ = FortranType.get(type_name)
-            dep_params = None
-
-            # Check for 'param[name=param(;name=param)]' parameters,
-            # indicating a dependency on that other parameter
-            if '[' in name:
-                idx = name.index('[')
-                dep_params = [part.split('=') for part in name[idx+1:-1].split(';')]
-                dep_params = dict(dep_params)
-                name = name[:idx]
-
-            # Validate the parameter key values (or an empty list if not found)
-            type_.validate_dep_param_keys(name, [] if dep_params is None else dep_params.keys())
-
-            parsed_parameters.append(FortranParameter(type_name, name, dep_params))
-        return FortranPrototype(fn_name, lno, parsed_parameters)
-    except util.BindingError as err:
-        raise util.BindingError(
-            f'Failed to parse prototype starting on line {lno}: {err}'
-        ) from None
-    except KeyError as err:
-        raise util.BindingError(
-            f'Found invalid type starting on line {lno}: {err}'
-        ) from None
+FortranPrototype = namedtuple('FortranPrototype', ['fn_name', 'parameters'])
 
 
 def load_prototypes(fname):
-    """Load the prototypes from a file."""
+    """Load the prototypes from a JSON file."""
     with open(fname) as fp:
-        tmp_proto_string = []
-        proto_strings = []
-        cur_lno = 0
-        reading_proto = False
-
-        # The loop below is designed to read in each prototype, each delimited
-        # by a '.' preceding the name of the subroutine, allowing for the
-        # prototype to run across multiple lines.
-        for i, line in enumerate(fp):
-            lno = i + 1
-            line = line.strip()
-
-            # First strip comments
-            comm_idx = line.find('#')
-            if comm_idx != -1:
-                line = line[:comm_idx]
-            if not line:
-                continue
-
-            # Set the current line for the prototype
-            if not tmp_proto_string:
-                cur_lno = lno
-
-            # Check for initial '.' character, indicating the start of a prototype
-            reading_proto = reading_proto or line[0] == '.'
-            if line[0] == '.' and tmp_proto_string:
-                # If the buffer is not empty, then the previous prototype
-                # string is complete and can be saved
-                proto_strings.append((cur_lno, ' '.join(tmp_proto_string)))
-                cur_lno = lno
-                tmp_proto_string = []
-            # Only add the line to the current buffer if we already encountered
-            # a '.' at the start of this or a previous line
-            if reading_proto:
-                tmp_proto_string.append(line)
-
-        if tmp_proto_string:
-            proto_strings.append((cur_lno, ' '.join(tmp_proto_string)))
-
-        return [parse_prototype(lno, proto_string) for lno, proto_string in proto_strings]
+        data = json.load(fp)
+        prototypes = []
+        for proto in data:
+            fn_name = proto['name']
+            parameters = []
+            for param in proto['parameters']:
+                type_name = param['type']
+                type_ = FortranType.get(type_name)
+                param_name = param['name']
+                dep_params = param['dep_params'] if 'dep_params' in param else None
+                try:
+                    type_.validate_dep_param_keys(param_name, [] if dep_params is None else dep_params.keys())
+                except util.BindingError as err:
+                    raise util.BindingError(f'Invalid prototype "{fn_name}": {err}') from None
+                parameters.append(FortranParameter(type_name, param_name, dep_params))
+            prototypes.append(FortranPrototype(fn_name, parameters))
+        return prototypes
 
 
 class FortranBinding:
@@ -136,13 +68,13 @@ def __init__(self, prototype, out, bigcount=False, ts=False):
             if param.dep_params is not None:
                 dep_params[param.name] = param.dep_params
         # Set dependent parameters for those that need them
-        try:
-            for name, deps in dep_params.items():
+        for name, deps in dep_params.items():
+            try:
                 param_map[name].dep_params = {key: param_map[dep_name] for key, dep_name in deps.items()}
-        except KeyError as err:
-            raise util.BindingError(
-                f'Invalid dependent type in prototype starting on line {prototype.lno}: {err}'
-            )
+            except KeyError as err:
+                raise util.BindingError(
+                    f'Invalid dependent type for parameter "{name}" (prototype "{prototype.fn_name}"): {err}'
+                ) from None
 
     def dump(self, *pargs, **kwargs):
         """Write to the output file."""
@@ -370,7 +302,7 @@ def print_binding(prototype, lang, out, bigcount=False, ts=False):
 
 def generate_code(args, out):
     """Generate binding code based on arguments."""
-    prototypes = load_prototypes(args.template)
+    prototypes = load_prototypes(args.prototypes)
     if args.lang == 'fortran':
         print_f_source_header(out)
         out.dump()
@@ -388,7 +320,7 @@ def generate_code(args, out):
 
 def generate_interface(args, out):
     """Generate the Fortran interface files."""
-    prototypes = load_prototypes(args.template)
+    prototypes = load_prototypes(args.prototypes)
     out.dump(f'! {consts.GENERATED_MESSAGE}')
     for prototype in prototypes:
         ext_name = util.ext_api_func_name(prototype.fn_name)

ompi/mpi/bindings/ompi_bindings/fortran_type.py

@@ -49,8 +49,8 @@ def validate_dep_param_keys(param_name, keys):
         """Validate the keys that are allowed to be used for a dependent param."""
         # No dependent parameters allowed by default
         if keys:
-            raise util.FortranBindingError(
-                f'Invalid keys found for parameter {param_name}: {list(keys)}'
+            raise util.BindingError(
+                f'Invalid keys found for parameter "{param_name}": {list(keys)}'
             )
 
     @property

ompi/mpi/fortran/use-mpi-f08/Makefile.am

@@ -565,23 +565,23 @@ lib@OMPI_LIBMPI_NAME@_usempif08_profile_la_FCFLAGS = \
         -DOMPI_BUILD_MPI_PROFILING=1
 
 
-# Include script and template files for ABI generation from a distribution
+# Include script and JSON file for ABI generation from a distribution
 # tarball
-EXTRA_DIST = interface.in
+EXTRA_DIST = interface.json
 
 #
 # Generate the Fortran bindings and C wrapper functions for bindings with a
 # *.in template.
 #
 
 if OMPI_GENERATE_BINDINGS
-api_f08_generated.F90: interface.in
+api_f08_generated.F90: interface.json
 	$(OMPI_V_GEN) $(PYTHON) $(top_srcdir)/ompi/mpi/bindings/bindings.py \
 	    --builddir $(abs_top_builddir) \
 	    --srcdir $(abs_top_srcdir) \
 	    --output $(abs_builddir)/$@ \
 	    fortran \
-	    --template $(abs_srcdir)/$< \
+	    --prototypes $(abs_srcdir)/$< \
 	    code \
 	    fortran
 

ompi/mpi/fortran/use-mpi-f08/base/Makefile.am

@@ -49,24 +49,24 @@ endif
 # binding scripts in order to generate the specific version for their compiler.
 #
 if OMPI_GENERATE_BINDINGS
-api_f08_generated.c: ../interface.in
+api_f08_generated.c: ../interface.json
 	$(OMPI_V_GEN) $(PYTHON) $(top_srcdir)/ompi/mpi/bindings/bindings.py \
 	    --builddir $(abs_top_builddir) \
 	    --srcdir $(abs_top_srcdir) \
 	    --output $(abs_builddir)/$@ \
 	    fortran \
-	    --template $(abs_srcdir)/$< \
+	    --prototypes $(abs_srcdir)/$< \
 	    code \
 	    c
 
-api_f08_ts_generated.c: ../interface.in
+api_f08_ts_generated.c: ../interface.json
 	$(OMPI_V_GEN) $(PYTHON) $(top_srcdir)/ompi/mpi/bindings/bindings.py \
 	    --builddir $(abs_top_builddir) \
 	    --srcdir $(abs_top_srcdir) \
 	    --output $(abs_builddir)/$@ \
 	    fortran \
 	    --ts \
-	    --template $(abs_srcdir)/$< \
+	    --prototypes $(abs_srcdir)/$< \
 	    code \
 	    c