Clarify coercion parenthesis contexts

Signed-off-by: Christoph Knittel <ck@cca.io>

Author: cknitt

CHANGELOG.md

@@ -72,7 +72,7 @@
 
 #### :nail_care: Polish
 
-- Omit unnecessary parentheses around coercions in call arguments, collection elements, and array indices while preserving expression grouping. https://github.com/rescript-lang/rescript/pull/8614
+- Omit unnecessary parentheses around coercions where the surrounding syntax already delimits the expression, while preserving required grouping. https://github.com/rescript-lang/rescript/pull/8614
 - Print external declarations in signatures and type errors with their processed attributes instead of the `"#rescript-external"` placeholder, and print inline constants using `@inline` syntax. https://github.com/rescript-lang/rescript/pull/8581
 - Improve diagnostics for dynamic imports of local values and attempts to use `import` as a first-class value. https://github.com/rescript-lang/rescript/pull/8582
 - Allow inferred labeled functions to be called with labels in any order by removing legacy curried-arrow commutation locks. https://github.com/rescript-lang/rescript/pull/8547

compiler/syntax/src/res_parens.ml

@@ -1,7 +1,7 @@
 module Parsetree_viewer = Res_parsetree_viewer
 type kind = Parenthesized | Braced of Location.t | Nothing
 
-let expr ?(allow_coercion = false) expr =
+let expr_with_coercion_kind coercion_kind expr =
   let opt_braces, _ = Parsetree_viewer.process_braces_attr expr in
   match opt_braces with
   | Some ({Location.loc = braces_loc}, _) -> Braced braces_loc
@@ -12,10 +12,13 @@ let expr ?(allow_coercion = false) expr =
        Pexp_constraint ({pexp_desc = Pexp_pack _}, {ptyp_desc = Ptyp_package _});
     } ->
       Nothing
-    | {pexp_desc = Pexp_coerce _} when allow_coercion -> Nothing
-    | {pexp_desc = Pexp_constraint _ | Pexp_coerce _} -> Parenthesized
+    | {pexp_desc = Pexp_coerce _} -> coercion_kind
+    | {pexp_desc = Pexp_constraint _} -> Parenthesized
     | _ -> Nothing)
 
+let expr expr = expr_with_coercion_kind Parenthesized expr
+let expr_allowing_coercion expr = expr_with_coercion_kind Nothing expr
+
 let expr_record_row_rhs ~optional e =
   let kind = expr e in
   match kind with

compiler/syntax/src/res_parens.mli

@@ -1,9 +1,11 @@
 type kind = Parenthesized | Braced of Location.t | Nothing
 
-(* Set [allow_coercion] to [true] only in grammar positions accepting a trailing
-   coercion without parentheses, such as call arguments and collection elements.
-   Bindings and arrow bodies require parentheses. *)
-val expr : ?allow_coercion:bool -> Parsetree.expression -> kind
+val expr : Parsetree.expression -> kind
+
+(* Unlike [expr], this does not request parentheses for a top-level coercion.
+   Use only where the surrounding grammar delimits the expression, such as call
+   arguments and collection elements. *)
+val expr_allowing_coercion : Parsetree.expression -> kind
 val structure_expr : Parsetree.expression -> kind
 
 val unary_expr_operand : Parsetree.expression -> kind

compiler/syntax/src/res_printer.ml

@@ -1716,7 +1716,7 @@ and print_spread_dict_expr ~state parts (expr : Parsetree.expression) cmt_tbl =
     in
     let spread_doc =
       let doc = print_expression ~state spread_expr cmt_tbl in
-      match Parens.expr ~allow_coercion:true spread_expr with
+      match Parens.expr_allowing_coercion spread_expr with
       | Parens.Parenthesized -> add_parens doc
       | Braced braces -> print_braces doc spread_expr braces
       | Nothing -> doc
@@ -3044,7 +3044,7 @@ and print_expression_with_comments_and_parens ~state expr cmt_tbl =
 and print_expression_args ~state (args : Parsetree.expression list) cmt_tbl =
   let print_arg expr =
     let doc = print_expression_with_comments ~state expr cmt_tbl in
-    match Parens.expr ~allow_coercion:true expr with
+    match Parens.expr_allowing_coercion expr with
     | Parens.Parenthesized -> add_parens doc
     | Braced braces -> print_braces doc expr braces
     | Nothing -> doc
