j-perm 0.2.0.1__tar.gz → 0.2.1.1__tar.gz

{j_perm-0.2.0.1 → j_perm-0.2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: j-perm
-Version: 0.2.0.1
+Version: 0.2.1.1
 Summary: json permutation library
 Author-email: Roman <kuschanow@gmail.com>
 License: MIT
@@ -84,11 +84,13 @@ Typical setup:
 substitutor = TemplateSubstitutor()
 special = SpecialResolver()
 handlers = Handlers()
+normalizer = Normalizer()
 
 engine = ActionEngine(
   handlers=handlers,
   special=special,
   substitutor=substitutor,
+  normalizer=normalizer,
 )
 ```
 
@@ -676,59 +678,103 @@ Update a mapping at `path` using either source mapping (`from`) or inline mappin
 
 ---
 
-## Shorthand expansion (built-in)
+## Shorthand normalization
 
-Normalization expands shorthand syntax into explicit operation steps:
+In addition to explicit DSL steps, J-Perm supports a *shorthand syntax* for more concise scripts.
+Shorthand forms are expanded into regular operation steps **before execution**.
 
-### `~delete`
+Shorthand expansion is implemented as a pluggable normalization layer, similar to operations and special constructs.
+
+### How it works
+
+During normalization, each mapping entry is processed by a chain of registered *shorthand rules*:
+
+1. Each rule decides whether it can handle a given `(key, value)` pair.
+2. If a rule matches, it expands the entry into one or more explicit operation steps.
+3. The first matching rule wins.
+4. If no rule matches, normalization fails with an error.
+
+The resulting list of steps is then executed by the engine as a normal DSL script.
+
+---
+
+### Built-in shorthand rules
+
+The following shorthand forms are enabled by default.
+
+#### Delete shorthand (`~delete`)
 
 ```json
 { "~delete": ["/a", "/b"] }
 ```
 
-→
+Expands into:
 
 ```json
 { "op": "delete", "path": "/a" }
 { "op": "delete", "path": "/b" }
 ```
 
-### `~assert`
+---
+
+#### Assert shorthand (`~assert`)
+
+Mapping form:
 
 ```json
-{ "~assert": { "/x": 10 } }
+{ "~assert": { "/x": 10, "/y": 20 } }
 ```
 
-→
+Expands into:
 
 ```json
 { "op": "assert", "path": "/x", "equals": 10 }
+{ "op": "assert", "path": "/y", "equals": 20 }
 ```
 
-### `field[]` append
+List / string form:
+
+```json
+{ "~assert": ["/x", "/y"] }
+```
+
+Expands into existence-only assertions.
+
+---
+
+#### Append shorthand (`field[]`)
+
+A key ending with `[]` means *append to a list* at that path:
 
 ```json
 { "items[]": 123 }
 ```
 
-→
+Expands into:
 
 ```json
 { "op": "set", "path": "/items/-", "value": 123 }
 ```
 
-### pointer assignment
+---
+
+#### Pointer assignment shorthand
 
-If a value is a string that starts with `/`, it becomes a `copy`:
+If a value is a string that starts with `/`, it is treated as a source pointer:
 
 ```json
 { "name": "/user/fullName" }
 ```
 
-→
+Expands into:
 
 ```json
-{ "op": "copy", "from": "/user/fullName", "path": "/name", "ignore_missing": true }
+{
+  "op": "copy",
+  "from": "/user/fullName",
+  "path": "/name",
+  "ignore_missing": true
+}
 ```
 
 ---
@@ -798,6 +844,21 @@ ${json:/raw_payload}
 
 ---
 
+### Custom shorthand rules
+
+```python
+from j_perm import ShorthandRegistry, ExpandResult
+
+@ShorthandRegistry.register("name", priority=10)
+def my_shorthand_rule(key: str, value: Any) -> ExpandResult | None:
+    if key.startswith("my_prefix_"):
+        # expand into steps
+        steps = [ ... ]
+        return steps
+```
+
+---
+
 ## Plugin loading
 
 Registries collect definitions **at import time**.

{j_perm-0.2.0.1 → j_perm-0.2.1.1}/README.md

@@ -71,11 +71,13 @@ Typical setup:
 substitutor = TemplateSubstitutor()
 special = SpecialResolver()
 handlers = Handlers()
+normalizer = Normalizer()
 
 engine = ActionEngine(
   handlers=handlers,
   special=special,
   substitutor=substitutor,
+  normalizer=normalizer,
 )
 ```
 
@@ -663,59 +665,103 @@ Update a mapping at `path` using either source mapping (`from`) or inline mappin
 
 ---
 
-## Shorthand expansion (built-in)
+## Shorthand normalization
 
-Normalization expands shorthand syntax into explicit operation steps:
+In addition to explicit DSL steps, J-Perm supports a *shorthand syntax* for more concise scripts.
+Shorthand forms are expanded into regular operation steps **before execution**.
 
-### `~delete`
+Shorthand expansion is implemented as a pluggable normalization layer, similar to operations and special constructs.
+
+### How it works
+
+During normalization, each mapping entry is processed by a chain of registered *shorthand rules*:
+
+1. Each rule decides whether it can handle a given `(key, value)` pair.
+2. If a rule matches, it expands the entry into one or more explicit operation steps.
+3. The first matching rule wins.
+4. If no rule matches, normalization fails with an error.
+
+The resulting list of steps is then executed by the engine as a normal DSL script.
+
+---
+
+### Built-in shorthand rules
+
+The following shorthand forms are enabled by default.
+
+#### Delete shorthand (`~delete`)
 
 ```json
 { "~delete": ["/a", "/b"] }
 ```
 
-→
+Expands into:
 
 ```json
 { "op": "delete", "path": "/a" }
 { "op": "delete", "path": "/b" }
 ```
 
-### `~assert`
+---
+
+#### Assert shorthand (`~assert`)
+
+Mapping form:
 
 ```json
-{ "~assert": { "/x": 10 } }
+{ "~assert": { "/x": 10, "/y": 20 } }
 ```
 
-→
+Expands into:
 
 ```json
 { "op": "assert", "path": "/x", "equals": 10 }
+{ "op": "assert", "path": "/y", "equals": 20 }
 ```
 
-### `field[]` append
+List / string form:
+
+```json
+{ "~assert": ["/x", "/y"] }
+```
+
+Expands into existence-only assertions.
+
+---
+
+#### Append shorthand (`field[]`)
+
+A key ending with `[]` means *append to a list* at that path:
 
 ```json
 { "items[]": 123 }
 ```
 
-→
+Expands into:
 
 ```json
 { "op": "set", "path": "/items/-", "value": 123 }
 ```
 
-### pointer assignment
+---
+
+#### Pointer assignment shorthand
 
-If a value is a string that starts with `/`, it becomes a `copy`:
+If a value is a string that starts with `/`, it is treated as a source pointer:
 
 ```json
 { "name": "/user/fullName" }
 ```
 
-→
+Expands into:
 
 ```json
-{ "op": "copy", "from": "/user/fullName", "path": "/name", "ignore_missing": true }
+{
+  "op": "copy",
+  "from": "/user/fullName",
+  "path": "/name",
+  "ignore_missing": true
+}
 ```
 
 ---
@@ -785,6 +831,21 @@ ${json:/raw_payload}
 
 ---
 
+### Custom shorthand rules
+
+```python
+from j_perm import ShorthandRegistry, ExpandResult
+
+@ShorthandRegistry.register("name", priority=10)
+def my_shorthand_rule(key: str, value: Any) -> ExpandResult | None:
+    if key.startswith("my_prefix_"):
+        # expand into steps
+        steps = [ ... ]
+        return steps
+```
+
+---
+
 ## Plugin loading
 
 Registries collect definitions **at import time**.

{j_perm-0.2.0.1 → j_perm-0.2.1.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "j-perm"
-version = "0.2.0.1"
+version = "0.2.1.1"
 description = "json permutation library"
 authors = [
     { name = "Roman", email = "kuschanow@gmail.com" },

{j_perm-0.2.0.1 → j_perm-0.2.1.1}/src/j_perm/__init__.py

@@ -3,19 +3,23 @@ from . import casters as _builtin_casters  # noqa: F401
 from . import constructs as _builtin_constructs  # noqa: F401
 from . import funcs as _builtin_funcs  # noqa: F401
 from . import ops as _builtin_ops  # noqa: F401
+from . import shorthands as _builtin_shorthands  # noqa: F401
 from .engine import apply_actions, ActionEngine
-from .subst import JpFuncRegistry, CasterRegistry, TemplateSubstitutor
+from .normalizer import Normalizer, ShorthandRegistry
 from .op_handler import OpRegistry, Handlers
 from .special_resolver import SpecialRegistry, SpecialResolver
+from .subst import JpFuncRegistry, CasterRegistry, TemplateSubstitutor
 
 __all__ = [
     "apply_actions",
     "ActionEngine",
-    "JpFuncRegistry",
-    "CasterRegistry",
-    "TemplateSubstitutor",
+    "Normalizer",
+    "ShorthandRegistry",
     "OpRegistry",
     "Handlers",
     "SpecialRegistry",
     "SpecialResolver",
+    "JpFuncRegistry",
+    "CasterRegistry",
+    "TemplateSubstitutor",
 ]

{j_perm-0.2.0.1 → j_perm-0.2.1.1}/src/j_perm/constructs/eval.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import Mapping, Any
 
-from j_perm.special_resolver import SpecialRegistry
+from ..special_resolver import SpecialRegistry
 
 
 @SpecialRegistry.register("$eval")

{j_perm-0.2.0.1 → j_perm-0.2.1.1}/src/j_perm/constructs/ref.py

@@ -3,8 +3,8 @@ from __future__ import annotations
 import copy
 from typing import Mapping, Any
 
-from j_perm.special_resolver import _MISSING, SpecialRegistry
-from j_perm.utils.pointers import maybe_slice
+from ..special_resolver import _MISSING, SpecialRegistry
+from ..utils.pointers import maybe_slice
 
 
 @SpecialRegistry.register("$ref")

{j_perm-0.2.0.1 → j_perm-0.2.1.1}/src/j_perm/engine.py

@@ -4,6 +4,7 @@ import copy
 from dataclasses import dataclass, field
 from typing import Any, List, Mapping, TypeAlias, MutableMapping, Union
 
+from .normalizer import Normalizer
 from .op_handler import Handlers
 from .special_resolver import SpecialResolver
 from .subst import TemplateSubstitutor
@@ -17,14 +18,6 @@ JsonLikeDest: TypeAlias = Union[MutableMapping[str, Any], List[Any]]
 # Small utilities
 # =============================================================================
 
-def _is_pointer_string(v: Any) -> bool:
-    return isinstance(v, str) and v.startswith("/")
-
-
-def _to_list(x: Any) -> List[Any]:
-    return x if isinstance(x, list) else [x]
-
-
 def tuples_to_lists(obj: Any) -> Any:
     """Recursively convert all tuples into lists so JMESPath indexers work reliably."""
     if isinstance(obj, tuple):
@@ -48,22 +41,13 @@ class ActionEngine:
       - handlers: a Handlers object (has get_handler)
       - special: a SpecialResolver (resolves $ref/$eval/... inside the actions spec, if you want)
       - substitutor: a TemplateSubstitutor (optional: expand ${...} in action specs)
-      - resolve_special_in_actions: enable resolving special constructs inside the actions spec
-      - substitute_templates_in_actions: enable template expansion inside the actions spec
-
-    Notes on order:
-      1) Optionally substitute templates in 'actions' using 'source' as context
-      2) Optionally resolve special constructs in 'actions' using 'source' as context
-      3) Normalize to flat step list
-      4) Execute handlers
+      - normalizer: a Normalizer (for shorthand expansion)
     """
 
     handlers: Handlers = field(default_factory=Handlers)
     special: SpecialResolver = field(default_factory=SpecialResolver)
     substitutor: TemplateSubstitutor = field(default_factory=TemplateSubstitutor)
-
-    resolve_special_in_actions: bool = True
-    substitute_templates_in_actions: bool = True
+    normalizer: Normalizer = field(default_factory=Normalizer)
 
     def apply_actions(
             self,
@@ -107,46 +91,16 @@ class ActionEngine:
             out: List[dict] = []
             for item in spec:
                 if isinstance(item, Mapping) and "op" not in item:
-                    out.extend(self._expand_shorthand(item))
+                    out.extend(self.normalizer.expand_shorthand(item))
                 else:
                     out.append(item)
             return out
 
         if isinstance(spec, Mapping):
-            return self._expand_shorthand(spec)
+            return self.normalizer.expand_shorthand(spec)
 
         raise TypeError("spec must be dict or list")
 
-    @staticmethod
-    def _expand_shorthand(obj: Mapping[str, Any]) -> List[dict]:
-        """Expand shorthand mapping form into explicit op steps."""
-        steps: List[dict] = []
-
-        for key, val in obj.items():
-            if key == "~delete":
-                for p in _to_list(val):
-                    steps.append({"op": "delete", "path": p})
-                continue
-
-            if key == "~assert":
-                if isinstance(val, Mapping):
-                    for p, eq in val.items():
-                        steps.append({"op": "assert", "path": p, "equals": eq})
-                else:
-                    for p in _to_list(val):
-                        steps.append({"op": "assert", "path": p})
-                continue
-
-            append = isinstance(key, str) and key.endswith("[]")
-            dst = f"{key[:-2]}/-" if append else key
-
-            if _is_pointer_string(val):
-                steps.append({"op": "copy", "from": val, "path": dst, "ignore_missing": True})
-            else:
-                steps.append({"op": "set", "path": dst, "value": val})
-
-        return steps
-
 
 # Create a default engine instance for convenience
 default_engine = ActionEngine()

{j_perm-0.2.0.1 → j_perm-0.2.1.1}/src/j_perm/funcs/subtract.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from jmespath import functions as _jp_funcs
 
-from j_perm.subst import JpFuncRegistry
+from ..subst import JpFuncRegistry
 
 
 @JpFuncRegistry.register("subtract")

j_perm-0.2.1.1/src/j_perm/normalizer.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping, Optional, List
+
+ExpandResult = Optional[List[dict]]
+Rule = Callable[[str, Any], ExpandResult]
+
+
+class ShorthandRegistry:
+    _rules: dict[str, Rule] = {}
+    _default_priority: dict[str, int] = {}  # name -> order (10, 5, 0, -5, -10...)
+
+    @classmethod
+    def register(cls, name: str, *, priority: int = 0):
+        def deco(fn: Rule) -> Rule:
+            if name in cls._rules:
+                raise ValueError(f"shorthand rule already registered: {name!r}")
+            cls._rules[name] = fn
+            cls._default_priority[name] = priority
+            return fn
+        return deco
+
+    @classmethod
+    def ordered(
+            cls,
+            rules: Mapping[str, Rule] | None = None,
+            *,
+            priority: Mapping[str, int] | None = None,
+    ) -> list[Rule]:
+        rules = dict(cls._rules if rules is None else rules)
+
+        _priority = dict(cls._default_priority)
+        if priority:
+            _priority.update(priority)
+
+        names = sorted(
+            rules.keys(),
+            key=lambda n: (_priority.get(n, 0), n),
+            reverse=True,
+        )
+        return [rules[n] for n in names]
+
+    @classmethod
+    def get(cls, name: str) -> Rule:
+        try:
+            return cls._rules[name]
+        except KeyError:
+            raise ValueError(f"Unknown rule {name!r}") from None
+
+    @classmethod
+    def all(cls) -> dict[str, Rule]:
+        return dict(cls._rules)
+
+
+@dataclass(slots=True)
+class Normalizer:
+    rules: list[str] | Mapping[str, Rule] | None = None
+    priority: Mapping[str, int] | None = None
+
+    _rules: list[Rule] = field(init=False)
+
+    def __post_init__(self) -> None:
+        if self.rules is None:
+            rules = ShorthandRegistry.all()
+        elif isinstance(self.rules, Mapping):
+            rules = dict(self.rules)
+        else:
+            all_rules = ShorthandRegistry.all()
+            rules = {}
+            for n in self.rules:
+                if n not in all_rules:
+                    raise ValueError(f"Unknown rule {n!r}")
+                rules[n] = all_rules[n]
+
+        self._rules = ShorthandRegistry.ordered(rules, priority=self.priority)
+
+    def expand_shorthand(self, obj: Mapping[str, Any]) -> List[dict]:
+        steps: List[dict] = []
+        for k, v in obj.items():
+            for rule in self._rules:
+                out = rule(k, v)
+                if out is not None:
+                    steps.extend(out)
+                    break
+            else:
+                raise ValueError(f"Unhandled shorthand key: {k!r}")
+        return steps

{j_perm-0.2.0.1 → j_perm-0.2.1.1}/src/j_perm/ops/__init__.py

@@ -1,4 +1,5 @@
 from ._assert import op_assert
+from ._assert_d import op_assert_d
 from ._exec import op_exec
 from ._if import op_if
 from .copy import op_copy

{j_perm-0.2.0.1 → j_perm-0.2.1.1}/src/j_perm/ops/_assert.py

@@ -17,11 +17,11 @@ def op_assert(
     path = engine.substitutor.substitute(step["path"], src)
 
     try:
-        current = jptr_get(dest, path)
+        current = jptr_get(src, path)
     except Exception:
-        raise AssertionError(f"{path} does not exist")
+        raise AssertionError(f"'{path}' does not exist in source")
 
     if "equals" in step and current != step["equals"]:
-        raise AssertionError(f"{path} != {step['equals']!r}")
+        raise AssertionError(f"'{path}' != '{step['equals']!r}'")
 
     return dest

j_perm-0.2.1.1/src/j_perm/ops/_assert_d.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import MutableMapping, Any, Mapping
+
+from ..op_handler import OpRegistry
+from ..utils.pointers import jptr_get
+
+
+@OpRegistry.register("assertD")
+def op_assert_d(
+        step: dict,
+        dest: MutableMapping[str, Any],
+        src: Mapping[str, Any],
+        engine: "ActionEngine",
+) -> MutableMapping[str, Any]:
+    """Assert node existence and/or value at JSON Pointer path in dest."""
+    path = engine.substitutor.substitute(step["path"], dest)
+
+    try:
+        current = jptr_get(dest, path)
+    except Exception:
+        raise AssertionError(f"'{path}' does not exist in destination")
+
+    if "equals" in step and current != step["equals"]:
+        raise AssertionError(f"'{path}' != '{step['equals']!r}'")
+
+    return dest

{j_perm-0.2.0.1 → j_perm-0.2.1.1}/src/j_perm/ops/_exec.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 from typing import MutableMapping, Any, Mapping
 
 from ..op_handler import OpRegistry
-from ..engine import apply_actions
 from ..utils.pointers import maybe_slice
 
 
@@ -43,10 +42,10 @@ def op_exec(
     merge = bool(step.get("merge", False))
 
     if merge:
-        result = apply_actions(actions, dest=dest, source=src)
+        result = engine.apply_actions(actions, dest=dest, source=src)
         return result
     else:
-        result = apply_actions(actions, dest={}, source=src)
+        result = engine.apply_actions(actions, dest={}, source=src)
         dest.clear()
         if isinstance(dest, list):
             dest.extend(result)  # type: ignore[arg-type]

j_perm-0.2.1.1/src/j_perm/shorthands/__init__.py

@@ -0,0 +1,3 @@
+from ._assert import rule_assert
+from .assign_or_append import rule_assign_or_append
+from .delete import rule_delete

j_perm-0.2.1.1/src/j_perm/shorthands/_assert.py

@@ -0,0 +1,17 @@
+from collections.abc import Mapping
+from typing import Any
+
+from ..normalizer import ShorthandRegistry, ExpandResult
+
+
+@ShorthandRegistry.register("assert")
+def rule_assert(key: str, val: Any) -> ExpandResult:
+    if key != "~assert" and key != "~assertD":
+        return None
+    if key == "~assertD":
+        op = "assertD"
+    else:
+        op = "assert"
+    if isinstance(val, Mapping):
+        return [{"op": op, "path": p, "equals": eq} for p, eq in val.items()]
+    return [{"op": op, "path": p} for p in (val if isinstance(val, list) else [val])]

j_perm-0.2.1.1/src/j_perm/shorthands/assign_or_append.py

@@ -0,0 +1,17 @@
+from typing import Any
+
+from ..normalizer import ExpandResult, ShorthandRegistry
+
+
+@ShorthandRegistry.register("assign_or_append", priority=-1)
+def rule_assign_or_append(key: str, val: Any) -> ExpandResult:
+    # Fallback rule: handles:
+    # - append shorthand: field[] -> "/field/-"
+    # - pointer assignment -> copy
+    # - literal assignment -> set
+    append = key.endswith("[]")
+    dst = f"{key[:-2]}/-" if append else key
+
+    if isinstance(val, str) and val.startswith("/"):
+        return [{"op": "copy", "from": val, "path": dst, "ignore_missing": True}]
+    return [{"op": "set", "path": dst, "value": val}]

j_perm-0.2.1.1/src/j_perm/shorthands/delete.py

@@ -0,0 +1,10 @@
+from typing import Any
+
+from ..normalizer import ShorthandRegistry, ExpandResult
+
+
+@ShorthandRegistry.register("delete")
+def rule_delete(key: str, val: Any) -> ExpandResult:
+    if key != "~delete":
+        return None
+    return [{"op": "delete", "path": p} for p in (val if isinstance(val, list) else [val])]

{j_perm-0.2.0.1 → j_perm-0.2.1.1}/src/j_perm.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: j-perm
-Version: 0.2.0.1
+Version: 0.2.1.1
 Summary: json permutation library
 Author-email: Roman <kuschanow@gmail.com>
 License: MIT
@@ -84,11 +84,13 @@ Typical setup:
 substitutor = TemplateSubstitutor()
 special = SpecialResolver()
 handlers = Handlers()
+normalizer = Normalizer()
 
 engine = ActionEngine(
   handlers=handlers,
   special=special,
   substitutor=substitutor,
+  normalizer=normalizer,
 )
 ```
 
@@ -676,59 +678,103 @@ Update a mapping at `path` using either source mapping (`from`) or inline mappin
 
 ---
 
-## Shorthand expansion (built-in)
+## Shorthand normalization
 
-Normalization expands shorthand syntax into explicit operation steps:
+In addition to explicit DSL steps, J-Perm supports a *shorthand syntax* for more concise scripts.
+Shorthand forms are expanded into regular operation steps **before execution**.
 
-### `~delete`
+Shorthand expansion is implemented as a pluggable normalization layer, similar to operations and special constructs.
+
+### How it works
+
+During normalization, each mapping entry is processed by a chain of registered *shorthand rules*:
+
+1. Each rule decides whether it can handle a given `(key, value)` pair.
+2. If a rule matches, it expands the entry into one or more explicit operation steps.
+3. The first matching rule wins.
+4. If no rule matches, normalization fails with an error.
+
+The resulting list of steps is then executed by the engine as a normal DSL script.
+
+---
+
+### Built-in shorthand rules
+
+The following shorthand forms are enabled by default.
+
+#### Delete shorthand (`~delete`)
 
 ```json
 { "~delete": ["/a", "/b"] }
 ```
 
-→
+Expands into:
 
 ```json
 { "op": "delete", "path": "/a" }
 { "op": "delete", "path": "/b" }
 ```
 
-### `~assert`
+---
+
+#### Assert shorthand (`~assert`)
+
+Mapping form:
 
 ```json
-{ "~assert": { "/x": 10 } }
+{ "~assert": { "/x": 10, "/y": 20 } }
 ```
 
-→
+Expands into:
 
 ```json
 { "op": "assert", "path": "/x", "equals": 10 }
+{ "op": "assert", "path": "/y", "equals": 20 }
 ```
 
-### `field[]` append
+List / string form:
+
+```json
+{ "~assert": ["/x", "/y"] }
+```
+
+Expands into existence-only assertions.
+
+---
+
+#### Append shorthand (`field[]`)
+
+A key ending with `[]` means *append to a list* at that path:
 
 ```json
 { "items[]": 123 }
 ```
 
-→
+Expands into:
 
 ```json
 { "op": "set", "path": "/items/-", "value": 123 }
 ```
 
-### pointer assignment
+---
+
+#### Pointer assignment shorthand
 
-If a value is a string that starts with `/`, it becomes a `copy`:
+If a value is a string that starts with `/`, it is treated as a source pointer:
 
 ```json
 { "name": "/user/fullName" }
 ```
 
-→
+Expands into:
 
 ```json
-{ "op": "copy", "from": "/user/fullName", "path": "/name", "ignore_missing": true }
+{
+  "op": "copy",
+  "from": "/user/fullName",
+  "path": "/name",
+  "ignore_missing": true
+}
 ```
 
 ---
@@ -798,6 +844,21 @@ ${json:/raw_payload}
 
 ---
 
+### Custom shorthand rules
+
+```python
+from j_perm import ShorthandRegistry, ExpandResult
+
+@ShorthandRegistry.register("name", priority=10)
+def my_shorthand_rule(key: str, value: Any) -> ExpandResult | None:
+    if key.startswith("my_prefix_"):
+        # expand into steps
+        steps = [ ... ]
+        return steps
+```
+
+---
+
 ## Plugin loading
 
 Registries collect definitions **at import time**.

{j_perm-0.2.0.1 → j_perm-0.2.1.1}/src/j_perm.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.md
 pyproject.toml
 src/j_perm/__init__.py
 src/j_perm/engine.py
+src/j_perm/normalizer.py
 src/j_perm/op_handler.py
 src/j_perm/special_resolver.py
 src/j_perm/subst.py
@@ -22,6 +23,7 @@ src/j_perm/funcs/__init__.py
 src/j_perm/funcs/subtract.py
 src/j_perm/ops/__init__.py
 src/j_perm/ops/_assert.py
+src/j_perm/ops/_assert_d.py
 src/j_perm/ops/_exec.py
 src/j_perm/ops/_if.py
 src/j_perm/ops/copy.py
@@ -33,5 +35,9 @@ src/j_perm/ops/replace_root.py
 src/j_perm/ops/set.py
 src/j_perm/ops/update.py
 src/j_perm/schema/__init__.py
+src/j_perm/shorthands/__init__.py
+src/j_perm/shorthands/_assert.py
+src/j_perm/shorthands/assign_or_append.py
+src/j_perm/shorthands/delete.py
 src/j_perm/utils/__init__.py
 src/j_perm/utils/pointers.py