yini-parser 0.1.0a1__py3-none-any.whl

yini_parser/__init__.py

@@ -0,0 +1,14 @@
+# src/yini_parser/__init__.py
+"""Public API for the yini_parser package."""
+
+from .api import YiniParseError, load, loads
+
+"""
+So users can write:
+from yini_parser import load, loads, YiniParseError
+
+Instead:
+from yini_parser.api import load, loads, YiniParseError
+"""
+
+__all__ = ["YiniParseError", "load", "loads"]

yini_parser/api/__init__.py

@@ -0,0 +1,13 @@
+# src/yini_parser/api/__init__.py
+"""Public API helpers for parsing YINI documents."""
+
+from .errors import YiniParseError
+from .warnings import YiniParseWarning
+from .load import load, loads
+
+__all__ = [
+    "load",
+    "loads",
+    "YiniParseError",
+    "YiniParseWarning",
+]

yini_parser/api/errors.py

@@ -0,0 +1,15 @@
+# src/yini_parser/api/errors.py
+
+class YiniParseError(Exception):
+    def __init__(self, message: str, line: int | None = None, column: int | None = None):
+        super().__init__(message)
+        self.message = message
+        self.line = line
+        self.column = column
+
+    def __str__(self) -> str:
+        if self.line is not None and self.column is not None:
+            return f"{self.message} (line {self.line}, column {self.column})"
+        if self.line is not None:
+            return f"{self.message} (line {self.line})"
+        return self.message

yini_parser/api/load.py

@@ -0,0 +1,55 @@
+# src/yini_parser/api/load.py
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from antlr4 import CommonTokenStream, FileStream, InputStream
+
+from yini_parser.api.errors import YiniParseError
+
+from ..core.yini_builder_visitor import YiniBuilderVisitor
+from ..grammar.generated.YiniLexer import YiniLexer
+from ..grammar.generated.YiniParser import YiniParser
+
+
+def loads(text: str, strict: bool=False) -> dict[str, Any]:
+    """
+    Parse YINI text and return the resulting Python dictionary.
+    """
+
+    input_stream = InputStream(text)
+    return _parse_input_stream(input_stream, strict=strict)
+
+
+def load(path: str, strict: bool=False) -> dict[str, Any]:
+    """
+    Parse a YINI file from disk and return the resulting Python dictionary.
+    """
+
+    file_path = Path(path)
+    input_stream = FileStream(str(file_path), encoding="utf-8")
+    return _parse_input_stream(input_stream, strict=strict)
+
+
+def _parse_input_stream(
+        input_stream: InputStream | FileStream,
+        strict: bool
+    ) -> dict[str, Any]:
+    lexer = YiniLexer(input_stream)
+    stream = CommonTokenStream(lexer)
+    parser = YiniParser(stream)
+
+    tree = parser.yini()
+
+    if parser.getNumberOfSyntaxErrors() > 0:
+#        raise ValueError(f"Failed to parse YINI input: {parser.getNumberOfSyntaxErrors()} syntax error(s).")
+        raise YiniParseError(f"Failed to parse YINI input: {parser.getNumberOfSyntaxErrors()} syntax error(s).")
+    
+    visitor = YiniBuilderVisitor(strict=strict)
+    result = visitor.visit(tree)
+
+    if not isinstance(result, dict):
+        raise TypeError(f"Expected parsed result to be a dict, got {type(result).__name__}.")
+
+    return result

yini_parser/api/warnings.py