@@ -3270,7 +3270,7 @@ and print_expression ~state (e : Parsetree.expression) cmt_tbl =
               Doc.line;
               Doc.dotdotdot;
               (let doc = print_expression_with_comments ~state expr cmt_tbl in
-               match Parens.expr ~allow_coercion:true expr with
+               match Parens.expr_allowing_coercion expr with
                | Parens.Parenthesized -> add_parens doc
                | Braced braces -> print_braces doc expr braces
                | Nothing -> doc);
@@ -3292,7 +3292,7 @@ and print_expression ~state (e : Parsetree.expression) cmt_tbl =
                            let doc =
                              print_expression_with_comments ~state expr cmt_tbl
                            in
-                           match Parens.expr ~allow_coercion:true expr with
+                           match Parens.expr_allowing_coercion expr with
                            | Parens.Parenthesized -> add_parens doc
                            | Braced braces -> print_braces doc expr braces
                            | Nothing -> doc)
@@ -3324,7 +3324,7 @@ and print_expression ~state (e : Parsetree.expression) cmt_tbl =
                            let doc =
                              print_expression_with_comments ~state expr cmt_tbl
                            in
-                           match Parens.expr ~allow_coercion:true expr with
+                           match Parens.expr_allowing_coercion expr with
                            | Parens.Parenthesized -> add_parens doc
                            | Braced braces -> print_braces doc expr braces
                            | Nothing -> doc)
@@ -3353,7 +3353,7 @@ and print_expression ~state (e : Parsetree.expression) cmt_tbl =
                            let doc =
                              print_expression_with_comments ~state expr cmt_tbl
                            in
-                           match Parens.expr ~allow_coercion:true expr with
+                           match Parens.expr_allowing_coercion expr with
                            | Parens.Parenthesized -> add_parens doc
                            | Braced braces -> print_braces doc expr braces
                            | Nothing -> doc)
