mapres 2.4.dev6__tar.gz → 3a2__tar.gz

mapres-3a2/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: mapres
+Version: 3a2
+Summary: A powerfull mapping utility
+Author: iFamished
+License: MIT
+Project-URL: Homepage, https://github.com/iFamished/mapres
+Project-URL: Documentation, https://github.com/iFamished/mapres
+Project-URL: Source, https://github.com/iFamished/mapres
+Project-URL: Issues, https://github.com/iFamished/mapres/issues
+Keywords: templating,automation,server-management
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# MapRes
+A powerful string-mapping utility for many use cases.
+
+## Installation
+```bash
+pip install mapres
+```

mapres-3a2/README.md

@@ -0,0 +1,7 @@
+# MapRes
+A powerful string-mapping utility for many use cases.
+
+## Installation
+```bash
+pip install mapres
+```

{mapres-2.4.dev6 → mapres-3a2}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mapres"
-version = "2.4-dev.6"
+version = "3-alpha.2"
 description = "A powerfull mapping utility"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -18,13 +18,8 @@ keywords = [
     "templating",
     "automation",
     "server-management",
-    "hungerlib",
-]
-dependencies = [
-    "requests",
-    "mcrcon",
-    "PyYaml",
 ]
+dependencies = []
 classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
@@ -42,10 +37,10 @@ classifiers = [
 text = "MIT"
 
 [project.urls]
-Homepage = "https://github.com/iFamishedX/mapres"
-Documentation = "https://github.com/iFamishedX/mapres"
-Source = "https://github.com/iFamishedX/mapres"
-Issues = "https://github.com/iFamishedX/mapres/issues"
+Homepage = "https://github.com/iFamished/mapres"
+Documentation = "https://github.com/iFamished/mapres"
+Source = "https://github.com/iFamished/mapres"
+Issues = "https://github.com/iFamished/mapres/issues"
 
 [tool.setuptools.packages.find]
 where = [

{mapres-2.4.dev6 → mapres-3a2}/src/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-3a2/src/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-3a2/src/mapres/datamap.py

@@ -0,0 +1,160 @@
+from dataclasses import dataclass, fields, is_dataclass
+
+# syntax identifiers
+class syntax:
+    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 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.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
+
+    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
+
+
+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__'] = {}
+        rules_obj = namespace.get('rules', None)
+
+        cls = type(cls.__name__, (DataMap,), namespace)
+
+        if rules_obj is not None:
+            setattr(cls, 'rules', rules_obj)
+
+        return dataclass(frozen=False)(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)
+
+datamap.config   = datamap(mode='config')
+datamap.dynamic  = datamap(mode='dynamic')
+datamap.callable = datamap(mode='callable')

mapres-3a2/src/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-3a2/src/mapres/exceptions.py

@@ -0,0 +1,8 @@
+class MapResError(Exception):
+    pass
+
+class MissingKeyError(MapResError):
+    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-3a2/src/mapres/layers.py

@@ -0,0 +1,54 @@
+class Layer:
+    """
+    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
+
+    def add(self, m):
+        self.maps.append(m)
+
+    def __iter__(self):
+        return iter(self.maps)
+
+
+class LayerStack:
+    """
+    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):
+        """
+        Yield all maps in priority order.
+        """
+        for layer in self.layers:
+            for m in layer:
+                yield m
+
+    def clone(self):
+        """
+        Return a shallow copy of the layerstack.
+        """
+        new = LayerStack()
+        new.layers = list(self.layers)
+        return new

{mapres-2.4.dev6 → mapres-3a2}/src/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-2.4.dev6 → mapres-3a2}/src/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")