bolt-anchors 0.1.0__tar.gz

bolt_anchors-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.3
+Name: bolt-anchors
+Version: 0.1.0
+Summary: Name resource locations and build nested paths in bolt
+Requires-Dist: beet>=0.119.0
+Requires-Dist: bolt>=0.51.0
+Requires-Dist: mecha>=0.106.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Bolt Anchors
+
+> Name resource locations and build nested paths in [bolt](https://github.com/mcbeet/beet/tree/main/packages/bolt).
+
+Bolt anchors let you bind a resource declaration to an identifier with the `as`
+clause. The anchor can then be used as a value or extended with `/` to build
+nested resource locations.
+
+## Installation
+
+```bash
+pip install bolt-anchors
+```
+
+## Configuration
+
+Add the plugin to your `beet.yml`/`beet.json` after `bolt`.
+
+```yaml
+pipeline:
+  - mecha
+
+require:
+  - bolt
+  - bolt_anchors
+```
+
+## Usage
+
+Bind an anchor when declaring any resource. The anchor holds the fully resolved
+resource location of the declaration.
+
+```mcfunction
+append function ~/foo as foo:
+    print(foo)
+    function foo / "bar":
+        say foo bar
+```
+
+`foo` resolves to `namespace:foo/foo` (relative to the current file and the
+enclosing declarations) and `foo / "bar"` extends it into a nested resource
+location. Anchors work for any resource type and any path depth.
+
+```mcfunction
+loot_table ./technical/loot as LOOT {}
+print(LOOT)
+```
+
+Anchors can be used as values, interpolated into strings, and reused when
+declaring or calling other resources.
+
+```mcfunction
+function ~/utils as utils:
+    function utils / "math" / "add":
+        scoreboard players add @s points 1
+
+advancement ./tech/root as ROOT {}
+predicate ROOT / "check" {}
+say f"prefix is {utils}"
+function utils / "math" / "add"
+```
+
+### Moving the path scope
+
+The `anchor` command changes the current path scope without creating a resource.
+Nested locations and anchors inside its block resolve against the new location.
+
+```mcfunction
+anchor demo:foo as foo:
+    function ~/bar as bar:
+        print(bar) # demo:foo/bar
+    function foo / "baz" as baz:
+        print(baz) # demo:foo/baz
+```
+
+The block itself emits no file. Commands and statements inside an `anchor` block
+are treated like regular top-level code and are inlined into the current file,
+while any resource declarations create files relative to the new scope.
+
+## Development
+
+```bash
+uv sync --dev
+uv run pytest
+uv run ruff check
+```

bolt_anchors-0.1.0/README.md

@@ -0,0 +1,86 @@
+# Bolt Anchors
+
+> Name resource locations and build nested paths in [bolt](https://github.com/mcbeet/beet/tree/main/packages/bolt).
+
+Bolt anchors let you bind a resource declaration to an identifier with the `as`
+clause. The anchor can then be used as a value or extended with `/` to build
+nested resource locations.
+
+## Installation
+
+```bash
+pip install bolt-anchors
+```
+
+## Configuration
+
+Add the plugin to your `beet.yml`/`beet.json` after `bolt`.
+
+```yaml
+pipeline:
+  - mecha
+
+require:
+  - bolt
+  - bolt_anchors
+```
+
+## Usage
+
+Bind an anchor when declaring any resource. The anchor holds the fully resolved
+resource location of the declaration.
+
+```mcfunction
+append function ~/foo as foo:
+    print(foo)
+    function foo / "bar":
+        say foo bar
+```
+
+`foo` resolves to `namespace:foo/foo` (relative to the current file and the
+enclosing declarations) and `foo / "bar"` extends it into a nested resource
+location. Anchors work for any resource type and any path depth.
+
+```mcfunction
+loot_table ./technical/loot as LOOT {}
+print(LOOT)
+```
+
+Anchors can be used as values, interpolated into strings, and reused when
+declaring or calling other resources.
+
+```mcfunction
+function ~/utils as utils:
+    function utils / "math" / "add":
+        scoreboard players add @s points 1
+
+advancement ./tech/root as ROOT {}
+predicate ROOT / "check" {}
+say f"prefix is {utils}"
+function utils / "math" / "add"
+```
+
+### Moving the path scope
+
+The `anchor` command changes the current path scope without creating a resource.
+Nested locations and anchors inside its block resolve against the new location.
+
+```mcfunction
+anchor demo:foo as foo:
+    function ~/bar as bar:
+        print(bar) # demo:foo/bar
+    function foo / "baz" as baz:
+        print(baz) # demo:foo/baz
+```
+
+The block itself emits no file. Commands and statements inside an `anchor` block
+are treated like regular top-level code and are inlined into the current file,
+while any resource declarations create files relative to the new scope.
+
+## Development
+
+```bash
+uv sync --dev
+uv run pytest
+uv run ruff check
+```

bolt_anchors-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "bolt-anchors"
+version = "0.1.0"
+description = "Name resource locations and build nested paths in bolt"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "beet>=0.119.0",
+    "bolt>=0.51.0",
+    "mecha>=0.106.0",
+]
+
+[dependency-groups]
+dev = [
+    "lectern>=0.35.0",
+    "pytest>=9.0.2",
+    "pytest-insta>=0.4.1",
+    "python-semantic-release>=9.21.0",
+    "ruff>=0.14.13",
+]
+
+[tool.semantic_release]
+major_on_zero = false
+allow_zero_version = true
+build_command = "uv build"
+version_variables = ["src/bolt_anchors/__init__.py:__version__"]
+version_toml = ["pyproject.toml:project.version"]
+commit_author = "github-actions <action@github.com>"
+
+[tool.semantic_release.publish]
+dist_glob_patterns = ["dist/*"]
+upload_to_vcs_release = true
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"

bolt_anchors-0.1.0/pyproject.toml.orig

@@ -0,0 +1,38 @@
+[project]
+name = "bolt-anchors"
+version = "0.1.0"
+description = "Name resource locations and build nested paths in bolt"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "beet>=0.119.0",
+    "bolt>=0.51.0",
+    "mecha>=0.106.0",
+]
+
+[dependency-groups]
+dev = [
+    "lectern>=0.35.0",
+    "pytest>=9.0.2",
+    "pytest-insta>=0.4.1",
+    "python-semantic-release>=9.21.0",
+    "ruff>=0.14.13",
+]
+
+[tool.semantic_release]
+major_on_zero = false
+allow_zero_version = true
+build_command = "uv build"
+
+version_variables = ["src/bolt_anchors/__init__.py:__version__"]
+version_toml = ["pyproject.toml:project.version"]
+commit_author = "github-actions <action@github.com>"
+
+[tool.semantic_release.publish]
+# This ensures it uses the build_command defined above
+dist_glob_patterns = ["dist/*"]
+upload_to_vcs_release = true
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"

