Intersection types & type checks

CHANGELOG.md

@@ -120,6 +120,10 @@
 #### Enso Language & Runtime
 
 - [Arguments in constructor definitions may now be on their own lines][11374]
+- [Intersection types & type checks][11600]
+
+[11374]: https://github.com/enso-org/enso/pull/11374
+[11600]: https://github.com/enso-org/enso/pull/11600
 - [The `:` type operator can now be chained][11671].
 
 [11374]: https://github.com/enso-org/enso/pull/11374

docs/syntax/README.md

@@ -43,6 +43,7 @@ The various components of Enso's syntax are described below:
 - [**Functions:**](./functions.md) The syntax for writing functions in Enso.
 - [**Function Arguments:**](./function-arguments.md) The syntax for function
   arguments in Enso.
+- [**Conversions:**](./conversions.md) The syntax of special _conversion functions_ in Enso.
 - [**Field Access:**](./projections.md) The syntax for working with fields of
   data types in Enso.
 - [**Comments:**](./comments.md) The syntax for writing comments in Enso.

docs/syntax/conversions.md

@@ -0,0 +1,35 @@
+---
+layout: developer-doc
+title: Defining Functions
+category: syntax
+tags: [syntax, functions]
+order: 10
+---
+
+# Conversions
+
+Conversions are special [functions](./functions.md) associated with a [type](../types/hierarchy.md),
+named `from` and taking single `that` argument. Following example:
+```ruby
+type Complex
+    Num re:Float im:Float
+
+Complex.from (that:Float) = Complex.Num that 0
+```
+defines type `Complex` and a **conversion** from `Float` which uses the provided `Float` value as
+real part of a complex number while setting the imaginary part to zero.
+
+## Type Checks
+
+Conversions are integral part of [type checking](../types/inference-and-checking.md#type-checking-algorithm)
+during runtime. Having the right conversion in scope one can write:
+```ruby
+complex_pi = 3.14:Complex
+```
+to create a new instance of type `Complex`. The Enso runtime represents
+the `3.14` literal as `Float` value and that would fail the `Complex` type check if there was no
+conversion method available. However as there is one, the runtime uses `Complex.from` behind the
+scene and `complex_pi` then becomes `Complex.Num 3.14 0` value.
+
+Type checks may perform no, one or multiple conversions (like in case of 
+[intersection types](../types/intersection-types.md)).

docs/types/README.md

@@ -48,6 +48,7 @@ Information on the type system is broken up into the following sections:
 - [**Goals for the Type System:**](./goals.md) The goals for the Enso type
   system, particularly around usability and user experience.
 - [**The Type Hierarchy:**](./hierarchy.md) The type hierarchy in Enso.
+- [**Intersection Types:**](./intersection-types.md) intersection types in Enso.
 - [**Function Types:**](./function-types.md) Function types in Enso.
 - [**Access Modification:**](./access-modifiers.md) Access modifiers in Enso
   (e.g. `private` and `unsafe`),

docs/types/hierarchy.md

@@ -142,7 +142,7 @@ They are as follows:
 - **Union - `|`:** This operator creates a typeset that contains the members in
   the union of its operands.
 - **Intersection - `&`:** This operator creates a typeset that contains the
-  members in the intersection of its operands.
+  members in the [intersection of its operands](./intersection-types.md).
 
 > [!WARNING]
 > These operators _don't seem to be supported_. There is no plan to

docs/types/intersection-types.md

@@ -0,0 +1,104 @@
+---
+layout: developer-doc
+title: The Enso Type Hierarchy
+category: types
+tags: [types, hierarchy, typeset]
+order: 2
+---
+
+# Intersection Types
+
+Intersection types play an important role in Enso [type hierarchy](./hierarchy.md)
+and its visual representation. Having a value that can play _multiple roles_
+at once is essential for smooth _live programming_ manipulation of such a value.
+
+Intersections types are created with the use of [`&` operator](./hierarchy.md#typeset-operators).
+In an attempt to represent `Complex` numbers (with real and imaginary component)
+one may decide to create a type that is both `Complex` and `Float` when the
+imaginary part is `0`:
+```ruby
+type Complex
+    Num re:Float im:Float
+
+    plain_or_both self = 
+        if self.im != 0 then self else
+            both = self.re : Complex&Float
+            both # value with both types: Complex and Float
+```   
+Having a value with such _intersection type_ allows the IDE to offer operations
+available on all individual types.
+
+## Creating
+
+Creating a value of _intersection types_ is as simple as performing a type check:
+```ruby
+self : Complex&Float
+```
+However such a _type check_ is closely associated with [conversions](../syntax/conversions.md).
+If the value doesn't represent all the desired types yet, then the system looks 
+for [conversion methods](../syntax/conversions.md) being available in the scope like:
+```
+Complex.from (that:Float) = Complex.Num that 0
+```
+and uses them to create all the values the _intersection type_ represents.
+
+## Narrowing Type Check
+
+When an _intersection type_ value is being downcast to _one of the types it already represents_,
+such a check is:
+- recorded for purposes of [dynamic dispatch](../types/dynamic-dispatch.md)
+- recorded for cases when the value is passed as an argument
+- however the value still keeps (internal) knowledge of all the types it represents
+
+As such a _static analysis_ knows the type a value _has been cast to_ and 
+can deduce the set of operations that can be performed with it. However, the value
+_can be cast to_ explicitly.
+
+> [!NOTE]
+> In the **object oriented terminology** we can think of
+> a type `Complex&Float` as being a subclass of `Complex` and subclass of `Float` types.
+> As such a value of type `Complex&Float` may be used wherever `Complex` or `Float` types
+> are used. Let there, for example, be a function:
+> ```ruby
+> use_complex c:Complex callback:(Any -> Any) = callback c
+> ```
+> that accepts `Complex` value and passes it back to a provided callback function.
+> It is possible to pass a value of `Complex&Float` type to such a function. Only
+> operations available on type `Complex` can be performed on value in variable `c`.
+>
+> However the `callback` function may still explicitly cast the value to `Float`.
+> E.g. the following is valid:
+> ```ruby
+> both = v : Complex&Float
+> use_complex both (v-> v:Float . sqrt)
+> ```
+> This behavior is often described as being **openness to subclasses**. E.g. the `c:Complex` 
+> check allows values with _intersection types_ that include `Complex` to pass thru with
+> all their runtime information available,
+> but one has to perform an explicit cast to extract the other types associated with 
+> such a value.
+
+This behavior allows creation of values with types like `Table&Column` to represent a table
+with a single column - something the users of visual _live programming_ environment of Enso find
+very useful.
+```ruby
+Table.join self right:Table -> Table = ...
+```
+Such a `Table&Column` value can be returned from the above `Table.join` function and while
+having only `Table` behavior by default, still being able to be explicitly casted by the visual environment
+to `Column`. 
+
+## Converting Type Check
+
+When an _intersection type_ is being checked against a type it doesn't represent,
+any of its component types can be used for [conversion](../syntax/conversions.md).
+Should there be a `Float` to `Text` conversion:
+```ruby
+Text.from (that:Float) = Float.to_text
+```
+then `Complex&Float` value `cf` can be typed as `cf:Text`. The value can also
+be converted to another _intersection type_ like `ct = cf:Complex&Text`. In such case
+it looses its `Float` type and `ct:Float` would fail.
+
+In short: when a [conversion](../syntax/conversions.md) is needed to satisfy a type check
+a new value is created to satisfy just the types requested in the check.

engine/runtime-integration-tests/src/test/java/org/enso/interpreter/node/expression/builtin/meta/TypeOfNodeMultiValueTest.java

@@ -89,15 +89,15 @@ private static void registerValue(
       var rawValue = ContextUtils.unwrapValue(ctx(), polyValue);
       var rawType = ContextUtils.unwrapValue(ctx(), t);
       if (rawType instanceof Type type) {
-        var singleMultiValue = EnsoMultiValue.create(new Type[] {type}, new Object[] {rawValue});
+        var singleMultiValue = EnsoMultiValue.create(new Type[] {type}, 1, new Object[] {rawValue});
         var n = t.getMetaSimpleName();
         data.add(new Object[] {singleMultiValue, n, 0});
         var rawInt = (Type) ContextUtils.unwrapValue(ctx(), g.typeInteger());
         var secondMultiValue =
-            EnsoMultiValue.create(new Type[] {rawInt, type}, new Object[] {5L, rawValue});
+            EnsoMultiValue.create(new Type[] {rawInt, type}, 2, new Object[] {5L, rawValue});
         data.add(new Object[] {secondMultiValue, n, 1});
         var firstMultiValue =
-            EnsoMultiValue.create(new Type[] {type, rawInt}, new Object[] {rawValue, 6L});
+            EnsoMultiValue.create(new Type[] {type, rawInt}, 2, new Object[] {rawValue, 6L});
         data.add(new Object[] {firstMultiValue, n, 0});
       } else {
         if (!t.isHostObject()) {

engine/runtime-integration-tests/src/test/java/org/enso/interpreter/node/typecheck/TypeCheckValueTest.java

@@ -0,0 +1,79 @@
+package org.enso.interpreter.node.typecheck;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+
+import com.oracle.truffle.api.CallTarget;
+import org.enso.interpreter.runtime.data.EnsoMultiValue;
+import org.enso.interpreter.runtime.data.Type;
+import org.enso.test.utils.ContextUtils;
+import org.enso.test.utils.TestRootNode;
+import org.graalvm.polyglot.Context;
+import org.junit.AfterClass;
+import org.junit.Test;
+
+public class TypeCheckValueTest {
+  private static Context ctx;
+
+  private static Context ctx() {
+    if (ctx == null) {
+      ctx = ContextUtils.defaultContextBuilder().build();
+    }
+    return ctx;
+  }
+
+  @AfterClass
+  public static void closeCtx() {
+    if (ctx != null) {
+      ctx.close();
+    }
+    ctx = null;
+  }
+
+  @Test
+  public void avoidDoubleWrappingOfEnsoMultiValue() {
+    var convert = allOfIntegerAndText();
+
+    ContextUtils.executeInContext(
+        ctx(),
+        () -> {
+          var builtins = ContextUtils.leakContext(ctx).getBuiltins();
+          var m1 =
+              EnsoMultiValue.create(
+                  new Type[] {builtins.text(), builtins.number().getInteger()},
+                  2,
+                  new Object[] {"Hi", 42});
+          assertEquals("Text & Integer", m1.toDisplayString(true));
+
+          var res = convert.call(m1);
+          assertTrue("Got multivalue again", res instanceof EnsoMultiValue);
+          var emv = (EnsoMultiValue) res;
+
+          assertEquals("Integer & Text", emv.toDisplayString(true));
+          return null;
+        });
+  }
+
+  private static CallTarget allOfIntegerAndText() {
+    var call = new CallTarget[1];
+    ContextUtils.executeInContext(
+        ctx(),
+        () -> {
+          var builtins = ContextUtils.leakContext(ctx).getBuiltins();
+          var intNode = TypeCheckValueNode.single("int", builtins.number().getInteger());
+          var textNode = TypeCheckValueNode.single("text", builtins.text());
+          var bothNode = TypeCheckValueNode.allOf("int&text", intNode, textNode);
+          var root =
+              new TestRootNode(
+                  (frame) -> {
+                    var arg = frame.getArguments()[0];
+                    var res = bothNode.handleCheckOrConversion(frame, arg, null);
+                    return res;
+                  });
+          root.insertChildren(bothNode);
+          call[0] = root.getCallTarget();
+          return null;
+        });
+    return call[0];
+  }
+}

engine/runtime-integration-tests/src/test/java/org/enso/interpreter/test/EnsoMultiValueInteropTest.java

@@ -0,0 +1,83 @@
+package org.enso.interpreter.test;
+
+import com.oracle.truffle.api.interop.InteropLibrary;
+import java.util.ArrayList;
+import org.enso.interpreter.runtime.data.EnsoMultiValue;
+import org.enso.interpreter.runtime.data.Type;
+import org.enso.test.utils.ContextUtils;
+import org.graalvm.polyglot.Context;
+import org.graalvm.polyglot.Value;
+import org.junit.AfterClass;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.Parameterized;
+
+@RunWith(Parameterized.class)
+public class EnsoMultiValueInteropTest {
+
+  @Parameterized.Parameter(0)
+  public Object value;
+
+  private static Context ctx;
+
+  private static Context ctx() {
+    if (ctx == null) {
+      ctx = ContextUtils.defaultContextBuilder().build();
+    }
+    return ctx;
+  }
+
+  @Parameterized.Parameters
+  public static Object[][] allEnsoMultiValuePairs() throws Exception {
+    var g = ValuesGenerator.create(ctx());
+    var typeOf =
+        ContextUtils.evalModule(
+            ctx(),
+            """
+    from Standard.Base import all
+
+    typ obj = Meta.type_of obj
+    main = typ
+    """);
+    var data = new ArrayList<Object[]>();
+    for (var v1 : g.allValues()) {
+      for (var v2 : g.allValues()) {
+        registerValue(g, typeOf, v1, v2, data);
+      }
+    }
+    return data.toArray(new Object[0][]);
+  }
+
+  private static void registerValue(
+      ValuesGenerator g, Value typeOf, Value v1, Value v2, ArrayList<Object[]> data) {
+    var t1 = typeOf.execute(v1);
+    var t2 = typeOf.execute(v2);
+    if (!t1.isNull() && !t2.isNull()) {
+      var rawT1 = ContextUtils.unwrapValue(ctx(), t1);
+      var rawT2 = ContextUtils.unwrapValue(ctx(), t2);
+      if (rawT1 instanceof Type typ1 && rawT2 instanceof Type typ2) {
+        var r1 = ContextUtils.unwrapValue(ctx, v1);
+        var r2 = ContextUtils.unwrapValue(ctx, v2);
+        var both = EnsoMultiValue.create(new Type[] {typ1, typ2}, 2, new Object[] {r1, r2});
+        data.add(new Object[] {both});
+      }
+    }
+  }
+
+  @AfterClass
+  public static void disposeCtx() throws Exception {
+    if (ctx != null) {
+      ctx.close();
+      ctx = null;
+    }
+  }
+
+  @Test
+  public void isStringDoesntFail() {
+    ContextUtils.executeInContext(
+        ctx,
+        () -> {
+          return InteropLibrary.getUncached().isString(value);
+        });
+  }
+}