1"""
  2High-level utilities for traversing and manipulating Rusty Object Notation (RON)
  3data.
  4
  5This module features `RonObject` and semi-internal parser types (`RonValue`).
  6Although it is possible to use primitive syntax types directly, you will likely
  7prefer using `RonObject`'s `__getitem__` implementation, especially for nested
  8lookups. It abstracts away specific key and container types, allowing you to use
  9plain Python objects to access the data.
 10
 11To access the raw syntax leaves, `RonObject` exposes a family of `expect_`
 12methods (e.g., `expect_int`, `expect_map`).
 13
 14These methods assert that the value
 15matches the expected type, raising a `ValueError` if it does not (which also
 16makes type checkers happy).
 17"""
 18
 19from __future__ import annotations
 20
 21from dataclasses import dataclass
 22from typing import Any, Callable, Literal, TypeGuard, override
 23
 24from frozendict import frozendict
 25
 26type RonValue = (
 27    RonStruct
 28    | RonSeq
 29    | RonMap
 30    | RonOptional
 31    | RonChar
 32    | int
 33    | float
 34    | str
 35    | bool
 36)
 37"""
 38@public Union of all supported RON types, including primitives and containers.
 39"""
 40
 41
 42def is_ron_value(val: Any) -> TypeGuard[RonValue]:
 43    """
 44    Type-guard that checks that your value is indeed of `RonValue`
 45
 46    Use with typecheckers.
 47    """
 48    # simple top-level check
 49    if isinstance(
 50        val,
 51        (
 52            RonStruct,
 53            RonSeq,
 54            RonMap,
 55            RonOptional,
 56            RonChar,
 57            int,
 58            float,
 59            str,
 60            bool,
 61        ),
 62    ):
 63        return True
 64
 65    return False
 66
 67
 68@dataclass
 69class RonObject:
 70    """
 71    A wrapper around `RonValue` enabling convenient traversal.
 72
 73    It allows you to access nested fields using standard Python types as keys,
 74    automatically handling the necessary conversions to RON-specific types.
 75
 76    Read `RonObject.__getitem__`() docs for more.
 77    """
 78
 79    v: RonValue
 80    """@private field holding the internal value"""
 81
 82    def expect_map(self) -> RonMap:
 83        """Returns an underlying map or **raises** a `ValueError`"""
 84        if isinstance(self.v, RonMap):
 85            return self.v
 86        raise ValueError(f"Value '{self}' is not a map")
 87
 88    def expect_struct(self) -> RonStruct:
 89        """Returns an underlying struct or **raises** a `ValueError`"""
 90        if isinstance(self.v, RonStruct):
 91            return self.v
 92        raise ValueError(f"Value '{self}' is not a struct")
 93
 94    def expect_int(self) -> int:
 95        """Returns an underlying int or **raises** a `ValueError`"""
 96        if isinstance(self.v, int):
 97            return self.v
 98        raise ValueError(f"Value '{self}' is not an integer")
 99