bolt_anchors-0.1.0/src/bolt_anchors/__init__.py

@@ -0,0 +1,4 @@
+__version__ = "0.1.0"
+
+from .ast import AstAnchor as AstAnchor
+from .plugin import beet_default as beet_default

bolt_anchors-0.1.0/src/bolt_anchors/ast.py

@@ -0,0 +1,20 @@
+__all__ = [
+    "AstAnchor",
+]
+
+
+from dataclasses import dataclass
+from typing import Any
+
+from bolt import AstValue
+
+
+@dataclass(frozen=True, slots=True)
+class AstAnchor(AstValue):
+    """Ast node representing a named resource location anchor.
+
+    The anchor holds the fully resolved resource location of the declaration it
+    was created from. When used as a value it behaves like a plain string.
+    """
+
+    value: Any = ""

bolt_anchors-0.1.0/src/bolt_anchors/parse.py

@@ -0,0 +1,331 @@
+__all__ = [
+    "ANCHOR_COMMAND_IDENTIFIER",
+    "AnchorBlockParser",
+    "AnchorCommandTransformer",
+    "AnchorContext",
+    "AnchorIdentifierParser",
+    "AnchorRootParser",
+    "ResourceNameParser",
+]
+
+
+import re
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+from bolt.parse import IDENTIFIER_PATTERN
+from bolt.pattern import STRING_PATTERN
+from mecha import (
+    AstChildren,
+    AstCommand,
+    AstNode,
+    AstResourceLocation,
+    AstRoot,
+    CommandSpec,
+    CompilationDatabase,
+    MutatingReducer,
+    Parser,
+    get_stream_scope,
+    rule,
+)
+from mecha.contrib.nested_location import AstNestedLocation
+from mecha.contrib.relative_location import resolve_relative_location
+from mecha.utils import JsonQuoteHelper
+from tokenstream import Token, TokenStream, set_location
+
+from .ast import AstAnchor
+
+ANCHOR_COMMAND_IDENTIFIER = "anchor:name:commands"
+
+IDENTIFIER_REGEX = re.compile(IDENTIFIER_PATTERN)
+
+# Children that indicate that the current resource location argument introduces
+# a resource declaration with a body.
+DECLARATION_CHILDREN = {"commands", "content"}
+
+
+class AnchorContext:
+    """Tracks anchors and declaration roots while parsing a compilation unit."""
+
+    def __init__(self, database: CompilationDatabase):
+        self.database = database
+        self._unit: Any = None
+        self._bases: list[str] = []
+        self._anchored: list[bool] = []
+        self._scopes: list[dict[str, AstAnchor]] = [{}]
+        self._pending: tuple[tuple[str, ...], str, bool] | None = None
+
+    def reset_if_needed(self):
+        unit = self.database.current
+        if unit is not self._unit:
+            self._unit = unit
+            self._bases.clear()
+            self._anchored.clear()
+            self._scopes = [{}]
+            self._pending = None
+
+    def file_root(self) -> str | None:
+        unit = self.database.current
+        if unit is None:
+            return None
+        return self.database[unit].resource_location
+
+    def current_root(self) -> str | None:
+        if self._bases:
+            return self._bases[-1]
+        return self.file_root()
+
+    @contextmanager
+    def scope(self) -> Iterator[dict[str, AstAnchor]]:
+        self._scopes.append({})
+        try:
+            yield self._scopes[-1]
+        finally:
+            self._scopes.pop()
+
+    @contextmanager
+    def declaration(self, base: str, anchored: bool = False) -> Iterator[None]:
+        with self.scope():
+            self._bases.append(base)
+            self._anchored.append(anchored or self.is_anchored())
+            try:
+                yield
+            finally:
+                self._anchored.pop()
+                self._bases.pop()
+
+    def is_anchored(self) -> bool:
+        return any(self._anchored)
+
+    def bind(self, identifier: str, anchor: AstAnchor):
+        self._scopes[-1][identifier] = anchor
+
+    def lookup(self, identifier: str) -> AstAnchor | None:
+        for scope in reversed(self._scopes):
+            if anchor := scope.get(identifier):
+                return anchor
+        return None
+
+    def set_pending(self, name_scope: tuple[str, ...], base: str, anchored: bool):
+        self._pending = (name_scope, base, anchored)
+
+    def take_pending(self, name_scope: tuple[str, ...]) -> tuple[str, bool] | None:
+        pending = self._pending
+        if pending is None or pending[0] != name_scope:
+            return None
+        self._pending = None
+        return pending[1], pending[2]
+
+
+def is_declaration_name(spec: CommandSpec, scope: tuple[str, ...]) -> bool:
+    """Return whether the given argument scope introduces a resource declaration."""
+    tree = spec.tree.get(scope)
+    if tree is None or not tree.children:
+        return False
+    return any(name in DECLARATION_CHILDREN for name in tree.children)
+
+
+def resolve_nested_location(
+    node: AstNestedLocation, context: AnchorContext
+) -> AstResourceLocation:
+    """Resolve a nested location against the current declaration root."""
+    root = context.current_root()
+    if root is None:
+        raise node.emit_error(
+            ValueError("Can't resolve nested location without a root.")
+        )
+
+    namespace, resolved = resolve_relative_location(
+        node.path, root, include_root_file=True
+    )
+    resource_location = AstResourceLocation(
+        is_tag=node.is_tag, namespace=namespace, path=resolved
+    )
+    return set_location(resource_location, node)
+
+
+def canonical_location(node: AstResourceLocation, context: AnchorContext) -> str:
+    """Return the fully resolved resource location of a name node."""
+    if isinstance(node, AstNestedLocation):
+        return resolve_nested_location(node, context).get_canonical_value()
+    return node.get_canonical_value()
+
+
+ANCHOR_SYNTAX = {
+    "literal": None,
+    "identifier": IDENTIFIER_PATTERN,
+    "string": STRING_PATTERN,
+    "number": r"(?:0|[1-9]\d*)(?:\.\d+)?",
+    "slash": r"/",
+}
+
+
+def parse_anchor_path(
+    stream: TokenStream,
+    context: AnchorContext,
+    quote_helper: JsonQuoteHelper,
+) -> tuple[str, Token] | None:
+    """Parse an anchor followed by any number of path segments."""
+    with stream.syntax(**ANCHOR_SYNTAX):
+        token = stream.peek()
+
+        if token is None or not isinstance(token.value, str):
+            return None
+        if not IDENTIFIER_REGEX.fullmatch(token.value):
+            return None
+
+        anchor = context.lookup(token.value)
+        if anchor is None:
+            return None
+
+        start = stream.expect()
+        value = str(anchor.value)
+
+        while stream.get(("slash", "/")):
+            segment = stream.expect_any("string", "identifier", "number")
+            if segment.match("string"):
+                text = quote_helper.unquote_string(segment)
+            else:
+                text = segment.value
+            value = f"{value}/{text}"
+
+        return value, start
+
+
+@dataclass
+class ResourceNameParser:
+    """Parser for resource declaration names that supports anchors."""
+
+    parser: Parser
+    context: AnchorContext
+    spec: CommandSpec
+    quote_helper: JsonQuoteHelper = field(default_factory=JsonQuoteHelper)
+
+    def __call__(self, stream: TokenStream) -> AstNode:
+        self.context.reset_if_needed()
+
+        node = self.parse_anchor(stream)
+        if node is None:
+            node = self.parser(stream)
+
+        scope = get_stream_scope(stream)
+        if not is_declaration_name(self.spec, scope):
+            return node
+
+        anchored = scope[0] == "anchor"
+
+        if (anchored or self.context.is_anchored()) and isinstance(
+            node, AstNestedLocation
+        ):
+            node = resolve_nested_location(node, self.context)
+
+        base = canonical_location(node, self.context)
+
+        with stream.checkpoint() as commit:
+            if stream.get(("literal", "as")):
+                with stream.syntax(identifier=IDENTIFIER_PATTERN):
+                    token = stream.expect("identifier")
+                self.context.bind(
+                    token.value, set_location(AstAnchor(value=base), token)
+                )
+                commit()
+
+        self.context.set_pending(scope, base, anchored)
+        return node
+
+    def parse_anchor(self, stream: TokenStream) -> AstResourceLocation | None:
+        result = parse_anchor_path(stream, self.context, self.quote_helper)
+        if result is None:
+            return None
+
+        value, start = result
+        node = AstResourceLocation.from_value(value)
+        return set_location(node, start, stream.current)
+
+
+@dataclass
+class AnchorIdentifierParser:
+    """Parser for identifiers that resolves anchors to their resource location."""
+
+    parser: Parser
+    context: AnchorContext
+    quote_helper: JsonQuoteHelper = field(default_factory=JsonQuoteHelper)
+
+    def __call__(self, stream: TokenStream) -> AstNode:
+        self.context.reset_if_needed()
+
+        result = parse_anchor_path(stream, self.context, self.quote_helper)
+        if result is not None:
+            value, start = result
+            node = AstAnchor(value=value)
+            return set_location(node, start, stream.current)
+
+        return self.parser(stream)
+
+
+@dataclass
+class AnchorBlockParser:
+    """Parser that manages the anchor scope of a resource declaration body."""
+
+    parser: Parser
+    context: AnchorContext
+
+    def __call__(self, stream: TokenStream) -> Any:
+        self.context.reset_if_needed()
+
+        scope = get_stream_scope(stream)
+        pending = self.context.take_pending(scope[:-1])
+
+        if pending is None:
+            return self.parser(stream)
+
+        base, anchored = pending
+
+        with self.context.declaration(base, anchored):
+            return self.parser(stream)
+
+
+@dataclass
+class AnchorCommandTransformer(MutatingReducer):
+    """Inlines the body of `anchor` commands into the surrounding root."""
+
+    @rule(AstRoot)
+    def anchor_commands(self, node: AstRoot) -> AstRoot:
+        changed = False
+        commands: list[AstCommand] = []
+
+        for command in node.commands:
+            if (
+                isinstance(command, AstCommand)
+                and command.identifier == ANCHOR_COMMAND_IDENTIFIER
+                and command.arguments
+                and isinstance(body := command.arguments[-1], AstRoot)
+            ):
+                commands.extend(body.commands)
+                changed = True
+                continue
+
+            commands.append(command)
+
+        if changed:
+            return replace(node, commands=AstChildren(commands))
+
+        return node
+
+
+@dataclass
+class AnchorRootParser:
+    """Parser that inlines `anchor` commands right after parsing."""
+
+    parser: Parser
+    transformer: AnchorCommandTransformer = field(
+        default_factory=AnchorCommandTransformer
+    )
+
+    def __call__(self, stream: TokenStream) -> Any:
+        node = self.parser(stream)
+        if isinstance(node, AstRoot):
+            return self.transformer(node)
+        return node

