Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion analysis/src/completion_decorators.ml
Original file line number Diff line number Diff line change
Expand Up @@ -271,7 +271,9 @@ You will need this decorator whenever you want to use a JSX component in ReScrip
( "instanceOf",
Some "instanceOf(\"$0\")",
[
{|The `@instanceOf` decorator states that the values of an abstract type are instances of a global JavaScript class. Such a type can be the payload of an untagged variant case, which is then recognized with `instanceof`, and is never `undefined`, like with `@notUndefined`.
{|The `@instanceOf` decorator states that the values of an abstract type are instances of a JavaScript class. Such a type can be the payload of an untagged variant case, which is then recognized with `instanceof`, and is never `undefined`, like with `@notUndefined`.

With `@module("m")`, the class is the one the module `m` exports under that name, `"default"` for its default export, imported like with a `@module` external. `@scope` reads the class through the given properties, like for an external.

A private abbreviation of another annotated type declares a subclass. A case of the superclass then excludes the instances of a subclass that is a case too, whatever the order of the cases.

Expand All @@ -282,6 +284,9 @@ type blob

@instanceOf("File")
type file = private blob

@module("three") @instanceOf("Mesh")
type mesh
```|};
] );
( "typeOf",
Expand Down
4 changes: 4 additions & 0 deletions changes/instance-of-module.fix.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
- Read the class of an `@instanceOf` type from its module with `@module("m")`,
importing it as a `@module` external does, and through the properties of
`@scope`. Both were silently ignored, so the check read a global of the
class's name.
2 changes: 2 additions & 0 deletions changes/module-scope-need-instance-of.breaking.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
- `@module` and `@scope` on a type declaration without `@instanceOf` are an
error. They had no effect there; remove them.
19 changes: 2 additions & 17 deletions compiler/core/js_exp_make.ml
Original file line number Diff line number Diff line change
Expand Up @@ -1418,19 +1418,9 @@ let literal_tag = function
| Null -> nil
| Undefined -> undefined

(* The constructor of a class at a global path such as "Intl.Locale": a
global with properties, so that a binding that shadows the global's name
is noticed. *)
let class_constructor (instance : Variant_runtime.Instance.t) =
match
String.split_on_char '.' (Variant_runtime.Instance.to_string instance)
with
| [] -> assert false
| global :: properties -> List.fold_left dot (js_global global) properties

(* The [typeof] string an untagged payload answers to, as a [switch] key.
Instances are told apart by [is_instance_of], an unknown payload is not
checked *)
Instances are told apart by [instanceof] or [Array.isArray], an unknown
payload is not checked *)
let block_type_name block_type =
match Variant_runtime.typeof_name block_type with
| Some name -> str name
Expand All @@ -1440,11 +1430,6 @@ let tag_type = function
| Variant_runtime.Literal d -> literal_tag d
| Payload_shape b -> block_type_name b

let is_instance_of (instance : Variant_runtime.Instance.t) e =
match instance with
| Array -> is_array e
| Class _ -> instanceof e (class_constructor instance)

(* Whether a value of a tagged variant is a constant rather than a block,
given the literals of its constants *)
let is_int_tag ~(literal_tags : Variant_runtime.literal_tag list) e =
Expand Down
4 changes: 2 additions & 2 deletions compiler/core/js_exp_make.mli
Original file line number Diff line number Diff line change
Expand Up @@ -160,8 +160,8 @@ val assign : t -> t -> t
val literal_tag : Variant_runtime.literal_tag -> t
val tag_type : Variant_runtime.tag_type -> t

val is_instance_of : Variant_runtime.Instance.t -> t -> t
(** [Array.isArray(e)] or [e instanceof C] *)
val instanceof : t -> t -> t
(** [e0 instanceof e1] *)

val triple_equal : ?comment:string -> t -> t -> t
(* TODO: reduce [triple_equal] use *)
Expand Down
4 changes: 3 additions & 1 deletion compiler/core/lam_compile.ml
Original file line number Diff line number Diff line change
Expand Up @@ -970,7 +970,9 @@ let compile output_prefix =
match Variant_runtime.typeof_name block_type with
| Some name -> E.string_equal (E.typeof e) (E.str name)
| None -> assert false)
| Instance instance -> E.is_instance_of instance e
| Instance Array -> E.is_array e
| Instance (Class {name}) ->
E.instanceof e (Lam_compile_external_call.class_constructor name)
| Not_null -> E.not (E.is_null e)
| Not test -> E.not (test_exp test)
| And (test1, test2) -> E.and_ (test_exp test1) (test_exp test2)
Expand Down
14 changes: 14 additions & 0 deletions compiler/core/lam_compile_external_call.ml
Original file line number Diff line number Diff line change
Expand Up @@ -290,6 +290,20 @@ let translate_scoped_module_val
let start = E.js_global x in
Ext_list.fold_left (Ext_list.append_one rest fn) start E.dot)

(* The constructor of a class, read like the value of an external: a global
path, such as "Intl.Locale", is a global with properties, so that a binding
that shadows the global's name is noticed; an export of a module is
imported as [@module] imports it. *)
let class_constructor ({module_; path} : Variant_runtime.Instance.class_name) =
let scopes, name = Ext_list.split_at_last (String.split_on_char '.' path) in
let module_name =
Option.map
(fun bundle : External_ffi_types.external_module_name ->
{bundle; module_bind_name = Phint_nothing; import_attributes = None})
module_
in
translate_scoped_module_val module_name name scopes

(* The function a JSX external refers to; [Translcore] only builds [Pjsx]
for [Decl_val] externals that aren't the module itself *)
let jsx_callee
Expand Down
4 changes: 4 additions & 0 deletions compiler/core/lam_compile_external_call.mli
Original file line number Diff line number Diff line change
Expand Up @@ -59,3 +59,7 @@ val translate_ffi :

val jsx_callee : External_ffi_types.external_decl -> J.expression
(** The function a JSX external refers to, for [J.Jsx] *)

val class_constructor : Variant_runtime.Instance.class_name -> J.expression
(** The constructor of a class, [Intl.Locale] for a global or [Three.Mesh]
for an export of a module, whose import it adds *)
48 changes: 37 additions & 11 deletions compiler/ml/UntaggedVariants.md
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,21 @@ level implying the one before:
- `@instanceOf("C")`: they are instances of the global class at the path `C`,
such as `"Date"` or `"Intl.Locale"`.

Like an external, an `@instanceOf` type can say where its class is found:
`@module("m")` reads the path among the exports of the module `m`, with
`"default"` for its default export, and imports it as a `@module` external
does, and `@scope` puts its properties in front of the path, so
`@scope("THREE") @instanceOf("Mesh")` is `@instanceOf("THREE.Mesh")`:

```rescript
@module("three") @instanceOf("Mesh") type mesh // x instanceof Three.Mesh
@module("./shapes.js") @instanceOf("default") type shape
```

On a type without `@instanceOf`, `@module` and `@scope` have no effect, so
they are errors. Before #9239 the compiler ignored them on every type without
a word, which hid that bug.

A type has at most one of the three, and only abstract types and type
abbreviations, public or private, can have one.
`@notUndefined` affects only rule 12: `option` of the type, and of an untagged
Expand Down Expand Up @@ -222,26 +237,39 @@ a locally abstract type stands for another type and does not count.
declaration is @notUndefined, but the first declaration can hold undefined".
An interface that states nothing hides the shape. The same holds for functor
arguments, `with type` constraints and module type ascriptions. Within one
variant a class is identified by its path, so two types of the same class are
one case (rule 6); across a signature the two declarations must also state
the same superclasses.
variant a class is identified by its path and its module, so two types of the
same class are one case (rule 6), while a global `Mesh` and the `Mesh` that
`"three"` exports are two; across a signature the two declarations must also
state the same superclasses and module
(`runtime_annotation_interface_module_class.res`).

The class path is a dot-separated list of identifiers whose first one is not
a JavaScript keyword. Paths that name no class to recognize values by are
a JavaScript keyword. In a module, the path names an export, which can be
named like a keyword and can be any class, so none of the global paths below
is rejected there. Paths that name no class to recognize values by are
rejected as well:

| Path | Error | Fixture |
| --- | --- | --- |
| not a path, or a keyword global | @instanceOf expects the name of a global class ... | `instance_of_invalid_class.res`, `instance_of_keyword.res` |
| not a string, not a path, or a keyword global | @instanceOf expects the name of a global class ... | `instance_of_invalid_class.res`, `instance_of_keyword.res`, `instance_of_not_string.res` |
| `globalThis.C` | Write @instanceOf("C") without "globalThis." ... | `instance_of_global_this.res` |
| `Object`, `Function` | Every object is an instance of Object ... Use @typeOf("object") instead. | `instance_of_object.res` |
| `Array` | Arrays are recognized by Array.isArray ... | `instance_of_array.res` |
| `String`, `Number`, `Boolean`, `BigInt`, `Symbol` | Values of type bigint are primitives ... | `instance_of_primitive_wrapper.res` |
| `globalThis`, `undefined`, `NaN`, `Infinity`, `Math`, `JSON`, `Reflect`, `Atomics`, `Intl`, `Proxy` | Math is not a class ... | `instance_of_not_a_class.res` |
| not a path, with `@module` | @instanceOf expects the name of a class that "three" exports ... | `instance_of_module_invalid_class.res` |
| `@module` without one non-empty string, or a payload of `@instanceOf` that is not a string with `@module` | @module on an @instanceOf type expects the module that exports the class ...; @instanceOf expects the name of a class that "three" exports ... | `instance_of_module_invalid_payload.res`, `instance_of_module_empty.res`, `instance_of_module_not_string.res` |
| a `@scope` without a string or a tuple of strings, or with a property that is not an identifier | @scope on an @instanceOf type expects the properties the class is read through ... | `instance_of_invalid_scope.res`, `instance_of_scope_not_strings.res`, `instance_of_scope_without_payload.res` |
| a first `@scope` property named like a keyword, without `@module` | Without @module, the first property of @scope is a global, which cannot be named like the keyword "default". | `instance_of_scope_keyword.res` |
| a first `@scope` property `globalThis`, without `@module` | Remove "globalThis" from @scope ... | `instance_of_scope_global_this.res` |
| `@module` or `@scope` twice | Duplicate @module annotation; a type can have only one. | `instance_of_module_duplicate.res` |
| `@module` or `@scope` on a type without `@instanceOf` | @module on a type declaration names the module a class is imported from, so it needs @instanceOf ..., with what to do for an abstract type, a type with `@typeOf` or `@notUndefined`, and a record or variant | `module_without_instance_of.res`, `scope_without_instance_of.res`, `module_on_record.res` |

An unknown `typeof` is an error too (`type_of_invalid.res`). The class is read
as a global; where a local binding of the same name is in scope, it is read
through `globalThis` (#8785). The compiler trusts the annotations, as it
through `globalThis` (#8785). A class of a module is read through the module's
import, which the module that compiles the check adds, wherever the type is
declared (`untagged_module_class_test.res`). The compiler trusts the annotations, as it
trusts the type of an external: a value that is not what its type declares is
recognized by what it is (rule 10).

Expand All @@ -267,7 +295,8 @@ written (Known bugs).
`undefinedness`; `ast_untagged_variants.ml:process_runtime_annotation`,
`unsupported_class`, `check_runtime_annotation`;
`includecore.ml:compare_runtime_annotations`;
`variant_runtime.ml:Instance`; `js_exp_make.ml:class_constructor`.
`variant_runtime.ml:Instance`;
`lam_compile_external_call.ml:class_constructor`.
- Tests: `spec_test` rules 4 and 5;
`tests/tests/src/untagged_runtime_annotations_test.res`,
`untagged_runtime_annotations_shadow_test.res`,
Expand All @@ -292,7 +321,7 @@ The type checker rejects an untagged variant, with
| Condition | Reason | Fixture |
| --- | --- | --- |
| two object cases | At most one case can be an object type. | `UntaggedAtMostOneObject.res` |
| two cases of one instance class, compared by path (arrays, tuples and records represented as arrays share `Array`) | At most one case can be an instance of C; for `Array`, an array, a tuple or a record represented as an array. | `UntaggedAtMostOneInstance.res`, `UntaggedTupleAndArray.res`, `untagged_array_record_and_array.res`, `untagged_same_class_twice.res` |
| two cases of one instance class, compared by path and module (arrays, tuples and records represented as arrays share `Array`) | At most one case can be an instance of C; for `Array`, an array, a tuple or a record represented as an array. | `UntaggedAtMostOneInstance.res`, `UntaggedTupleAndArray.res`, `untagged_array_record_and_array.res`, `untagged_same_class_twice.res` |
| two function cases | At most one case can be a function type. | `UntaggedAtMostOneFunction.res` |
| two string cases | At most one case can be a string type. | `UntaggedAtMostOneString.res` |
| two number cases (`int` and `float` count together) | At most one case can be a number type (int or float). | `UntaggedAtMostOneNumber.res` |
Expand Down Expand Up @@ -621,6 +650,3 @@ had to answer, and the answers of rule 5:
and a type is never recognized by its name.
9. **Globals.** A shadowed class is read through `globalThis`. A missing
class throws when the check runs (rule 10).

Still open: a class imported from a module cannot be named, and the typed
arrays share one type (#8955).
Loading
Loading