Add Java APIs for polymorphic datatypes (#8438)

* Initial plan

* Add Java APIs for polymorphic datatypes and type variables

Co-authored-by: NikolajBjorner <3085284+NikolajBjorner@users.noreply.github.com>

* Fix code review issue and add documentation

Co-authored-by: NikolajBjorner <3085284+NikolajBjorner@users.noreply.github.com>

* Add TypeVarSort.java to CMakeLists.txt for Java bindings

The CMake build was failing because TypeVarSort.java was not included in the Z3_JAVA_JAR_SOURCE_FILES list in src/api/java/CMakeLists.txt. Added it in alphabetical order between TupleSort.java and UninterpretedSort.java.

Co-authored-by: NikolajBjorner <3085284+NikolajBjorner@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: NikolajBjorner <3085284+NikolajBjorner@users.noreply.github.com>

src/api/java/CMakeLists.txt

@@ -158,6 +158,7 @@ set(Z3_JAVA_JAR_SOURCE_FILES
   Symbol.java
   Tactic.java
   TupleSort.java
+  TypeVarSort.java
   UninterpretedSort.java
   UserPropagatorBase.java
   Version.java

src/api/java/Context.java

@@ -473,6 +473,88 @@ public class Context implements AutoCloseable {
         return mkDatatypeSorts(mkSymbols(names), c);
     }
 
+    /**
+     * Create a type variable for use in polymorphic functions and datatypes.
+     * Type variables can be used as sort parameters in polymorphic datatypes.
+     * @param name name of the type variable
+     * @return a new type variable sort
+     **/
+    public TypeVarSort mkTypeVariable(Symbol name)
+    {
+        checkContextMatch(name);
+        return new TypeVarSort(this, name);
+    }
+
+    /**
+     * Create a type variable for use in polymorphic functions and datatypes.
+     * Type variables can be used as sort parameters in polymorphic datatypes.
+     * @param name name of the type variable
+     * @return a new type variable sort
+     **/
+    public TypeVarSort mkTypeVariable(String name)
+    {
+        return mkTypeVariable(mkSymbol(name));
+    }
+
+    /**
+     * Create a polymorphic (parametric) datatype sort.
+     * A polymorphic datatype is parameterized by type variables, allowing it to
+     * work with different types. This is similar to generic types in programming languages.
+     * 
+     * @param name name of the datatype sort
+     * @param parameters array of type variable sorts to parameterize the datatype
+     * @param constructors array of constructor specifications
+     * @return a new polymorphic datatype sort
+     * 
+     * Example:
+     * <pre>
+     * // Create a polymorphic List datatype: List[T]
+     * TypeVarSort T = ctx.mkTypeVariable("T");
+     * Constructor&lt;Object&gt; nil = ctx.mkConstructor("nil", "is_nil", null, null, null);
+     * Constructor&lt;Object&gt; cons = ctx.mkConstructor("cons", "is_cons",
+     *     new String[]{"head", "tail"},
+     *     new Sort[]{T, null}, // head has type T, tail is recursive reference
+     *     new int[]{0, 0}); // sortRef 0 refers back to List[T]
+     * DatatypeSort&lt;Object&gt; listSort = ctx.mkPolymorphicDatatypeSort("List",
+     *     new Sort[]{T}, new Constructor[]{nil, cons});
+     * </pre>
+     **/
+    public <R> DatatypeSort<R> mkPolymorphicDatatypeSort(Symbol name, Sort[] parameters, Constructor<R>[] constructors)
+    {
+        checkContextMatch(name);
+        checkContextMatch(parameters);
+        checkContextMatch(constructors);
+        
+        int numParams = parameters.length;
+        long[] paramsNative = AST.arrayToNative(parameters);
+        
+        int numConstructors = constructors.length;
+        long[] constructorsNative = new long[numConstructors];
+        for (int i = 0; i < numConstructors; i++) {
+            constructorsNative[i] = constructors[i].getNativeObject();
+        }
+        
+        long nativeSort = Native.mkPolymorphicDatatype(nCtx(), name.getNativeObject(),
+                numParams, paramsNative, numConstructors, constructorsNative);
+        
+        return new DatatypeSort<>(this, nativeSort);
+    }
+
+    /**
+     * Create a polymorphic (parametric) datatype sort.
+     * A polymorphic datatype is parameterized by type variables, allowing it to
+     * work with different types. This is similar to generic types in programming languages.
+     * 
+     * @param name name of the datatype sort
+     * @param parameters array of type variable sorts to parameterize the datatype
+     * @param constructors array of constructor specifications
+     * @return a new polymorphic datatype sort
+     **/
+    public <R> DatatypeSort<R> mkPolymorphicDatatypeSort(String name, Sort[] parameters, Constructor<R>[] constructors)
+    {
+        return mkPolymorphicDatatypeSort(mkSymbol(name), parameters, constructors);
+    }
+
     /**
      * Update a datatype field at expression t with value v.
      * The function performs a record update at t. The field

src/api/java/TypeVarSort.java

@@ -0,0 +1,27 @@
+/**
+Copyright (c) 2024 Microsoft Corporation
+   
+Module Name:
+
+    TypeVarSort.java
+
+Abstract:
+
+Author:
+
+    GitHub Copilot 2024-01-30
+
+Notes:
+    
+**/
+
+package com.microsoft.z3;
+
+/**
+ * A type variable sort for use in polymorphic functions and datatypes.
+ **/
+public class TypeVarSort extends Sort
+{
+    TypeVarSort(Context ctx, long obj) { super(ctx, obj); }
+    TypeVarSort(Context ctx, Symbol s) { super(ctx, Native.mkTypeVariable(ctx.nCtx(), s.getNativeObject())); }
+}