bolt_anchors-0.1.0/src/bolt_anchors/plugin.py

@@ -0,0 +1,73 @@
+from beet import Context
+from bolt import Runtime
+from mecha import Mecha
+
+from .parse import (
+    AnchorBlockParser,
+    AnchorContext,
+    AnchorIdentifierParser,
+    AnchorRootParser,
+    ResourceNameParser,
+)
+
+__all__ = ["beet_default"]
+
+RESOURCE_NAME_PARSERS = (
+    "command:argument:minecraft:function",
+    "command:argument:minecraft:resource_location",
+)
+
+BLOCK_PARSERS = (
+    "command:argument:mecha:nested_root",
+    "command:argument:mecha:nested_json",
+)
+
+# `anchor <resource_location> [as <identifier>]:` moves the path scope and can
+# bind the location to an identifier without creating a resource.
+ANCHOR_COMMANDS = {
+    "type": "root",
+    "children": {
+        "anchor": {
+            "type": "literal",
+            "children": {
+                "name": {
+                    "type": "argument",
+                    "parser": "minecraft:resource_location",
+                    "children": {
+                        "commands": {
+                            "type": "argument",
+                            "parser": "mecha:nested_root",
+                            "executable": True,
+                        }
+                    },
+                }
+            },
+        }
+    },
+}
+
+
+def beet_default(ctx: Context):
+    ctx.inject(Runtime)
+    mc = ctx.inject(Mecha)
+
+    context = AnchorContext(mc.database)
+    spec = mc.spec
+
+    spec.add_commands(ANCHOR_COMMANDS)
+
+    for name in RESOURCE_NAME_PARSERS:
+        if parser := spec.parsers.get(name):
+            spec.parsers[name] = ResourceNameParser(parser, context, spec)
+
+    for name in BLOCK_PARSERS:
+        if parser := spec.parsers.get(name):
+            spec.parsers[name] = AnchorBlockParser(parser, context)
+
+    if parser := spec.parsers.get("bolt:identifier"):
+        spec.parsers["bolt:identifier"] = AnchorIdentifierParser(parser, context)
+
+    # Inline anchor bodies at parse time so that the cached ast already reflects
+    # the moved path scope and statements are evaluated like regular code.
+    if parser := spec.parsers.get("root"):
+        spec.parsers["root"] = AnchorRootParser(parser)