mapres 2.4.dev6__py3-none-any.whl → 3a2__py3-none-any.whl

mapres/__init__.py

@@ -7,7 +7,7 @@ try:
 except PackageNotFoundError:
     __version__ = '0.0.0'
 
-from .resolver import MapResolver, res, setGlobalMaps
+from .resolver import MapResolver, res, rprint, setGlobalMaps
 from .datamap import DataMap, datamap, syntax
 from .layers import Layer, LayerStack
 
@@ -28,6 +28,10 @@ maps = SimpleNamespace(
     time = time,
 )
 
+utils = SimpleNamespace(
+    rprint = rprint,
+)
+
 __all__ = [
     # core modules
     'MapResolver',
@@ -39,6 +43,9 @@ __all__ = [
     'LayerStack',
     'setGlobalMaps',
 
+    # utils
+    'rprint',
+
     # maps
     'ColorMap',
     'ascii_colors',
@@ -49,4 +56,5 @@ __all__ = [
 
     # namespaces
     'maps',
+    'utils',
 ]

mapres/ast.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Node:
+    pass
+
+
+@dataclass
+class TemplateNode(Node):
+    children: list[Node]
+
+
+@dataclass
+class TextNode(Node):
+    text: str
+
+
+@dataclass
+class IdentNode(Node):
+    name: str
+    syntax: str
+
+
+@dataclass
+class CallNode(Node):
+    name: str          # outer identifier
+    arg: Node          # nested TemplateNode
+    syntax: str        # which delimiter type produced it

mapres/datamap.py

@@ -1,64 +1,160 @@
-import re
 from dataclasses import dataclass, fields, is_dataclass
 
+# syntax identifiers
 class syntax:
-    braces   = r'\{([^{}]+)\}'
-    dollars  = r'\$\{([^{}]+)\}'
-    angles   = r'<([^<>]+)>'
-    percents = r'%([^%]+)%'
+    braces         = 'braces'           # {{value}}
+    dollars        = 'dollars'          # ${value}
+    angles         = 'angles'           # <value>
+    percents       = 'percents'         # %value%
+    pipes          = 'pipes'            # |value|
+    colons         = 'colons'           # :value:
+    at_tags        = 'at_tags'          # @value@
+    hash_tags      = 'hash_tags'        # #value#
+    paren_dollars  = 'paren_dollars'    # $(value)
 
 
+# base datamap class
 @dataclass
 class DataMap:
-    '''Core datamap class. Contains logic used to make datamaps'''
-    __syntax__: str = syntax.braces
-    __mode__: str | None = None
+    '''
+    Core datamap class for mapres 3.
+
+    Responsibilities:
+        - hold fields
+        - optionally evaluate dynamic providers
+        - return a dict via as_map()
+
+    Syntax metadata (__syntax__) determines which delimiters
+    this map responds to (angle, brace, colon, percent, pipe, etc).
+
+    Mode metadata (__mode__) controls behavior:
+        - None: plain static map
+        - 'dynamic': values may be provided by callables/providers
+        - 'config': config-style maps (no dynamic evaluation)
+        - 'callable': map exposes callable methods for nested calls
+    '''
+    __syntax__: str = None
+    __mode__: str | None = None  # 'dynamic', 'config', 'callable', or None
+    __missing_key__: str = 'error'  # 'error', 'silent', 'placeholder', or 'raw'
+    __recursive__: bool = False
+    __max_depth__: int = 10
 
     def as_map(self):
+        '''
+        Convert datamap fields into a dictionary.
+        If mode='dynamic', evaluate provider functions.
+
+        Callable mode does NOT change as_map() behavior; methods are
+        used by the evaluator, not exported as map entries.
+        '''
         result = {}
+
+        # dataclass fields
         for f in fields(self):
-            if not f.init or f.name in ('__syntax__', '__mode__'):
+            if not f.init or f.name.startswith('__'):
                 continue
+
             val = getattr(self, f.name)
+
+            # dynamic provider support
             if self.__mode__ == 'dynamic':
                 providers = getattr(self, 'providers', None)
                 if isinstance(providers, dict) and f.name in providers:
                     val = providers[f.name]
                 if callable(val):
                     val = val()
+
             result[f.name] = val
+
+        # nested classes > nested dicts
+        for name, obj in self.__class__.__dict__.items():
+            if name.startswith('__'):
+                continue
+            if isinstance(obj, type):
+                result[name] = self._class_to_dict(obj)
+
         return result
 
-    @classmethod
-    def get_syntax(cls):
-        return getattr(cls, '__syntax__', syntax.braces)
+    def _class_to_dict(self, cls):
+        out = {}
+
+        if is_dataclass(cls):
+            dummy = cls()
+            for f in fields(dummy):
+                if not f.init:
+                    continue
+                out[f.name] = getattr(dummy, f.name)
+
+        for name, obj in cls.__dict__.items():
+            if name.startswith('__'):
+                continue
+            if isinstance(obj, type):
+                out[name] = self._class_to_dict(obj)
+
+        return out
 
 
-# decorator
-def datamap(
-    _cls = None,
-    *,
-    syntax: str = syntax.braces,
-    mode: bool | str | None = None,
-):
-    '''@datamap decorator with optional values'''
+def datamap(_cls=None, *, syntax=None, mode=None, missing_key=None, recursive=None, max_depth=None):
     def wrap(cls):
         cls.__syntax__ = syntax
         cls.__mode__ = mode
+        cls.__missing_key__ = missing_key or 'error'
+        cls.__recursive__ = recursive or False
+        cls.__max_depth__ = max_depth or 10
+
         namespace = dict(cls.__dict__)
         namespace['__dict__'] = {}
-        # preserve any rules class defined in the original namespace by attaching it to the generated class
         rules_obj = namespace.get('rules', None)
+
         cls = type(cls.__name__, (DataMap,), namespace)
-        # attach rules (if present) to the new class so validators can read them via the datamap class
+
         if rules_obj is not None:
             setattr(cls, 'rules', rules_obj)
+
         return dataclass(frozen=False)(cls)
-    return wrap if _cls is None else wrap(_cls)
 
+    if _cls is not None and isinstance(_cls, type):
+        return wrap(_cls)
+
+    return wrap
+
+
+# syntax-bound decorator factories
+class _SyntaxFactory:
+    def __init__(self, syntax_name):
+        self._syntax = syntax_name
+
+    def __call__(self, _cls=None, **kwargs):
+        if _cls is not None and isinstance(_cls, type):
+            return datamap(_cls, syntax=self._syntax)
+        return datamap(syntax=self._syntax, **kwargs)
+
+    def config(self, _cls=None, **kwargs):
+        if _cls is not None and isinstance(_cls, type):
+            return datamap(_cls, syntax=self._syntax, mode='config')
+        return datamap(syntax=self._syntax, mode='config', **kwargs)
+
+    def dynamic(self, _cls=None, **kwargs):
+        if _cls is not None and isinstance(_cls, type):
+            return datamap(_cls, syntax=self._syntax, mode='dynamic')
+        return datamap(syntax=self._syntax, mode='dynamic', **kwargs)
+
+    def callable(self, _cls=None, **kwargs):
+        if _cls is not None and isinstance(_cls, type):
+            return datamap(_cls, syntax=self._syntax, mode='callable')
+        return datamap(syntax=self._syntax, mode='callable', **kwargs)
+
+
+datamap.braces        = _SyntaxFactory(syntax.braces)
+datamap.dollars       = _SyntaxFactory(syntax.dollars)
+datamap.angles        = _SyntaxFactory(syntax.angles)
+datamap.percents      = _SyntaxFactory(syntax.percents)
+datamap.pipes         = _SyntaxFactory(syntax.pipes)
+datamap.colons        = _SyntaxFactory(syntax.colons)
+datamap.at_tags       = _SyntaxFactory(syntax.at_tags)
+datamap.hash_tags     = _SyntaxFactory(syntax.hash_tags)
+datamap.paren_dollars = _SyntaxFactory(syntax.paren_dollars)
 
-# decorator shortcuts
-datamap.braces = datamap(syntax=syntax.braces)
-datamap.angles = datamap(syntax=syntax.angles)
-datamap.dollars = datamap(syntax=syntax.dollars)
-datamap.percents = datamap(syntax=syntax.percents)
+datamap.config   = datamap(mode='config')
+datamap.dynamic  = datamap(mode='dynamic')
+datamap.callable = datamap(mode='callable')

mapres/evaluator.py

@@ -0,0 +1,212 @@
+from .ast import TemplateNode, TextNode, IdentNode, CallNode
+from .tokenizer import Tokenizer
+from .parser import Parser
+from .exceptions import MapResError, MissingKeyError
+
+
+class EvaluationError(MapResError):
+    pass
+
+
+class Evaluator:
+    def __init__(self, layerstack, ctx=None, missing_key_mode: str = 'error'):
+        '''
+        layerstack: LayerStack instance
+        ctx:        dict used as highest-priority map
+        missing_key_mode:
+            - 'error'       → raise MissingKeyError
+            - 'silent'      → return raw token unchanged
+            - 'placeholder' → return <missing:key>
+            - 'raw'         → return raw token unchanged (alias of 'silent' at token level)
+        '''
+        self.layerstack = layerstack
+        self.ctx = ctx or {}
+        self._seen = set()  # cycle detection
+        self.missing_key_mode = missing_key_mode
+
+    # public api
+    def evaluate(self, node):
+        return self._eval(node)
+
+    # internal dispatch
+    def _eval(self, node):
+        if isinstance(node, TemplateNode):
+            return self._eval_template(node)
+
+        if isinstance(node, TextNode):
+            return node.text
+
+        if isinstance(node, IdentNode):
+            return self._eval_ident(node)
+
+        if isinstance(node, CallNode):
+            return self._eval_call(node)
+
+        raise EvaluationError(f'Unknown AST node: {node}')
+
+    # re-resolve
+    def _re_resolve(self, text: str) -> str:
+        tokens = Tokenizer(text).tokenize()
+        ast = Parser(tokens).parse()
+        return self.evaluate(ast)
+
+    # template
+    def _eval_template(self, node: TemplateNode):
+        parts = []
+        for child in node.children:
+            parts.append(self._eval(child))
+        out = ''.join(parts)
+
+        # per-map recursion (syntax-scoped)
+        recursive_maps = [
+            m for m in self.layerstack.all_maps()
+            if getattr(m, '__recursive__', False) is True
+        ]
+
+        if not recursive_maps:
+            return out
+
+        max_depth = max(getattr(m, '__max_depth__', 10) for m in recursive_maps)
+
+        seen = set()
+        depth = 0
+
+        while depth < max_depth:
+            new_out = self._re_resolve(out)
+
+            if new_out == out:
+                break
+
+            if new_out in seen:
+                raise EvaluationError('Cycle detected in recursive map resolution')
+
+            seen.add(new_out)
+            out = new_out
+            depth += 1
+
+        return out
+
+    # identifier
+    def _eval_ident(self, node: IdentNode):
+        name = node.name
+
+        # cycle detection
+        if name in self._seen:
+            raise EvaluationError(f'Cycle detected in identifier \'{name}\'')
+        self._seen.add(name)
+
+        parts = name.split('.')
+
+        # 1. ctx first
+        val = self._lookup_hierarchical(self.ctx, parts)
+        if val is not None:
+            self._seen.remove(name)
+            return str(val)
+
+        # 2. syntax-bound maps
+        for m in self.layerstack.all_maps():
+            if getattr(m, '__syntax__', None) not in (None, node.syntax):
+                continue
+
+            d = self._map_to_dict(m)
+            val = self._lookup_hierarchical(d, parts)
+            if val is not None:
+                self._seen.remove(name)
+                return str(val)
+
+        self._seen.remove(name)
+        return self._handle_missing_ident(node)
+
+    # call (nested token)
+    def _eval_call(self, node: CallNode):
+        outer = node.name
+
+        if outer in self._seen:
+            raise EvaluationError(f'Cycle detected in call \'{outer}\'')
+        self._seen.add(outer)
+
+        arg_value = self._eval(node.arg)
+        parts = [outer, arg_value]
+
+        # ctx first
+        val = self._lookup_hierarchical(self.ctx, parts)
+        if val is not None:
+            self._seen.remove(outer)
+            return str(val)
+
+        # syntax-bound maps
+        for m in self.layerstack.all_maps():
+            if getattr(m, '__syntax__', None) not in (None, node.syntax):
+                continue
+
+            d = self._map_to_dict(m)
+            val = self._lookup_hierarchical(d, parts)
+            if val is not None:
+                self._seen.remove(outer)
+                return str(val)
+
+        self._seen.remove(outer)
+        return self._handle_missing_call(node, arg_value)
+
+    # helpers
+    def _map_to_dict(self, m):
+        if hasattr(m, 'as_map'):
+            return m.as_map()
+        if isinstance(m, dict):
+            return m
+        raise EvaluationError(f'Invalid map object: {m}')
+
+    def _lookup_hierarchical(self, root, parts):
+        cur = root
+        for p in parts:
+            if not isinstance(cur, dict):
+                return None
+            if p not in cur:
+                return None
+            cur = cur[p]
+        return cur
+
+    # missing-key handling (token-level)
+    def _delims_for_syntax(self, syntax_name: str):
+        table = {
+            'angles': ('<', '>'),
+            'braces': ('{{', '}}'),
+            'dollars': ('${', '}'),
+            'percents': ('%', '%'),
+            'pipes': ('|', '|'),
+            'colons': (':', ':'),
+        }
+        return table.get(syntax_name, ('<', '>'))
+
+    def _handle_missing_ident(self, node: IdentNode):
+        name = node.name
+        open_, close_ = self._delims_for_syntax(node.syntax)
+        raw_token = f'{open_}{name}{close_}'
+
+        mode = self.missing_key_mode or 'error'
+
+        if mode in ('silent', 'raw'):
+            # token-level fallback: leave the unresolved token as-is
+            return raw_token
+
+        if mode == 'placeholder':
+            return f'<missing:{name}>'
+
+        # default: error
+        raise MissingKeyError(name, token=raw_token)
+
+    def _handle_missing_call(self, node: CallNode, arg_value: str):
+        outer = node.name
+        open_, close_ = self._delims_for_syntax(node.syntax)
+        raw_token = f'{open_}{outer}({arg_value}){close_}'
+        key_repr = f'{outer}({arg_value})'
+
+        mode = self.missing_key_mode or 'error'
+
+        if mode in ('silent', 'raw'):
+            return raw_token
+
+        if mode == 'placeholder':
+            return f'<missing:{key_repr}>'
+
+        raise MissingKeyError(key_repr, token=raw_token)

mapres/exceptions.py

@@ -2,7 +2,7 @@ class MapResError(Exception):
     pass
 
 class MissingKeyError(MapResError):
-    pass
-
-class MapSyntaxError(MapResError):
-    pass
+    def __init__(self, key: str, token: str | None = None):
+        super().__init__(f"Missing key {key!r}")
+        self.key = key
+        self.token = token or key

mapres/layers.py

@@ -1,7 +1,10 @@
 class Layer:
-    '''Holds a map with a priority'''
-    def __init__(self, name, maps=None, priority=0):
-        self.name = name
+    """
+    A single layer containing one or more maps.
+    Priority determines resolution order.
+    Lower priority = earlier lookup.
+    """
+    def __init__(self, maps=None, priority=0):
         self.maps = maps or []
         self.priority = priority
 
@@ -13,31 +16,39 @@ class Layer:
 
 
 class LayerStack:
-    '''Manages ordered layers'''
-    def __init__(self, layers=None):
-        self.layers = {}
-        if layers:
-            for layer in layers:
-                self.layers[layer.name] = layer
-
-    def add_layer(self, layer):
-        self.layers[layer.name] = layer
-
-    def remove_layer(self, name):
-        if name in self.layers:
-            del self.layers[name]
-
-    def get_layer(self, name):
-        return self.layers.get(name)
-
-    def clone(self):
-        return LayerStack(list(self.layers.values()))
+    """
+    A simple ordered list of layers.
+    No names, no dicts, no complexity.
+    Just priority-sorted layers.
+    """
+    def __init__(self):
+        self.layers = []  # list of Layer objects
+
+    def add_layer(self, maps, priority=0):
+        """
+        Add a new layer containing one or more maps.
+        maps: datamap instance, datamap class, or dict
+        priority: lower = earlier lookup
+        """
+        layer = Layer(
+            maps=[maps] if not isinstance(maps, list) else maps,
+            priority=priority
+        )
+        self.layers.append(layer)
+        self.layers.sort(key=lambda l: l.priority)
 
     def all_maps(self):
-        ordered = sorted(self.layers.values(), key=lambda l: l.priority)
-        for layer in ordered:
+        """
+        Yield all maps in priority order.
+        """
+        for layer in self.layers:
             for m in layer:
                 yield m
 
-    def __iter__(self):
-        return self.all_maps()
+    def clone(self):
+        """
+        Return a shallow copy of the layerstack.
+        """
+        new = LayerStack()
+        new.layers = list(self.layers)
+        return new

mapres/maps/color.py

@@ -1,6 +1,6 @@
-from mapres.datamap import datamap, syntax
+from mapres.datamap import datamap
 
-@datamap(syntax=syntax.angles) # produces <>
+@datamap.angles
 class ColorMap:
     black: str = '\033[30m'
     dark_blue: str = '\033[34m'
@@ -22,13 +22,8 @@ class ColorMap:
     bold: str = '\033[1m'
     italic: str = '\033[3m'
 
-    def as_dict(self):
-        return {f'<{k}>': getattr(self, k) for k in self.__dataclass_fields__}
-
-# ASCII color map
 ascii_colors = ColorMap()
 
-# Minecraft color map
 mc_colors = ColorMap(
     black='§0',
     dark_blue='§1',
@@ -51,7 +46,6 @@ mc_colors = ColorMap(
     italic='§o'
 )
 
-# Color strip map
 strip_colors = ColorMap(
     black='',
     dark_blue='',
@@ -72,4 +66,4 @@ strip_colors = ColorMap(
     reset='',
     bold='',
     italic=''
-)
+)

mapres/maps/time.py

@@ -1,6 +1,6 @@
 from datetime import datetime, timezone
 from zoneinfo import ZoneInfo
-from mapres.datamap import datamap, syntax
+from mapres.datamap import datamap
 
 
 def safe_zoneinfo(tz: str):
@@ -10,7 +10,7 @@ def safe_zoneinfo(tz: str):
         return timezone.utc
 
 
-@datamap(syntax=syntax.percents, mode='dynamic')
+@datamap.percents.dynamic
 class TimeMap:
     _default_tz = safe_zoneinfo("America/Chicago")