dotted-notation 0.41.0__tar.gz → 0.41.2__tar.gz

{dotted_notation-0.41.0/dotted_notation.egg-info → dotted_notation-0.41.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.41.0
+Version: 0.41.2
 Summary: Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms
 Home-page: https://github.com/freywaid/dotted
 Author: Frey Waid
@@ -111,6 +111,7 @@ Or pick only what you need:
   - [Slicing vs Patterns](#slicing-vs-patterns)
 - [Substitutions and References](#substitutions-and-references)
   - [Substitution](#substitution)
+    - [Substitution transforms](#substitution-transforms)
   - [References](#references)
   - [Relative References](#relative-references)
   - [Escaping](#escaping)
@@ -462,7 +463,7 @@ excluding literals:
 Substitute placeholders in a template path with bound values. Template paths
 are validated at parse time — structural errors are caught immediately, not at runtime.
 
-Positional (`$N`) placeholders resolve against a tuple:
+Positional (`$N`) placeholders resolve against a list or tuple:
 
     >>> import dotted
     >>> dotted.replace('people.$1.$2', ('users', 'alice', 'age'))
@@ -473,6 +474,11 @@ Named (`$(name)`) placeholders resolve against a dict:
     >>> dotted.replace('$(table).$(key)', {'table': 'users', 'key': 'alice'})
     'users.alice'
 
+Placeholders support transforms inside the parenthesized form:
+
+    >>> dotted.replace('$(0|uppercase)', ['hello'])
+    'HELLO'
+
 Combine with `match` to remap paths — capture groups from one pattern and substitute
 into another:
 
@@ -1167,8 +1173,10 @@ at replace time) and **references** (resolved during traversal).
 
 | Syntax | Type | Resolved against |
 |---|---|---|
-| `$0`, `$1` | Positional substitution | `replace()` bindings |
-| `$(name)` | Named substitution | `replace()` bindings |
+| `$0`, `$1` | Positional substitution | `replace()` bindings (list/tuple) |
+| `$(name)` | Named substitution | `replace()` bindings (dict) |
+| `$(0)`, `$(name)` | Substitution with parens | `replace()` bindings via `__getitem__` |
+| `$(name\|int)` | Substitution with transform | `replace()` bindings, then transform |
 | `$$(path)` | Reference | Root object during traversal |
 | `$$(^path)` | Relative reference | Current node during traversal |
 | `$$(^^path)` | Relative reference | Parent node during traversal |
@@ -1178,7 +1186,7 @@ at replace time) and **references** (resolved during traversal).
 
 Substitution references turn a path into a **template**. There are two forms:
 
-- **Positional** (`$0`, `$1`, …) — resolved against a tuple of values
+- **Positional** (`$0`, `$1`, …) — resolved against a list or tuple
 - **Named** (`$(name)`, `$(key)`, …) — resolved against a dict
 
 The `replace` function resolves them:
@@ -1188,6 +1196,13 @@ The `replace` function resolves them:
     >>> dotted.replace('$(table).$(field)', {'table': 'users', 'field': 'email'})
     'users.email'
 
+The parenthesized form `$(N)` adapts to the binding type — it uses `__getitem__`,
+so `$(0)` works as a positional index against a list or as a numeric key against
+a dict:
+
+    >>> dotted.replace('$(0)', {0: 'zero'})
+    'zero'
+
 Use `is_template` to test whether a path contains substitution references:
 
     >>> dotted.is_template('a.$0')
@@ -1197,6 +1212,25 @@ Use `is_template` to test whether a path contains substitution references:
     >>> dotted.is_template('a.b')
     False
 
+#### Substitution transforms
+
+Substitutions support per-substitution transforms using the `|` separator inside
+the parenthesized form. The transform is applied to the resolved value before it
+is spliced into the path:
+
+    >>> dotted.replace('$(name|uppercase)', {'name': 'hello'})
+    'HELLO'
+    >>> dotted.replace('$(0|str)', [42])
+    '42'
+
+Multiple transforms chain left to right:
+
+    >>> dotted.replace('$(name|strip|lowercase)', {'name': '  HELLO  '})
+    'hello'
+
+All [built-in transforms](#built-in-transforms) are available. The bare `$N` form
+does not support transforms — use `$(N|transform)` instead.
+
 See [Replace](#replace) and [Translate](#translate) for full API details.
 
 <a id="references"></a>

{dotted_notation-0.41.0 → dotted_notation-0.41.2}/README.md

@@ -74,6 +74,7 @@ Or pick only what you need:
   - [Slicing vs Patterns](#slicing-vs-patterns)
 - [Substitutions and References](#substitutions-and-references)
   - [Substitution](#substitution)
+    - [Substitution transforms](#substitution-transforms)
   - [References](#references)
   - [Relative References](#relative-references)
   - [Escaping](#escaping)
@@ -425,7 +426,7 @@ excluding literals:
 Substitute placeholders in a template path with bound values. Template paths
 are validated at parse time — structural errors are caught immediately, not at runtime.
 
-Positional (`$N`) placeholders resolve against a tuple:
+Positional (`$N`) placeholders resolve against a list or tuple:
 
     >>> import dotted
     >>> dotted.replace('people.$1.$2', ('users', 'alice', 'age'))
@@ -436,6 +437,11 @@ Named (`$(name)`) placeholders resolve against a dict:
     >>> dotted.replace('$(table).$(key)', {'table': 'users', 'key': 'alice'})
     'users.alice'
 
+Placeholders support transforms inside the parenthesized form:
+
+    >>> dotted.replace('$(0|uppercase)', ['hello'])
+    'HELLO'
+
 Combine with `match` to remap paths — capture groups from one pattern and substitute
 into another:
 
@@ -1130,8 +1136,10 @@ at replace time) and **references** (resolved during traversal).
 
 | Syntax | Type | Resolved against |
 |---|---|---|
-| `$0`, `$1` | Positional substitution | `replace()` bindings |
-| `$(name)` | Named substitution | `replace()` bindings |
+| `$0`, `$1` | Positional substitution | `replace()` bindings (list/tuple) |
+| `$(name)` | Named substitution | `replace()` bindings (dict) |
+| `$(0)`, `$(name)` | Substitution with parens | `replace()` bindings via `__getitem__` |
+| `$(name\|int)` | Substitution with transform | `replace()` bindings, then transform |
 | `$$(path)` | Reference | Root object during traversal |
 | `$$(^path)` | Relative reference | Current node during traversal |
 | `$$(^^path)` | Relative reference | Parent node during traversal |
@@ -1141,7 +1149,7 @@ at replace time) and **references** (resolved during traversal).
 
 Substitution references turn a path into a **template**. There are two forms:
 
-- **Positional** (`$0`, `$1`, …) — resolved against a tuple of values
+- **Positional** (`$0`, `$1`, …) — resolved against a list or tuple
 - **Named** (`$(name)`, `$(key)`, …) — resolved against a dict
 
 The `replace` function resolves them:
@@ -1151,6 +1159,13 @@ The `replace` function resolves them:
     >>> dotted.replace('$(table).$(field)', {'table': 'users', 'field': 'email'})
     'users.email'
 
+The parenthesized form `$(N)` adapts to the binding type — it uses `__getitem__`,
+so `$(0)` works as a positional index against a list or as a numeric key against
+a dict:
+
+    >>> dotted.replace('$(0)', {0: 'zero'})
+    'zero'
+
 Use `is_template` to test whether a path contains substitution references:
 
     >>> dotted.is_template('a.$0')
@@ -1160,6 +1175,25 @@ Use `is_template` to test whether a path contains substitution references:
     >>> dotted.is_template('a.b')
     False
 
+#### Substitution transforms
+
+Substitutions support per-substitution transforms using the `|` separator inside
+the parenthesized form. The transform is applied to the resolved value before it
+is spliced into the path:
+
+    >>> dotted.replace('$(name|uppercase)', {'name': 'hello'})
+    'HELLO'
+    >>> dotted.replace('$(0|str)', [42])
+    '42'
+
+Multiple transforms chain left to right:
+
+    >>> dotted.replace('$(name|strip|lowercase)', {'name': '  HELLO  '})
+    'hello'
+
+All [built-in transforms](#built-in-transforms) are available. The bare `$N` form
+does not support transforms — use `$(N|transform)` instead.
+
 See [Replace](#replace) and [Translate](#translate) for full API details.
 
 <a id="references"></a>

{dotted_notation-0.41.0 → dotted_notation-0.41.2}/dotted/base.py

@@ -65,7 +65,7 @@ class Op:
         return self.__class__ == op.__class__ and self.args == op.args
     def resolve(self, bindings, partial=False):
         """
-        Return a new op with all PositionalSubst resolved.
+        Return a new op with all substitutions resolved.
         Default: return self (no substitutions).
         """
         return self
@@ -149,6 +149,13 @@ class TraversalOp(Op):
     Base class for ops that participate in stack-based traversal.
     Subclasses must implement push_children(stack, frame, paths).
     """
+    @property
+    def most_inner(self):
+        """
+        Return self — no wrapping to unwrap.
+        """
+        return self
+
     def to_branches(self):
         return [tuple([self])]
 

{dotted_notation-0.41.0 → dotted_notation-0.41.2}/dotted/engine.py

@@ -18,7 +18,7 @@ def _needs_parents(ops):
     (parent or higher), requiring _parents tracking during traversal.
     """
     for op in ops:
-        inner = op.inner if isinstance(op, wrappers.Wrap) else op
+        inner = op.most_inner
         if (hasattr(inner, 'is_reference') and inner.is_reference()
                 and inner.op.depth >= 2):
             return True

{dotted_notation-0.41.0 → dotted_notation-0.41.2}/dotted/grammar.py

@@ -84,11 +84,23 @@ _escaped_dollar = pp.Regex(r'\\\$\${0,2}(\([^)]*\)|[0-9]*)').set_parse_action(
     lambda t: matchers.Word(t[0][1:]))
 _reference = pp.Regex(r'\$\$\([^)]+\)').set_parse_action(
     lambda t: matchers.Reference(t[0][3:-1]))
-_named_subst = pp.Regex(r'\$\([a-zA-Z_]\w*\)').set_parse_action(
-    lambda t: matchers.NamedSubst(t[0][2:-1]))
+def _paren_subst_action(t):
+    """
+    Parse $(content) where content is name_or_index[|transform1|transform2...].
+    """
+    content = t[0][2:-1]  # strip $( and )
+    parts = content.split('|')
+    name = parts[0]
+    xforms = tuple(base.Transform(p) for p in parts[1:]) if len(parts) > 1 else ()
+    try:
+        return matchers.Subst(int(name), transforms=xforms)
+    except ValueError:
+        return matchers.Subst(name, transforms=xforms)
+
+_paren_subst = pp.Regex(r'\$\([^)]+\)').set_parse_action(_paren_subst_action)
 _raw_subst = pp.Regex(r'\$[0-9]+').set_parse_action(
-    lambda t: matchers.PositionalSubst(int(t[0][1:])))
-subst = _escaped_dollar | _reference | _named_subst | _raw_subst
+    lambda t: matchers.Subst(int(t[0][1:])))
+subst = _escaped_dollar | _reference | _paren_subst | _raw_subst
 slice = pp.Optional(integer | plus) + ':' + pp.Optional(integer | plus) \
          + pp.Optional(':') + pp.Optional(integer | plus)
 

{dotted_notation-0.41.0 → dotted_notation-0.41.2}/dotted/matchers.py

@@ -147,8 +147,15 @@ class Pattern(MatchOp):
 
 class Subst(Pattern):
     """
-    Base class for substitution ops ($0, $(name), etc.).
+    Substitution op: $0, $(name), $(0|transform), $(name|int), etc.
+    Resolves against bindings via __getitem__: list for positional,
+    dict for named or numeric keys.  Optional transforms applied
+    after lookup.
     """
+    def __init__(self, *args, transforms=(), **kwargs):
+        super().__init__(*args, **kwargs)
+        self.transforms = tuple(transforms)
+
     @property
     def value(self):
         return self.args[0]
@@ -162,47 +169,42 @@ class Subst(Pattern):
     def matchable(self, op, specials=False):
         return False
 
-
-class PositionalSubst(Subst):
-    """
-    Substitution op for captured match groups: $0, $1, $2, etc.
-    """
-    def resolve(self, bindings, partial=False):
+    def _apply_transforms(self, val):
         """
-        Resolve this substitution against bindings.
-        Returns ResolvedValue on success, self if partial and out of range,
-        or raises IndexError if not partial and out of range.
+        Apply this op's transforms to a resolved value.
         """
-        idx = self.value
-        if idx < len(bindings):
-            return ResolvedValue(str(bindings[idx]))
-        if partial:
-            return self
-        raise IndexError(
-            f'${idx} out of range ({len(bindings)} bindings)')
-    def __repr__(self):
-        return f'${self.args[0]}'
+        if not self.transforms:
+            return val
+        from .results import apply_transforms
+        return apply_transforms(val, self.transforms)
 
+    def _transform_suffix(self):
+        """
+        Render |transform1|transform2 suffix for quote/repr.
+        """
+        if not self.transforms:
+            return ''
+        return ''.join(f'|{t.operator()}' for t in self.transforms)
 
-class NamedSubst(Subst):
-    """
-    Substitution op for named bindings: $(name), $(key), etc.
-    """
     def resolve(self, bindings, partial=False):
         """
-        Resolve this substitution against a dict of bindings.
-        Returns ResolvedValue on success, self if partial and missing,
-        or raises KeyError if not partial and missing.
+        Resolve this substitution against bindings.
         """
-        name = self.value
-        if name in bindings:
-            return ResolvedValue(str(bindings[name]))
-        if partial:
-            return self
-        raise KeyError(
-            f'$({name}) not found in bindings')
+        try:
+            val = self._apply_transforms(bindings[self.value])
+            return ResolvedValue(str(val))
+        except (KeyError, IndexError, TypeError):
+            if partial:
+                return self
+            raise
+
     def __repr__(self):
-        return f'$({self.args[0]})'
+        suffix = self._transform_suffix()
+        v = self.args[0]
+        if isinstance(v, int) and not suffix:
+            return f'${v}'
+        return f'$({v}{suffix})'
+
 
 
 class Reference(MatchOp):

{dotted_notation-0.41.0 → dotted_notation-0.41.2}/dotted/wrappers.py

@@ -21,6 +21,16 @@ class Wrap(base.TraversalOp):
 
     inner = None  # subclasses set in __init__
 
+    @property
+    def most_inner(self):
+        """
+        Unwrap through nested Wraps to the innermost op.
+        """
+        op = self.inner
+        while isinstance(op, Wrap):
+            op = op.inner
+        return op
+
     def is_pattern(self):
         return self.inner.is_pattern() if hasattr(self.inner, 'is_pattern') else False
 
@@ -30,6 +40,12 @@ class Wrap(base.TraversalOp):
         """
         return self.inner.is_template() if hasattr(self.inner, 'is_template') else False
 
+    def is_reference(self):
+        """
+        Delegate to inner op.
+        """
+        return self.inner.is_reference() if hasattr(self.inner, 'is_reference') else False
+
     def default(self):
         return self.inner.default() if hasattr(self.inner, 'default') else {}
 

{dotted_notation-0.41.0 → dotted_notation-0.41.2/dotted_notation.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.41.0
+Version: 0.41.2
 Summary: Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms
 Home-page: https://github.com/freywaid/dotted
 Author: Frey Waid
@@ -111,6 +111,7 @@ Or pick only what you need:
   - [Slicing vs Patterns](#slicing-vs-patterns)
 - [Substitutions and References](#substitutions-and-references)
   - [Substitution](#substitution)
+    - [Substitution transforms](#substitution-transforms)
   - [References](#references)
   - [Relative References](#relative-references)
   - [Escaping](#escaping)
@@ -462,7 +463,7 @@ excluding literals:
 Substitute placeholders in a template path with bound values. Template paths
 are validated at parse time — structural errors are caught immediately, not at runtime.
 
-Positional (`$N`) placeholders resolve against a tuple:
+Positional (`$N`) placeholders resolve against a list or tuple:
 
     >>> import dotted
     >>> dotted.replace('people.$1.$2', ('users', 'alice', 'age'))
@@ -473,6 +474,11 @@ Named (`$(name)`) placeholders resolve against a dict:
     >>> dotted.replace('$(table).$(key)', {'table': 'users', 'key': 'alice'})
     'users.alice'
 
+Placeholders support transforms inside the parenthesized form:
+
+    >>> dotted.replace('$(0|uppercase)', ['hello'])
+    'HELLO'
+
 Combine with `match` to remap paths — capture groups from one pattern and substitute
 into another:
 
@@ -1167,8 +1173,10 @@ at replace time) and **references** (resolved during traversal).
 
 | Syntax | Type | Resolved against |
 |---|---|---|
-| `$0`, `$1` | Positional substitution | `replace()` bindings |
-| `$(name)` | Named substitution | `replace()` bindings |
+| `$0`, `$1` | Positional substitution | `replace()` bindings (list/tuple) |
+| `$(name)` | Named substitution | `replace()` bindings (dict) |
+| `$(0)`, `$(name)` | Substitution with parens | `replace()` bindings via `__getitem__` |
+| `$(name\|int)` | Substitution with transform | `replace()` bindings, then transform |
 | `$$(path)` | Reference | Root object during traversal |
 | `$$(^path)` | Relative reference | Current node during traversal |
 | `$$(^^path)` | Relative reference | Parent node during traversal |
@@ -1178,7 +1186,7 @@ at replace time) and **references** (resolved during traversal).
 
 Substitution references turn a path into a **template**. There are two forms:
 
-- **Positional** (`$0`, `$1`, …) — resolved against a tuple of values
+- **Positional** (`$0`, `$1`, …) — resolved against a list or tuple
 - **Named** (`$(name)`, `$(key)`, …) — resolved against a dict
 
 The `replace` function resolves them:
@@ -1188,6 +1196,13 @@ The `replace` function resolves them:
     >>> dotted.replace('$(table).$(field)', {'table': 'users', 'field': 'email'})
     'users.email'
 
+The parenthesized form `$(N)` adapts to the binding type — it uses `__getitem__`,
+so `$(0)` works as a positional index against a list or as a numeric key against
+a dict:
+
+    >>> dotted.replace('$(0)', {0: 'zero'})
+    'zero'
+
 Use `is_template` to test whether a path contains substitution references:
 
     >>> dotted.is_template('a.$0')
@@ -1197,6 +1212,25 @@ Use `is_template` to test whether a path contains substitution references:
     >>> dotted.is_template('a.b')
     False
 
+#### Substitution transforms
+
+Substitutions support per-substitution transforms using the `|` separator inside
+the parenthesized form. The transform is applied to the resolved value before it
+is spliced into the path:
+
+    >>> dotted.replace('$(name|uppercase)', {'name': 'hello'})
+    'HELLO'
+    >>> dotted.replace('$(0|str)', [42])
+    '42'
+
+Multiple transforms chain left to right:
+
+    >>> dotted.replace('$(name|strip|lowercase)', {'name': '  HELLO  '})
+    'hello'
+
+All [built-in transforms](#built-in-transforms) are available. The bare `$N` form
+does not support transforms — use `$(N|transform)` instead.
+
 See [Replace](#replace) and [Translate](#translate) for full API details.
 
 <a id="references"></a>

{dotted_notation-0.41.0 → dotted_notation-0.41.2}/dotted_notation.egg-info/SOURCES.txt

@@ -60,6 +60,7 @@ tests/test_softcut.py
 tests/test_strict.py
 tests/test_string_glob.py
 tests/test_subst_escape.py
+tests/test_subst_transforms.py
 tests/test_transforms.py
 tests/test_translate.py
 tests/test_type_restriction.py

{dotted_notation-0.41.0 → dotted_notation-0.41.2}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "rt") as f:
 
 setuptools.setup(
     name="dotted_notation",
-    version="0.41.0",
+    version="0.41.2",
     author="Frey Waid",
     author_email="logophage1@gmail.com",
     description="Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms",

{dotted_notation-0.41.0 → dotted_notation-0.41.2}/tests/test_named_subst.py

@@ -4,27 +4,27 @@ Tests for $(name) named substitutions.
 import pytest
 import dotted
 from dotted.api import parse, assemble, replace, quote
-from dotted.matchers import NamedSubst, Word
+from dotted.matchers import Subst, Word
 
 
 # ---- parsing ----
 
 def test_parse_named_subst():
     ops = parse('$(name)')
-    assert isinstance(ops[0].op, NamedSubst)
+    assert isinstance(ops[0].op, Subst)
     assert ops[0].op.value == 'name'
 
 
 def test_parse_named_subst_underscore():
     ops = parse('$(my_key)')
-    assert isinstance(ops[0].op, NamedSubst)
+    assert isinstance(ops[0].op, Subst)
     assert ops[0].op.value == 'my_key'
 
 
 def test_parse_named_subst_nested():
     ops = parse('a.$(key).b')
     assert len(ops) == 3
-    assert isinstance(ops[1].op, NamedSubst)
+    assert isinstance(ops[1].op, Subst)
     assert ops[1].op.value == 'key'
 
 

{dotted_notation-0.41.0 → dotted_notation-0.41.2}/tests/test_replace.py

@@ -5,7 +5,7 @@ import pytest
 import dotted
 from dotted.api import parse
 from dotted.access import Key, Attr, Slot
-from dotted.matchers import PositionalSubst
+from dotted.matchers import Subst
 from dotted.results import assemble
 
 
@@ -17,7 +17,7 @@ def test_parse_subst_key_position():
     ops = parse('a.$0')
     assert len(ops) == 2
     assert isinstance(ops[1], Key)
-    assert isinstance(ops[1].op, PositionalSubst)
+    assert isinstance(ops[1].op, Subst)
     assert ops[1].op.value == 0
 
 
@@ -25,7 +25,7 @@ def test_parse_subst_slot_position():
     ops = parse('a[$0]')
     assert len(ops) == 2
     assert isinstance(ops[1], Slot)
-    assert isinstance(ops[1].op, PositionalSubst)
+    assert isinstance(ops[1].op, Subst)
     assert ops[1].op.value == 0
 
 
@@ -33,15 +33,15 @@ def test_parse_subst_attr_position():
     ops = parse('$0@$1')
     assert len(ops) == 2
     assert isinstance(ops[0], Key)
-    assert isinstance(ops[0].op, PositionalSubst)
+    assert isinstance(ops[0].op, Subst)
     assert isinstance(ops[1], Attr)
-    assert isinstance(ops[1].op, PositionalSubst)
+    assert isinstance(ops[1].op, Subst)
     assert ops[1].op.value == 1
 
 
 def test_parse_subst_multi_digit():
     ops = parse('$10')
-    assert isinstance(ops[0].op, PositionalSubst)
+    assert isinstance(ops[0].op, Subst)
     assert ops[0].op.value == 10
 
 
@@ -99,22 +99,22 @@ def test_parse_subst_container_value():
 
 
 # ---------------------------------------------------------------------------
-# PositionalSubst.resolve
+# Subst.resolve
 # ---------------------------------------------------------------------------
 
 def test_resolve_in_range():
-    s = PositionalSubst(2)
+    s = Subst(2)
     r = s.resolve(('a', 'b', 'c'))
     assert r.value == 'c'
 
 
 def test_resolve_out_of_range():
-    s = PositionalSubst(5)
+    s = Subst(5)
     assert s.resolve(('a', 'b'), partial=True) is s
 
 
 def test_resolve_out_of_range_strict():
-    s = PositionalSubst(5)
+    s = Subst(5)
     with pytest.raises(IndexError):
         s.resolve(('a', 'b'))
 

{dotted_notation-0.41.0 → dotted_notation-0.41.2}/tests/test_subst_escape.py

@@ -3,7 +3,7 @@ Tests for $N substitution escaping and is_template API.
 """
 import dotted
 from dotted.api import parse, assemble, quote
-from dotted.matchers import Word, PositionalSubst
+from dotted.matchers import Word, Subst
 
 
 # ---- escaping: \$ produces literal dollar-sign keys ----
@@ -28,7 +28,7 @@ def test_parse_escaped_dollar_multi_digit():
 
 def test_parse_raw_subst_still_works():
     ops = parse('$0')
-    assert isinstance(ops[0].op, PositionalSubst)
+    assert isinstance(ops[0].op, Subst)
     assert ops[0].op.value == 0
 
 

dotted_notation-0.41.2/tests/test_subst_transforms.py

@@ -0,0 +1,173 @@
+"""
+Tests for substitution transforms: $(name|transform), $(0|transform).
+"""
+from dotted.api import replace, is_template, parse
+from dotted.matchers import Subst
+from dotted.results import assemble
+
+
+# ---- parsing ----
+
+def test_parse_named_with_transform():
+    """
+    $(name|int) parses as Subst with int transform.
+    """
+    ops = parse('$(name|int)')
+    assert isinstance(ops[0].op, Subst)
+    assert ops[0].op.value == 'name'
+    assert len(ops[0].op.transforms) == 1
+    assert ops[0].op.transforms[0].name == 'int'
+
+
+def test_parse_named_no_transform():
+    """
+    $(name) still parses as Subst with no transforms.
+    """
+    ops = parse('$(name)')
+    assert isinstance(ops[0].op, Subst)
+    assert ops[0].op.value == 'name'
+    assert ops[0].op.transforms == ()
+
+
+def test_parse_numeric_paren_with_transform():
+    """
+    $(0|str) parses as Subst with str transform.
+    """
+    ops = parse('$(0|str)')
+    assert isinstance(ops[0].op, Subst)
+    assert ops[0].op.value == 0
+    assert len(ops[0].op.transforms) == 1
+    assert ops[0].op.transforms[0].name == 'str'
+
+
+def test_parse_numeric_paren_no_transform():
+    """
+    $(0) parses as Subst with no transforms.
+    """
+    ops = parse('$(0)')
+    assert isinstance(ops[0].op, Subst)
+    assert ops[0].op.value == 0
+    assert ops[0].op.transforms == ()
+
+
+def test_parse_raw_positional():
+    """
+    $0 still parses as Subst with no transforms.
+    """
+    ops = parse('$0')
+    assert isinstance(ops[0].op, Subst)
+    assert ops[0].op.value == 0
+    assert ops[0].op.transforms == ()
+
+
+def test_parse_multiple_transforms():
+    """
+    $(name|strip|lowercase) parses with two transforms.
+    """
+    ops = parse('$(name|strip|lowercase)')
+    assert isinstance(ops[0].op, Subst)
+    assert len(ops[0].op.transforms) == 2
+    assert ops[0].op.transforms[0].name == 'strip'
+    assert ops[0].op.transforms[1].name == 'lowercase'
+
+
+# ---- resolve with transforms ----
+
+def test_resolve_named_with_int_transform():
+    """
+    $(name|int) resolves and applies int transform.
+    """
+    result = replace('$(name|int)', {'name': '42'})
+    assert result == '42'
+
+
+def test_resolve_named_with_str_transform():
+    """
+    $(name|str) resolves and applies str transform.
+    """
+    result = replace('$(name|str)', {'name': 123})
+    assert result == '123'
+
+
+def test_resolve_numeric_with_transform():
+    """
+    $(0|uppercase) resolves positional and applies transform.
+    """
+    result = replace('$(0|uppercase)', ['hello'])
+    assert result == 'HELLO'
+
+
+def test_resolve_raw_positional_no_transform():
+    """
+    $0 resolves against list bindings as before.
+    """
+    result = replace('prefix.$0', ['world'])
+    assert result == 'prefix.world'
+
+
+# ---- Subst against dict bindings ----
+
+def test_numeric_subst_dict_bindings():
+    """
+    $(0) against dict bindings looks up numeric key 0.
+    """
+    result = replace('$(0)', {0: 'zero'})
+    assert result == 'zero'
+
+
+# ---- round-trip ----
+
+def test_repr_named_with_transform():
+    """
+    Subst with transforms repr includes the suffix.
+    """
+    ops = parse('$(name|int)')
+    assert repr(ops[0].op) == '$(name|int)'
+
+
+def test_repr_numeric_with_transform():
+    """
+    Subst with transforms uses paren form.
+    """
+    ops = parse('$(0|str)')
+    assert repr(ops[0].op) == '$(0|str)'
+
+
+def test_repr_numeric_no_transform():
+    """
+    Subst without transforms uses bare $N form.
+    """
+    ops = parse('$0')
+    assert repr(ops[0].op) == '$0'
+
+
+def test_assemble_named_with_transform():
+    """
+    Assembling a path with $(name|int) round-trips.
+    """
+    ops = parse('a.$(name|int).b')
+    assert assemble(ops) == 'a.$(name|int).b'
+
+
+def test_assemble_numeric_with_transform():
+    """
+    Assembling a path with $(0|str) round-trips.
+    """
+    ops = parse('a.$(0|str).b')
+    assert assemble(ops) == 'a.$(0|str).b'
+
+
+# ---- is_template ----
+
+def test_is_template_with_transform():
+    """
+    $(name|int) is still a template.
+    """
+    assert is_template('$(name|int)')
+
+
+def test_is_template_numeric_with_transform():
+    """
+    $(0|str) is still a template.
+    """
+    assert is_template('$(0|str)')