Allow parenthesized match patterns in string/sequence/iter captures

In unambiguous capture positions (head-tail, init-last, head-last splits),
captures can now be parenthesized match patterns like view patterns or
equality checks, e.g. `(int -> n) + "G" = "8G"`. Search split positions
(two captures) still require bare variable names.

Closes #882

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: evhub

DOCS.md

@@ -1197,6 +1197,8 @@ infix_pattern ::= bar_or_pattern ("`" EXPR "`" [EXPR])*  # infix check
 
 bar_or_pattern ::= pattern ("|" pattern)*  # match any
 
+capture ::= NAME | "(" pattern ")"  # in unambiguous capture positions
+
 base_pattern ::= (
     "(" pattern ")"                  # parentheses
     | "None" | "True" | "False"      # constants
@@ -1230,29 +1232,29 @@ base_pattern ::= (
     | [(                             # sequence splits
         "(" patterns ")"
         | "[" patterns "]"
-      ) "+"] NAME ["+" (
+      ) "+"] capture ["+" (
         "(" patterns ")"                 # this match must be the same
         | "[" patterns "]"               #  construct as the first match
-      )] ["+" NAME ["+" (
-        "(" patterns ")"                 # and same here
+      )] ["+" NAME ["+" (              # search splits require NAME
+        "(" patterns ")"                 # must be same as first match
         | "[" patterns "]"
       )]]
     | [(                             # iterable splits
         "(" patterns ")"
         | "[" patterns "]"
         | "(|" patterns "|)"
-      ) "::"] NAME ["::" (
+      ) "::"] capture ["::" (
         "(" patterns ")"
         | "[" patterns "]"
         | "(|" patterns "|)"
-      )] [ "::" NAME [
+      )] [ "::" NAME [               # search splits require NAME
         "(" patterns ")"
         | "[" patterns "]"
         | "(|" patterns "|)"
       ]]
-    | [STRING "+"] NAME              # complex string matching
+    | [STRING "+"] capture           # complex string matching
         ["+" STRING]
-        ["+" NAME ["+" STRING]]
+        ["+" NAME ["+" STRING]]      # search splits require NAME
 )
 ```
 
@@ -1287,13 +1289,13 @@ base_pattern ::= (
 - Sequence Destructuring:
   - Lists (`[<patterns>]`), Tuples (`(<patterns>)`): will only match a sequence (`collections.abc.Sequence`) of the same length, and will check the contents against `<patterns>` (Coconut automatically registers `numpy` arrays and `collections.deque` objects as sequences).
   - Lazy lists (`(|<patterns>|)`): same as list or tuple matching, but checks for an Iterable (`collections.abc.Iterable`) instead of a Sequence.
-  - Head-Tail Splits (`<list/tuple> + <var>` or `(<patterns>, *<var>)`): will match the beginning of the sequence against the `<list/tuple>`/`<patterns>`, then bind the rest to `<var>`, and make it the type of the construct used.
-  - Init-Last Splits (`<var> + <list/tuple>` or `(*<var>, <patterns>)`): exactly the same as head-tail splits, but on the end instead of the beginning of the sequence.
-  - Head-Last Splits (`<list/tuple> + <var> + <list/tuple>` or `(<patterns>, *<var>, <patterns>)`): the combination of a head-tail and an init-last split.
-  - Search Splits (`<var1> + <list/tuple> + <var2>` or `(*<var1>, <patterns>, *<var2>)`): searches for the first occurrence of the `<list/tuple>`/`<patterns>` in the sequence, then puts everything before into `<var1>` and everything after into `<var2>`.
+  - Head-Tail Splits (`<list/tuple> + <capture>` or `(<patterns>, *<var>)`): will match the beginning of the sequence against the `<list/tuple>`/`<patterns>`, then bind the rest to `<capture>`, and make it the type of the construct used. `<capture>` can be a variable name or a parenthesized match pattern (e.g. `(int -> x)`).
+  - Init-Last Splits (`<capture> + <list/tuple>` or `(*<var>, <patterns>)`): exactly the same as head-tail splits, but on the end instead of the beginning of the sequence.
+  - Head-Last Splits (`<list/tuple> + <capture> + <list/tuple>` or `(<patterns>, *<var>, <patterns>)`): the combination of a head-tail and an init-last split.
+  - Search Splits (`<var1> + <list/tuple> + <var2>` or `(*<var1>, <patterns>, *<var2>)`): searches for the first occurrence of the `<list/tuple>`/`<patterns>` in the sequence, then puts everything before into `<var1>` and everything after into `<var2>`. Search split captures must be variable names, not parenthesized patterns.
   - Head-Last Search Splits (`<list/tuple> + <var> + <list/tuple> + <var> + <list/tuple>` or `(<patterns>, *<var>, <patterns>, *<var>, <patterns>)`): the combination of a head-tail split and a search split.
-  - Iterable Splits (`<list/tuple/lazy list> :: <var> :: <list/tuple/lazy list> :: <var> :: <list/tuple/lazy list>`): same as other sequence destructuring, but works on any iterable (`collections.abc.Iterable`), including infinite iterators (note that if an iterator is matched against it will be modified unless it is [`reiterable`](#reiterable)).
-  - Complex String Matching (`<string> + <var> + <string> + <var> + <string>`): string matching supports the same destructuring options as above.
+  - Iterable Splits (`<list/tuple/lazy list> :: <capture> :: <list/tuple/lazy list> :: <var> :: <list/tuple/lazy list>`): same as other sequence destructuring, but works on any iterable (`collections.abc.Iterable`), including infinite iterators (note that if an iterator is matched against it will be modified unless it is [`reiterable`](#reiterable)).
+  - Complex String Matching (`<string> + <capture> + <string> + <var> + <string>`): string matching supports the same destructuring options as above. In unambiguous positions (single capture), `<capture>` can be a variable name or a parenthesized match pattern (e.g. `(int -> n) + "px"`).
 
 _Note: Like [iterator slicing](#iterator-slicing), iterator and lazy list matching make no guarantee that the original iterator matched against be preserved (to preserve the iterator, use Coconut's [`reiterable`](#reiterable) built-in)._
 

coconut/compiler/grammar.py

@@ -2056,6 +2056,10 @@ class Grammar(object):
         del_stmt = addspace(keyword("del") - simple_assignlist)
 
         interior_name_match = labeled_group(setname, "var")
+        interior_capture_match = (
+            interior_name_match
+            | labeled_group(lparen.suppress() + match + rparen.suppress(), "paren")
+        )
         matchlist_anon_named_tuple_item = (
             Group(Optional(dot) + unsafe_name) + equals + match
             | Group(Optional(dot) + interior_name_match) + equals
@@ -2103,18 +2107,18 @@ class Grammar(object):
         match_string = interleaved_tokenlist(
             # f_string_atom must come first
             f_string_atom("f_string") | fixed_len_string_tokens("string"),
-            interior_name_match("capture"),
+            interior_capture_match("capture"),
             plus,
             at_least_two=True,
         )("string_sequence")
         sequence_match = interleaved_tokenlist(
             (match_list | match_tuple)("literal"),
-            interior_name_match("capture"),
+            interior_capture_match("capture"),
             plus,
         )("sequence")
         iter_match = interleaved_tokenlist(
             (match_list | match_tuple | match_lazy)("literal"),
-            interior_name_match("capture"),
+            interior_capture_match("capture"),
             unsafe_dubcolon,
             at_least_two=True,
         )("iter")

coconut/compiler/matching.py

@@ -812,6 +812,8 @@ def handle_sequence(self, seq_type, seq_groups, item, iter_match=False):
                 if len(seq_groups) == 3:
                     (front_gtype, front_match), mid_group, (back_gtype, back_match) = seq_groups
                     internal_assert(front_gtype == "capture" == back_gtype, "invalid sequence match middle groups", seq_groups)
+                    if "paren" in front_match or "paren" in back_match:
+                        raise CoconutDeferredSyntaxError("parenthesized match patterns cannot be used in sequence search patterns", self.loc)
                     mid_gtype, mid_contents = mid_group
 
                     if iter_match:

coconut/root.py

@@ -26,7 +26,7 @@
 VERSION = "3.2.0"
 VERSION_NAME = None
 # False for release, int >= 1 for develop
-DEVELOP = 13
+DEVELOP = 14
 ALPHA = False  # for pre releases rather than post releases
 
 assert DEVELOP is False or DEVELOP >= 1, "DEVELOP must be False or an int >= 1"

coconut/tests/src/cocotest/agnostic/primary_2.coco

@@ -732,6 +732,22 @@ def primary_test_2() -> bool:
     assert isinstance(lazy_d, lazy_deque)
     assert issubclass(type(lazy_d), lazy_deque)
 
+    # Issue #882: parenthesized match patterns in string captures
+    (int -> n882) + "G" = "8G"
+    assert n882 == 8
+    "G" + (int -> n882b) = "G8"
+    assert n882b == 8
+    "[" + (int -> n882c) + "]" = "[42]"
+    assert n882c == 42
+
+    a882 = "hello"
+    (==a882) + " world" = "hello world"
+
+    match (int -> mv882) + "px" in "100px":
+        assert mv882 == 100
+    else:
+        assert False
+
     # deferred ImportError on lazy imports
     lazy import coconut_nonexistent_test_module
     assert_raises(=> coconut_nonexistent_test_module.attr, ImportError)

coconut/tests/src/extras.coco

@@ -143,6 +143,10 @@ def test_setup_none() -> bool:
     assert_raises(-> parse("def f(x) = return x"), CoconutSyntaxError)
     assert_raises(-> parse("def f(x) =\n return x"), CoconutSyntaxError)
     assert_raises(-> parse("10 20"), CoconutSyntaxError)
+    assert_raises(-> parse('x + "1" + (=="2") = "test"'), CoconutSyntaxError)
+    assert_raises(-> parse('(==x) + "1" + y = "test"'), CoconutSyntaxError)
+    assert_raises(-> parse(r'd"\n    hello"'), CoconutSyntaxError)
+    assert_raises(-> parse('d"""    hello"""'), CoconutSyntaxError)
 
     assert_raises(-> parse("()[(())"), CoconutSyntaxError, err_has="""
 unclosed open '[' (line 1)