100    def expect_float(self) -> float:
101        """Returns an underlying float or **raises** a `ValueError`"""
102        if isinstance(self.v, float):
103            return self.v
104        raise ValueError(f"Value '{self}' is not a float")
105
106    def expect_str(self) -> str:
107        """Returns an underlying str or **raises** a `ValueError`"""
108        if isinstance(self.v, str):
109            return self.v
110        raise ValueError(f"Value '{self}' is not a string")
111
112    def expect_bool(self) -> bool:
113        """Returns an underlying bool or **raises** a `ValueError`"""
114        if isinstance(self.v, bool):
115            return self.v
116        raise ValueError(f"Value '{self}' is not a boolean")
117
118    def expect_tuple(self) -> RonSeq:
119        """Returns an underlying tuple or **raises** a `ValueError`"""
120        if isinstance(self.v, RonSeq) and self.v.kind == "tuple":
121            return self.v
122        raise ValueError(f"Value '{self}' is not a ron tuple")
123
124    def expect_list(self) -> RonSeq:
125        """Returns an underlying list or **raises** a `ValueError`"""
126        if isinstance(self.v, RonSeq) and self.v.kind == "list":
127            return self.v
128        raise ValueError(f"Value '{self}' is not a ron list")
129
130    def maybe(self) -> RonObject | None:
131        """
132        Transposes a RON optional into Python `Optional`.
133
134        # Returns
135        `RonObject` | `None`: The inner value, if present.
136
137        # Raises
138        - `ValueError`: If the value is not an option.
139
140        Examples:
141        >>> from ron import parse_ron
142        >>> obj = parse_ron('Some(42)')
143        >>> result = obj.maybe()
144        >>> assert result is not None
145        >>> result.expect_int()
146        42
147
148        >>> obj = parse_ron('None')
149        >>> obj.maybe() is None
150        True
151
152        >>> # Raises error if called on non-option types
153        >>> obj = parse_ron('42')
154        >>> obj.maybe()
155        Traceback (most recent call last):
156            ...
157        ValueError: Value ... is not an option
158        """
159        if isinstance(self.v, RonOptional):
160            return RonObject(self.v.value) if self.v.value is not None else None
161        raise ValueError(f"Value '{self}' is not an option")
162
163    def __getitem__(
164        self,
165        item: RonValue
166        | tuple[RonValue, ...]
167        | list[RonValue]
168        | dict[Any, Any]
169        | None
170        | RonObject,
171    ) -> RonObject:
172        """
173        @public Escape hatch to traverse the RON object.
174
175        This method inspects the underlying container (Map, Struct, or Sequence)
176        and (if needed) automatically converts the provided `item` into the
177        correct RON type required for the lookup.
178
179        For example, passing a `str` to a struct will look up that field name,
180        and passing a `tuple` to a map will convert it to a `RonSeq` key.
181
182        # Returns
183        `RonObject`: A new wrapper around the retrieved value, enabling
184        chained access.
185
186        # Raises
187        - `TypeError`: If the value is not a container, or if the key type
188            is invalid for the current container.
189        - `KeyError`: If the item is missing (for Maps and Structs).
190        - `IndexError`: If the index is out of bounds (for Sequences).
191
192        Examples:
193        >>> from ron import parse_ron
194
195        >>> # Struct access: use string keys for field names
196        >>> obj = parse_ron('( id: 42, name: "foo" )')
197        >>> obj["id"].expect_int()
198        42
199
200        >>> # Map access: use standard Python literals
201        >>> obj = parse_ron('{ "key": "value" }')
202        >>> obj["key"].expect_str()
203        'value'
204
205        >>> # Sequence access: use integer indices
206        >>> obj = parse_ron('[10, 20, 30]')
207        >>> obj[1].expect_int()
208        20
209
210        >>> # Complex keys: Python tuples are automatically coerced to RON tuples
211        >>> obj = parse_ron('{ (1, "a"): "found" }')
212        >>> obj[(1, "a")].expect_str()
213        'found'
214
215        >>> # Nested chaining
216        >>> obj = parse_ron('( config: (version: 1) )')
217        >>> obj["config"]["version"].expect_int()
218        1
219
220        >>> # Unit structs
221        >>> obj = parse_ron('{ King: "Crown" }')
222        >>> obj["King"].expect_str()
223        'Crown'
224
225        >>> # And even optionals
226        >>> obj = parse_ron('{ Some("King"): "Crown", None: "Hat" }')
227        >>> obj["King"].expect_str()
228        'Crown'
229        >>> obj[None].expect_str()
230        'Hat'
231
232        >>> # Nested coercion doesn't work for now
233        >>> obj = parse_ron('{ Some(King): "Crown", None: "Hat" }')
234        >>> obj["King"].expect_str() # doctest: +IGNORE_EXCEPTION_DETAIL
235        Traceback (most recent call last):
236            ...
237        KeyError: ... coerced as Some("King"), not Some(King)
238
239        >>> # If you need nested keys, parse them
240        >>> obj[parse_ron("Some(King)")].expect_str()
241        'Crown'
242        """
243
244        val = self.v
245        if isinstance(item, RonObject):
246            item = item.v
247
248        # 1. Pick a proper container (and its key type)
249        key = None
250        if isinstance(val, RonStruct):
251            container = val._fields
252            if type(container) is frozendict:
253                key = container.key(0)
254        elif isinstance(val, RonMap):
255            container = val.entries
256            key = container.key(0)
257        elif isinstance(val, RonSeq):
258            container = val.elements
259        elif isinstance(val, tuple):
260            container = val
261        else:
262            raise TypeError(f"{self}[{item}]")
263
264        # 2. Convert index to a proper ron type, if needed
265        if isinstance(item, tuple):
266            match key:
267                case RonSeq():
268                    item = RonSeq(elements=item, kind="tuple")
269                case RonStruct(name):
270                    item = RonStruct(name, _fields=item, spans=None)
271                case _:
272                    raise TypeError(f"{self}[{item}]: Unexpected index type")
273        if isinstance(item, list):
274            item = RonSeq(elements=tuple(item), kind="list")
275        if isinstance(item, dict):
276            match key:
277                case RonMap():
278                    item = RonMap(entries=frozendict(item))
279                case RonStruct(name):
280                    item = RonStruct(name, _fields=frozendict(item), spans=None)
281                case _:
282                    raise TypeError(f"{self}[{item}]: Unexpected index type")
283
284        # Handle optionals and unit structs
285        if type(key) is RonOptional and type(item) is not RonOptional:
286            item = RonOptional(item)
287        elif type(key) is RonStruct and type(item) is str:
288            item = RonStruct(item, _fields=tuple(), spans=None)
289        elif item is None:
290            item = RonOptional(None)
291
292        # 3. Do the index magic and wrap in RonObject to prolong the chain
293        if isinstance(container, frozendict):
294            try:
295                result = container[item]
296            except (KeyError, TypeError):
297                raise KeyError(
298                    f"container={container}, key={item}, heuristic_key={key}"
299                )
300            return RonObject(result)
301        elif isinstance(container, tuple):
302            if not isinstance(item, int):
303                raise TypeError(
304                    f"List indices must be integers, got {type(item).__name__}"
305                )
306            result = container[item]
307            return RonObject(result)
308        else:
309            raise TypeError(
310                f"Value of type {type(val).__name__} is not subscriptable"
311            )
312
313
314@dataclass(frozen=True)
315class SpanPoint:
316    """
317    Represents span point, the beginning or the end of the element.
318    """
319
320    ch: int
321    """
322    Character index in a stream
323    """
324    line: int
325    """
326    Line number, starts at 1
327    """
328    column: int
329    """
330    Column number, starts at 1
331    """
332
333
334type Span = tuple[SpanPoint, SpanPoint]
335"""
336@private
337"""
338
339
340@dataclass(frozen=True)
341class RonStruct:
342    """
343    Represents RON structures.
344
345    Includes:
346    - named structs like `Weapon(str: 5)`
347    - anon structs like `(str: 5)`
348    - structs with named fields (see above)
349    - structs with unnamed fields like `Weapon(5)`
350    - unit structs like ... `Weapon`?
351    - enums like `RBG(r: 255, g: 0, b: 0)` (yes, same syntax as structs)
352    - unit enums like `Red` (more useful than unit structs)
353
354    Use `RonStruct.as_dict` or `RonStruct.as_tuple` to get fields.
355
356    **Careful**, they will panic if you try to get the wrong thing.
357
358    And if you, for some reason, need a name, there's `RonStruct.name`
359    (might be `None`).
360
361
362    Oh, and it has spans. See `RonStruct.spans`.
363    """
364
365    name: str | None
366    """
367    Struct's name, if present. Simple as that.
368    """
369    _fields: frozendict[RonValue, RonValue] | tuple[RonValue, ...]
370    """
371    @private
372    """
373
374    spans: frozendict[RonValue, Span] | tuple[Span, ...] | None
375    """
376    Represents spans for struct field *values* as (start, end).
377    See `SpanPoint`.
378    """
379
380    @property
381    def as_dict(self) -> frozendict[RonValue, RonValue]:
382        """Returns the underlying dictionary for structs with named fields.
383
384        **Raises** a `ValueError` otherwise.
385        """
386        if isinstance(self._fields, frozendict):
387            return self._fields
388        raise ValueError(
389            f"Struct '{self.name}' is a Tuple-Struct, not a Named-Struct"
390        )
391
392    @property
393    def as_tuple(self) -> tuple[RonValue, ...]:
394        """Returns the underlying tuple for structs with unnamed fields.
395
396        **Raises** a ValueError otherwise.
397        """
398        if isinstance(self._fields, tuple):
399            return self._fields
400        raise ValueError(
401            f"Struct '{self.name}' is a Named-Struct, not a Tuple-Struct"
402        )
403
404
405@dataclass(frozen=True)
406class RonSeq:
407    """
408    Represents all sort of sequences: tuple `()`, lists `[]`, sets `[]`.
409
410    Use `RonSeq.as_tuple` to get said sequence as a `tuple`.
411
412    If you need such info, for some reason, you can use `RonSeq.kind` to
413    find out whether it was parsed from `()` or `[]`.
414    """
415
416    elements: tuple[RonValue, ...]
417    """
418    @private
419    """
420
421    kind: Literal["list", "tuple"]
422
423    @property
424    def as_tuple(self) -> tuple[RonValue, ...]:
425        """Returns the underlying sequence as a tuple."""
426        return self.elements
427
428
429@dataclass(frozen=True)
430class RonMap:
431    """
432    Represents a RON map, you can think of it as python's dict pretty much.
433
434    Use `RonMap.as_dict` to get said dict as `frozendict`
435    """
436
437    entries: frozendict[RonValue, RonValue]
438    """
439    @private
440    """
441
442    @property
443    def as_dict(self) -> frozendict[RonValue, RonValue]:
444        """Returns the underlying mapping as a `frozendict`."""
445        return self.entries
446
447
448@dataclass(frozen=True)
449class RonOptional:
450    """
451    Represents things like `Some("value")` or None.
452
453    Unlike in Python, that's a real object, but feel free to snatch it
454    with `RonOptional.value`.
455
456    Or use fancy methods to work with the object like `RonOptional.map`.
457    """
458
459    value: RonValue | None
460
461    def unwrap(self) -> RonValue:
462        """
463        Asserts that value is present, and returns it.
464
465        **Raises** a `ValueError` otherwise.
466        """
467        if self.value is None:
468            raise ValueError("tried to call unwrap() on None value")
469        return self.value
470
471    def unwrap_or(self, o: RonValue) -> RonValue:
472        """
473        Return a value if present, or return a fallback.
474        """
475        if self.value is None:
476            return o
477        return self.value
478
479    def map(self, f: Callable[[RonValue], RonValue]):
480        """
481        Apply a function to the underlying value, if present.
482
483        If not, nothing happens.
484        """
485        if self.value is None:
486            return None
487        return f(self.value)
488
489
490@dataclass(frozen=True)
491class RonChar:
492    """
493    Represents characters, like 'a'.
494    """
495
496    value: str
497
498    @override
499    def __str__(self) -> str:
500        return self.value