GDExtension: Store source of gdextension_interface.h in JSON

core/extension/make_interface_header.py

@@ -0,0 +1,306 @@
+import difflib
+import json
+from collections import OrderedDict
+
+import methods
+
+BASE_TYPES = [
+    "void",
+    "int",
+    "int8_t",
+    "uint8_t",
+    "int16_t",
+    "uint16_t",
+    "int32_t",
+    "uint32_t",
+    "int64_t",
+    "uint64_t",
+    "size_t",
+    "char",
+    "char16_t",
+    "char32_t",
+    "wchar_t",
+    "float",
+    "double",
+]
+
+
+def run(target, source, env):
+    filename = str(source[0])
+    buffer = methods.get_buffer(filename)
+    data = json.loads(buffer, object_pairs_hook=OrderedDict)
+    check_formatting(buffer.decode("utf-8"), data, filename)
+    check_allowed_keys(data, ["_copyright", "$schema", "format_version", "types", "interface"])
+
+    valid_data_types = {}
+    for type in BASE_TYPES:
+        valid_data_types[type] = True
+
+    with methods.generated_wrapper(str(target[0])) as file:
+        file.write("""\
+#ifndef __cplusplus
+#include <stddef.h>
+#include <stdint.h>
+
+typedef uint32_t char32_t;
+typedef uint16_t char16_t;
+#else
+#include <cstddef>
+#include <cstdint>
+
+extern "C" {
+#endif
+
+""")
+
+        handles = []
+        for type in data["types"]:
+            kind = type["kind"]
+
+            check_type(kind, type, valid_data_types)
+            valid_data_types[type["name"]] = True
+
+            if "description" in type:
+                write_doc(file, type["description"])
+
+            if kind == "handle":
+                check_allowed_keys(type, ["name", "kind"], ["const", "parent", "description", "deprecated"])
+                if "parent" in type and type["parent"] not in handles:
+                    raise UnknownTypeError(type["parent"], type["name"])
+                # @todo In the future, let's write these as `struct *` so the compiler can help us with type checking.
+                type["type"] = "void*" if not type.get("const", False) else "const void*"
+                write_simple_type(file, type)
+                handles.append(type["name"])
+            elif kind == "alias":
+                check_allowed_keys(type, ["name", "kind", "type"], ["description", "deprecated"])
+                write_simple_type(file, type)
+            elif kind == "enum":
+                check_allowed_keys(type, ["name", "kind", "values"], ["description", "deprecated"])
+                write_enum_type(file, type)
+            elif kind == "function":
+                check_allowed_keys(type, ["name", "kind", "return_value", "arguments"], ["description", "deprecated"])
+                write_function_type(file, type)
+            elif kind == "struct":
+                check_allowed_keys(type, ["name", "kind", "members"], ["description", "deprecated"])
+                write_struct_type(file, type)
+            else:
+                raise Exception(f"Unknown kind of type: {kind}")
+
+        for interface in data["interface"]:
+            check_type("function", interface, valid_data_types)
+            check_allowed_keys(
+                interface,
+                ["name", "return_value", "arguments", "since", "description"],
+                ["see", "legacy_type_name", "deprecated"],
+            )
+            write_interface(file, interface)
+
+        file.write("""\
+#ifdef __cplusplus
+}
+#endif
+""")
+
+
+# Serialize back into JSON in order to see if the formatting remains the same.
+def check_formatting(buffer, data, filename):
+    buffer2 = json.dumps(data, indent=4)
+
+    lines1 = buffer.splitlines()
+    lines2 = buffer2.splitlines()
+
+    diff = difflib.unified_diff(
+        lines1,
+        lines2,
+        fromfile="a/" + filename,
+        tofile="b/" + filename,
+        lineterm="",
+    )
+
+    diff = list(diff)
+    if len(diff) > 0:
+        print(" *** Apply this patch to fix: ***\n")
+        print("\n".join(diff))
+        raise Exception(f"Formatting issues in {filename}")
+
+
+def check_allowed_keys(data, required, optional=[]):
+    keys = data.keys()
+    allowed = required + optional
+    for k in keys:
+        if k not in allowed:
+            raise Exception(f"Found unknown key '{k}'")
+    for r in required:
+        if r not in keys:
+            raise Exception(f"Missing required key '{r}'")
+
+
+class UnknownTypeError(Exception):
+    def __init__(self, unknown, parent, item=None):
+        self.unknown = unknown
+        self.parent = parent
+        if item:
+            msg = f"Unknown type '{unknown}' for '{item}' used in '{parent}'"
+        else:
+            msg = f"Unknown type '{unknown}' used in '{parent}'"
+        super().__init__(msg)
+
+
+def base_type_name(type_name):
+    if type_name.startswith("const "):
+        type_name = type_name[6:]
+    if type_name.endswith("*"):
+        type_name = type_name[:-1]
+    return type_name
+
+
+def format_type_and_name(type, name=None):
+    ret = type
+    if ret[-1] == "*":
+        ret = ret[:-1] + " *"
+    if name:
+        if ret[-1] == "*":
+            ret = ret + name
+        else:
+            ret = ret + " " + name
+    return ret
+
+
+def check_type(kind, type, valid_data_types):
+    if kind == "alias":
+        if base_type_name(type["type"]) not in valid_data_types:
+            raise UnknownTypeError(type["type"], type["name"])
+    elif kind == "struct":
+        for member in type["members"]:
+            if base_type_name(member["type"]) not in valid_data_types:
+                raise UnknownTypeError(member["type"], type["name"], member["name"])
+    elif kind == "function":
+        for arg in type["arguments"]:
+            if base_type_name(arg["type"]) not in valid_data_types:
+                raise UnknownTypeError(arg["type"], type["name"], arg.get("name"))
+        if "return_value" in type:
+            if base_type_name(type["return_value"]["type"]) not in valid_data_types:
+                raise UnknownTypeError(type["return_value"]["type"], type["name"])
+
+
+def write_doc(file, doc, indent=""):
+    if len(doc) == 1:
+        file.write(f"{indent}/* {doc[0]} */\n")
+        return
+
+    first = True
+    for line in doc:
+        if first:
+            file.write(indent + "/*")
+            first = False
+        else:
+            file.write(indent + " *")
+
+        if line != "":
+            file.write(" " + line)
+        file.write("\n")
+    file.write(indent + " */\n")
+
+
+def make_deprecated_note(type):
+    if "deprecated" not in type:
+        return ""
+    return f" /* {type['deprecated']} */"
+
+
+def write_simple_type(file, type):
+    file.write(f"typedef {format_type_and_name(type['type'], type['name'])};{make_deprecated_note(type)}\n")
+
+
+def write_enum_type(file, enum):
+    file.write("typedef enum {\n")
+    for value in enum["values"]:
+        check_allowed_keys(value, ["name", "value"], ["description", "deprecated"])
+        if "description" in value:
+            write_doc(file, value["description"], "\t")
+        file.write(f"\t{value['name']} = {value['value']},\n")
+    file.write(f"}} {enum['name']};{make_deprecated_note(enum)}\n\n")
+
+
+def make_args_text(args):
+    combined = []
+    for arg in args:
+        check_allowed_keys(arg, ["type"], ["name", "description"])
+        combined.append(format_type_and_name(arg["type"], arg.get("name")))
+    return ", ".join(combined)
+
+
+def write_function_type(file, fn):
+    args_text = make_args_text(fn["arguments"]) if ("arguments" in fn) else ""
+    name_and_args = f"(*{fn['name']})({args_text})"
+    file.write(
+        f"typedef {format_type_and_name(fn['return_value']['type'], name_and_args)};{make_deprecated_note(fn)}\n"
+    )
+
+
+def write_struct_type(file, struct):
+    file.write("typedef struct {\n")
+    for member in struct["members"]:
+        check_allowed_keys(member, ["name", "type"], ["description"])
+        if "description" in member:
+            write_doc(file, member["description"], "\t")
+        file.write(f"\t{format_type_and_name(member['type'], member['name'])};\n")
+    file.write(f"}} {struct['name']};{make_deprecated_note(struct)}\n\n")
+
+
+def write_interface(file, interface):
+    doc = [
+        f"@name {interface['name']}",
+        f"@since {interface['since']}",
+    ]
+
+    if "deprecated" in interface:
+        if interface["deprecated"].lower().startswith("deprecated "):
+            parts = interface["deprecated"].split(" ", 1)
+            interface["deprecated"] = parts[1]
+        doc.append(f"@deprecated {interface['deprecated']}")
+
+    doc += [
+        "",
+        interface["description"][0],
+    ]
+
+    if len(interface["description"]) > 1:
+        doc.append("")
+        doc += interface["description"][1:]
+
+    if "arguments" in interface:
+        doc.append("")
+        for arg in interface["arguments"]:
+            if "description" not in arg:
+                raise Exception(f"Interface function {interface['name']} is missing docs for {arg['name']} argument")
+            arg_doc = " ".join(arg["description"])
+            doc.append(f"@param {arg['name']} {arg_doc}")
+
+    if "return_value" in interface and interface["return_value"]["type"] != "void":
+        if "description" not in interface["return_value"]:
+            raise Exception(f"Interface function {interface['name']} is missing docs for return value")
+        ret_doc = " ".join(interface["return_value"]["description"])
+        doc.append("")
+        doc.append(f"@return {ret_doc}")
+
+    if "see" in interface:
+        doc.append("")
+        for see in interface["see"]:
+            doc.append(f"@see {see}")
+
+    file.write("/**\n")
+    for d in doc:
+        if d != "":
+            file.write(f" * {d}\n")
+        else:
+            file.write(" *\n")
+    file.write(" */\n")
+
+    fn = interface.copy()
+    if "deprecated" in fn:
+        del fn["deprecated"]
+    fn["name"] = "GDExtensionInterface" + "".join(word.capitalize() for word in interface["name"].split("_"))
+    write_function_type(file, fn)
+
+    file.write("\n")