@@ -3387,7 +3387,7 @@ and print_expression ~state (e : Parsetree.expression) cmt_tbl =
               Doc.concat
                 [
                   Doc.dotdotdot;
-                  (match Parens.expr ~allow_coercion:true expr with
+                  (match Parens.expr_allowing_coercion expr with
                   | Parens.Parenthesized -> add_parens doc
                   | Braced braces -> print_braces doc expr braces
                   | Nothing -> doc);
@@ -3737,14 +3737,10 @@ and print_expression ~state (e : Parsetree.expression) cmt_tbl =
           print_cases ~state cases cmt_tbl;
         ]
     | Pexp_coerce (expr, (), typ) ->
-      let doc_expr = print_expression_with_comments ~state expr cmt_tbl in
-      let doc_typ = print_typ_expr ~state typ cmt_tbl in
       let doc_expr =
-        match Parens.expr expr with
-        | Parens.Parenthesized -> add_parens doc_expr
-        | Braced braces -> print_braces doc_expr expr braces
-        | Nothing -> doc_expr
+        print_expression_with_comments_and_parens ~state expr cmt_tbl
       in
+      let doc_typ = print_typ_expr ~state typ cmt_tbl in
       let doc = Doc.concat [doc_expr; Doc.text " :> "; doc_typ] in
       (* Keep attributes on the coercion rather than its operand. *)
       if Parsetree_viewer.has_printable_attributes e.pexp_attributes then
@@ -4250,7 +4246,7 @@ and print_array_spread_apply ~state sub_lists cmt_tbl =
       (* Print expression without leading comments (they're already extracted) *)
       let expr_doc =
         let doc = print_expression ~state expr cmt_tbl in
-        match Parens.expr ~allow_coercion:true expr with
+        match Parens.expr_allowing_coercion expr with
         | Parens.Parenthesized -> add_parens doc
         | Braced braces -> print_braces doc expr braces
         | Nothing -> doc
@@ -4282,7 +4278,7 @@ and print_array_spread_apply ~state sub_lists cmt_tbl =
         (List.map
            (fun expr ->
              let doc = print_expression_with_comments ~state expr cmt_tbl in
-             match Parens.expr ~allow_coercion:true expr with
+             match Parens.expr_allowing_coercion expr with
              | Parens.Parenthesized -> add_parens doc
              | Braced braces -> print_braces doc expr braces
              | Nothing -> doc)
@@ -4317,7 +4313,7 @@ and print_list_spread_apply ~state sub_lists cmt_tbl =
           comma_before_spread;
           Doc.dotdotdot;
           (let doc = print_expression_with_comments ~state expr cmt_tbl in
-           match Parens.expr ~allow_coercion:true expr with
+           match Parens.expr_allowing_coercion expr with
            | Parens.Parenthesized -> add_parens doc
            | Braced braces -> print_braces doc expr braces
            | Nothing -> doc);
@@ -4338,7 +4334,7 @@ and print_list_spread_apply ~state sub_lists cmt_tbl =
           (List.map
              (fun expr ->
                let doc = print_expression_with_comments ~state expr cmt_tbl in
-               match Parens.expr ~allow_coercion:true expr with
+               match Parens.expr_allowing_coercion expr with
                | Parens.Parenthesized -> add_parens doc
                | Braced braces -> print_braces doc expr braces
                | Nothing -> doc)
@@ -4438,7 +4434,7 @@ and print_pexp_apply ~state expr cmt_tbl =
     let member =
       let member_doc =
         let doc = print_expression_with_comments ~state member_expr cmt_tbl in
-        match Parens.expr ~allow_coercion:true member_expr with
+        match Parens.expr_allowing_coercion member_expr with
         | Parens.Parenthesized -> add_parens doc
         | Braced braces -> print_braces doc member_expr braces
         | Nothing -> doc
@@ -4485,7 +4481,7 @@ and print_pexp_apply ~state expr cmt_tbl =
     let member =
       let member_doc =
         let doc = print_expression_with_comments ~state member_expr cmt_tbl in
-        match Parens.expr ~allow_coercion:true member_expr with
+        match Parens.expr_allowing_coercion member_expr with
         | Parens.Parenthesized -> add_parens doc
         | Braced braces -> print_braces doc member_expr braces
         | Nothing -> doc
@@ -5138,7 +5134,7 @@ and print_arguments ~state ~partial
   | [(Nolabel, arg)] when Parsetree_viewer.is_huggable_expression arg ->
     let arg_doc =
       let doc = print_expression_with_comments ~state arg cmt_tbl in
-      match Parens.expr ~allow_coercion:true arg with
+      match Parens.expr_allowing_coercion arg with
       | Parens.Parenthesized -> add_parens doc
       | Braced braces -> print_braces doc arg braces
       | Nothing -> doc
@@ -5252,7 +5248,7 @@ and print_argument ~state (arg_lbl, arg) cmt_tbl =
     in
     let printed_expr =
       let doc = print_expression_with_comments ~state expr cmt_tbl in
-      match Parens.expr ~allow_coercion:true expr with
+      match Parens.expr_allowing_coercion expr with
       | Parenthesized -> add_parens doc
       | Braced braces -> print_braces doc expr braces
       | Nothing -> doc

packages/dev-playground/src/UrlState.res

@@ -42,7 +42,7 @@ let applyUrlState = (~encoded, ~config: PlaygroundConfig.t) => {
     params->UrlSearchParams.delete("sourceMapSourcesContent")
     params->UrlSearchParams.delete("sourceMapRoot")
   | sourceMapMode =>
-    params->UrlSearchParams.set("sourceMap", (sourceMapMode :> string))
+    params->UrlSearchParams.set("sourceMap", sourceMapMode :> string)
     params->UrlSearchParams.set(
       "sourceMapSourcesContent",
       config.sourceMapSourcesContent ? "true" : "false",

tests/syntax_tests/data/printer/expr/coerce.res

@@ -25,7 +25,7 @@ let foo = (~a=(3:int:>int), b) => 34
 
 let x = (/* c0 */ x /* c1 */ :> /* c2 */ int /* c3 */)
 
-// Delimited arguments need no extra parentheses.
+// Delimited expression positions need no extra parentheses.
 foo(v :> b)
 foo((v :> b))
 foo(~arg=(v :> b), ~optional=?(v :> b))

tests/syntax_tests/data/printer/expr/expected/coerce.res.txt

@@ -25,7 +25,7 @@ let foo = (~a=(3: int) :> int, b) => 34
 
 let x = (/* c0 */ x /* c1 */ :> /* c2 */ int /* c3 */)
 
-// Delimited arguments need no extra parentheses.
+// Delimited expression positions need no extra parentheses.
 foo(v :> b)
 foo(v :> b)
 foo(~arg=v :> b, ~optional=?v :> b)