@@ -0,0 +1,53 @@
+# src/yini_parser/api/warnings.py
+
+from __future__ import annotations
+
+
+class YiniParseWarning(Warning):
+    """
+    Warning raised for non-fatal YINI parse issues.
+
+    A YiniParseWarning represents a problem that was detected while parsing,
+    but which does not prevent a result from being produced.
+
+    Typical examples:
+    - Duplicate keys ignored in lenient mode.
+    - Duplicate sections ignored in lenient mode.
+    - Key/section name collisions handled by lenient-mode policy.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        line: int | None = None,
+        column: int | None = None,
+        code: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.line = line
+        self.column = column
+        self.code = code
+
+    def __str__(self) -> str:
+        location = self._format_location()
+
+        if self.code is not None and location is not None:
+            return f"{self.message} [{self.code}] {location}"
+
+        if self.code is not None:
+            return f"{self.message} [{self.code}]"
+
+        if location is not None:
+            return f"{self.message} {location}"
+
+        return self.message
+
+    def _format_location(self) -> str | None:
+        if self.line is not None and self.column is not None:
+            return f"(line {self.line}, column {self.column})"
+
+        if self.line is not None:
+            return f"(line {self.line})"
+
+        return None

yini_parser/core/__init__.py

@@ -0,0 +1 @@
+# This file marks this directory as a Python package so it can be imported (as a package/module).

yini_parser/core/section_headers.py

@@ -0,0 +1,134 @@
+# src/yini_parser/core/section_headers.py
+from ..api.errors import YiniParseError
+from ..utils.text import strip_backticks
+
+def parse_section_head(
+    raw_text: str,
+    *,
+    line: int | None = None,
+    column: int | None = None,
+) -> tuple[int, str]:
+    """
+    Parses a SECTION_HEAD token text like:
+        "^ App\\n"
+        "^^ Server\\n"
+        "^7 DeepSection\\n"
+
+    Returns:
+        (level, name)
+    """
+
+    text = raw_text.strip()
+    text = text.splitlines()[0].strip()
+    text = _strip_section_tail_comment(text)
+
+    if not text:
+        raise YiniParseError(
+            "Invalid section header: the header is empty.",
+            line=line,
+            column=column,
+        )
+
+    marker = text[0]
+
+    if marker not in {"^", "<", "§"}:
+        raise YiniParseError(
+            f"Invalid section header: {marker!r} is not a valid section marker. "
+            "Use one of: '^', '<', or '§'.",
+            line=line,
+            column=column,
+        )
+
+    # Numeric shorthand form, for example: ^7 SectionName.
+    if len(text) >= 2 and text[1].isdigit():
+        i = 1
+        j = i
+
+        while j < len(text) and text[j].isdigit():
+            j += 1
+
+        level_text = text[i:j]
+
+        try:
+            level = int(level_text)
+        except ValueError:
+            raise YiniParseError(
+                f"Invalid section level: {level_text!r} is not a valid number.",
+                line=line,
+                column=column,
+            ) from None
+
+        name = text[j:].strip()
+
+    else:
+        # Repeated/basic form, for example:
+        #   ^^ Section
+        #   ^_^ Section
+        #   ^_^_^ Section
+        i = 0
+        level = 0
+        expecting_marker = True
+
+        while i < len(text):
+            ch = text[i]
+
+            if ch == marker:
+                level += 1
+                expecting_marker = False
+                i += 1
+                continue
+
+            if ch == "_" and not expecting_marker:
+                if i + 1 < len(text) and text[i + 1] == marker:
+                    expecting_marker = True
+                    i += 1
+                    continue
+
+            break
+
+        name = text[i:].strip()
+
+    if not name:
+        raise YiniParseError(
+            f"Missing section name after section marker {marker!r}.",
+            line=line,
+            column=column,
+        )
+
+    return level, strip_backticks(name)
+
+
+def _strip_section_tail_comment(text: str) -> str:
+    in_single = False
+    in_double = False
+    in_backtick = False
+
+    i = 0
+    while i < len(text):
+        ch = text[i]
+
+        if ch == "`" and not in_single and not in_double:
+            in_backtick = not in_backtick
+            i += 1
+            continue
+
+        if ch == "'" and not in_double and not in_backtick:
+            in_single = not in_single
+            i += 1
+            continue
+
+        if ch == '"' and not in_single and not in_backtick:
+            in_double = not in_double
+            i += 1
+            continue
+
+        if not in_single and not in_double and not in_backtick:
+            if ch == "#":
+                return text[:i].rstrip()
+
+            if ch == "/" and i + 1 < len(text) and text[i + 1] == "/":
+                return text[:i].rstrip()
+
+        i += 1
+
+    return text.rstrip()

yini_parser/core/validator.py

@@ -0,0 +1,157 @@
+# src/yini_parser/core/validator.py
+
+from __future__ import annotations
+
+import warnings
+
+from ..api.errors import YiniParseError
+from ..api.warnings import YiniParseWarning
+
+
+class YiniValidator:
+    """
+    Handles validation policy for strict and lenient parsing.
+
+    In strict mode, conflicts are errors.
+    In lenient mode, conflicts are warnings and the first definition wins.
+    """
+
+    def __init__(self, strict: bool = False) -> None:
+        self.strict = strict
+
+    def handle_duplicate_key(
+        self,
+        key: str,
+        *,
+        line: int | None = None,
+        column: int | None = None,
+    ) -> bool:
+        """
+        Handles duplicate keys.
+
+        Returns:
+            True  -> caller may keep/replace the value
+            False -> caller should ignore the new value
+        """
+        message = (
+            f"Duplicate key {key!r} ignored. "
+            "The first value is kept."
+        )
+
+        if self.strict:
+            raise YiniParseError(
+                f"Duplicate key {key!r} is not allowed in strict mode.",
+                line=line,
+                column=column,
+            )
+
+        self._warn(
+            message,
+            line=line,
+            column=column,
+            code="duplicate-key",
+        )
+
+        return False
+
+    def handle_duplicate_section(
+        self,
+        name: str,
+        *,
+        line: int | None = None,
+        column: int | None = None,
+    ) -> bool:
+        """
+        Handles duplicate sections.
+
+        Returns:
+            True  -> caller may reuse/merge the existing section
+            False -> caller should ignore the new section block
+        """
+        message = (
+            f"Duplicate section {name!r} ignored. "
+            "The first section is kept."
+        )
+
+        if self.strict:
+            raise YiniParseError(
+                f"Duplicate section {name!r} is not allowed in strict mode.",
+                line=line,
+                column=column,
+            )
+
+        self._warn(
+            message,
+            line=line,
+            column=column,
+            code="duplicate-section",
+        )
+
+        return False
+
+    def handle_key_section_collision(
+        self,
+        name: str,
+        existing_kind: str,
+        incoming_kind: str,
+        *,
+        line: int | None = None,
+        column: int | None = None,
+    ) -> bool:
+        """
+        Handles name collisions between keys and sections.
+
+        Example:
+            app = "demo"
+            ^ app
+
+        or:
+
+            ^ app
+            app = "demo"
+
+        Returns:
+            True  -> caller may accept the incoming definition
+            False -> caller should ignore the incoming definition
+        """
+        message = (
+            f"Name collision for {name!r} ignored. "
+            f"A {existing_kind} with this name already exists, so the incoming "
+            f"{incoming_kind} was ignored."
+        )
+
+        if self.strict:
+            raise YiniParseError(
+                f"Name collision for {name!r}. "
+                f"A {existing_kind} with this name already exists, so it cannot "
+                f"also be used as a {incoming_kind} in strict mode.",
+                line=line,
+                column=column,
+            )
+
+        self._warn(
+            message,
+            line=line,
+            column=column,
+            code="key-section-collision",
+        )
+
+        return False
+
+    def _warn(
+        self,
+        message: str,
+        *,
+        line: int | None = None,
+        column: int | None = None,
+        code: str | None = None,
+    ) -> None:
+        warnings.warn(
+            YiniParseWarning(
+                message,
+                line=line,
+                column=column,
+                code=code,
+            ),
+            stacklevel=3,
+        )

yini_parser/core/value_decoders.py

@@ -0,0 +1,197 @@
+# src/yini_parser/core/value_decoders.py
+from ..api.errors import YiniParseError
+
+"""
+- Parsers reads raw/source text and recognizes its structure as tokens.
+- Decoders converts tokens into its runtime value.
+"""
+
+def decode_string_token(
+    token_text: str,
+    *,
+    line: int | None = None,
+    column: int | None = None,
+) -> str:
+    """
+    Minimal first-pass string decoding.
+
+    Handles:
+    - Optional prefixes: R/r and C/c.
+    - Single/double quoted strings.
+    - Triple-quoted strings.
+    - Simple quote stripping.
+
+    Unprefixed strings are treated as raw strings.
+    C-prefixed strings decode escape sequences.
+    """
+    text = token_text
+
+    if not text:
+        return ""
+
+    prefix = ""
+
+    if len(text) >= 2 and text[0] in "RrCc" and text[1] in {'"', "'"}:
+        prefix = text[0]
+        text = text[1:]
+    elif len(text) >= 4 and text[0] in "RrCc" and text[1:4] == '"""':
+        prefix = text[0]
+        text = text[1:]
+
+    # Triple-quoted string.
+    if text.startswith('"""') and text.endswith('"""') and len(text) >= 6:
+        inner = text[3:-3]
+
+        if prefix in {"C", "c"}:
+            return _decode_classic_string(
+                inner,
+                line=line,
+                column=column,
+            )
+
+        return inner
+
+    # Single-quoted or double-quoted string.
+    if len(text) >= 2 and text[0] == text[-1] and text[0] in {"'", '"'}:
+        inner = text[1:-1]
+
+        # Raw and unprefixed strings: return as-is.
+        if prefix in {"", "R", "r"}:
+            return inner
+
+        # Classic strings: decode escapes.
+        if prefix in {"C", "c"}:
+            return _decode_classic_string(
+                inner,
+                line=line,
+                column=column,
+            )
+
+        return inner
+
+    raise YiniParseError(
+        f"Invalid string literal: {token_text!r}",
+        line=line,
+        column=column,
+    )
+
+
+def parse_number_literal(text, line=None, column=None):
+    # text = ctx.getText().strip()
+    # line, column = self._ctx_location(ctx)
+
+    try:
+        sign = 1
+        body = text
+
+        if body.startswith("-"):
+            sign = -1
+            body = body[1:]
+        elif body.startswith("+"):
+            body = body[1:]
+
+        lowered = body.lower()
+
+        """
+        By spec: hex:FF_AA   // Shall work.
+                    hex: FF_AA  // INVALID!
+        """
+        if lowered.startswith("hex:"):
+            cleaned = body.split(":", 1)[1].strip().replace("_", "")
+            return sign * int(cleaned, 16)
+
+        if lowered.startswith("0x"):
+            return sign * int(body[2:].replace("_", ""), 16)
+
+        if lowered.startswith("0b"):
+            return sign * int(body[2:].replace("_", ""), 2)
+
+        if lowered.startswith("%"):
+            return sign * int(body[1:].replace("_", ""), 2)
+
+        if lowered.startswith("0o"):
+            return sign * int(body[2:].replace("_", ""), 8)
+
+        if lowered.startswith("0z"):
+            return sign * _parse_duodecimal(
+                body[2:].replace("_", ""),
+                line=line,
+                column=column,
+            )
+
+        decimal_text = text.replace("_", "")
+
+        if any(ch in decimal_text for ch in ".eE"):
+            return float(decimal_text)
+
+        return int(decimal_text, 10)
+
+    except YiniParseError:
+        raise
+
+    except ValueError:
+        raise YiniParseError(
+            f"Invalid number literal: {text!r}",
+            line=line,
+            column=column,
+        ) from None
+
+
+def _decode_classic_string(
+    inner: str,
+    *,
+    line: int | None = None,
+    column: int | None = None,
+) -> str:
+    try:
+        return bytes(inner, "utf-8").decode("unicode_escape")
+    except UnicodeDecodeError as exc:
+        raise YiniParseError(
+            f"Invalid string escape sequence: {exc.reason}.",
+            line=line,
+            column=column,
+        ) from None
+
+
+def _parse_duodecimal(
+    text: str,
+    *,
+    line: int | None = None,
+    column: int | None = None,
+) -> int:
+    value = 0
+
+    if not text:
+        raise YiniParseError(
+            "Invalid duodecimal number: missing digits after '0z'.",
+            line=line,
+            column=column,
+        )
+
+    for ch in text:
+        if ch.isdigit():
+            digit = int(ch)
+        else:
+            lowered = ch.lower()
+
+            if lowered in {"a", "x"}:
+                digit = 10
+            elif lowered in {"b", "e"}:
+                digit = 11
+            else:
+                raise YiniParseError(
+                    f"Invalid duodecimal number: {ch!r} is not a valid base-12 digit.",
+                    line=line,
+                    column=column,
+                )
+
+        if digit >= 12:
+            raise YiniParseError(
+                f"Invalid duodecimal number: {ch!r} is not a valid base-12 digit.",
+                line=line,
+                column=column,
+            )
+
+        value = value * 12 + digit
+
+    return value