natizon 0.1.0__tar.gz

natizon-0.1.0/LICENSES/Apache-2.0.txt

@@ -0,0 +1,73 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+     (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+     (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+     (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+     (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+     You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

natizon-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: natizon
+Version: 0.1.0
+Summary: A pure Python, native ZON (Zig Object Notation) parser.
+Keywords: zig,ZON,Zig Object Notation,parser
+Author-email: Eric Joldasov <bratishkaerik@landless-city.net>
+Requires-Python: >= 3.12
+Description-Content-Type: text/markdown
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Text Processing :: General
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+License-File: LICENSES/Apache-2.0.txt
+Requires-Dist: lark>=1.3.1
+Project-URL: Homepage, https://github.com/BratishkaErik/natizon
+Project-URL: Issues, https://github.com/BratishkaErik/natizon/issues
+Project-URL: Repository, https://github.com/BratishkaErik/natizon
+
+# natizon
+
+`natizon` (short for "native-ZON") is a pure Python parser for
+[ZON (Zig Object Notation)](https://ziglang.org/documentation/0.16.0/std/#std.zon). Built on top of
+[Lark](https://github.com/lark-parser/lark), it provides a familiar, `json`-like interface for decoding ZON strings
+directly into Python data structures: like dictionaries, lists, strings, booleans, and numbers.
+It relies strictly on standard Python types, without AST wrappers and so on.
+
+> [!NOTE]
+> `natizon` is slightly more lenient than the official `std.zon` parser. This flexibility is intentional,
+> making it easier to consume and work with data in Python environments.
+
+## ZON to Python Type Mapping
+
+When you pass a ZON string to `natizon.loads()`, the parser automatically converts ZON primitives and structures into
+their closest Python types.
+
+Here's breakdown:
+
+### Primitives and Literals
+
+| ZON Type              | ZON Example          | Python Type | Python Value     | Notes                                                          |
+|:----------------------|:---------------------|:------------|:-----------------|:---------------------------------------------------------------|
+| **Null**              | `null`               | `NoneType`  | `None`           |                                                                |
+| **Boolean**           | `true`, `false`      | `bool`      | `True`, `False`  |                                                                |
+| **Integer**           | `42`, `0x2A`         | `int`       | `42`             |                                                                |
+| **Float**             | `3.14`, `inf`, `nan` | `float`     | `3.14`           | Supports ZON-specific keywords: `nan` and `inf`.               |
+| **Char Literal**      | `'a'`                | `int`       | `97`             | Evaluates to the integer Unicode code point.                   |
+| **String**            | `"Hello"`            | `str`       | `"Hello"`        | Handles standard escapes and Unicode `\u{...}`.                |
+| **Multiline String**  | `\\Line 1`           | `str`       | `"Line 1"`       | Strips the `\\` prefix and joins multiple lines with newlines. |
+| **Enum Literal**      | `.linux`             | `str`       | `"linux"`        | Parsed simply as strings.                                      |
+| **Quoted Identifier** | `.@"complex-key!"`   | `str`       | `"complex-key!"` | Slices off the `@` prefix and evaluates the string.            |
+
+### Structures and Containers
+
+| ZON Type            | ZON Example    | Python Type | Python Value | Notes                                                          |
+|:--------------------|:---------------|:------------|:-------------|:---------------------------------------------------------------|
+| **Array**           | `.{ 1, 2, 3 }` | `list`      | `[1, 2, 3]`  | Parses as a `tuple` if `use_tuples=True` is set.               |
+| **Struct**          | `.{ .x = 1 }`  | `dict`      | `{"x": 1}`   | Raises `ValueError` if duplicate field names are encountered.  |
+| **Empty Container** | `.{}`          | `dict`      | `{}`         | Parses using Array rules if `empty_mode` is set to `SEQUENCE`. |
+
+## Installation
+
+```shell
+pip install natizon
+```
+
+## Usage
+
+`natizon` exposes a `loads()` function that works similarly to the standard library's `json.loads()`.
+
+```python
+from natizon import loads
+
+zon_data = r"""
+.{
+    .package_name = "network_tools",
+    .version = "2.1.0",
+    .supported_platforms = .{ .linux, .macos, .windows },
+    .dependencies = .{
+        .lib_a = .{ .url = "https://server.com/a.tar" },
+        .lib_b = .{ .path = "../local_b" }
+    }
+}
+"""
+
+# Parses directly into standard Python dicts and lists
+parsed_data = loads(zon_data)
+
+print(parsed_data["package_name"])  # "network_tools"
+print(parsed_data["supported_platforms"])  # ["linux", "macos", "windows"]
+```
+
+### Parsing Options
+
+You can customize how `natizon` handles specific ZON structures:
+
+* **`use_tuples`** (`bool`, default `False`): If `True`, parses ZON arrays (e.g., `.{ 1, 2, 3 }`) as Python `tuple`s
+  instead of `list`s.
+* **`empty_mode`** (`EmptyContainerMode`, default `EmptyContainerMode.DICT`): Controls whether an empty container `.{}`
+  becomes an empty dictionary (`{}`) or an empty sequence (`[]` / `()`).
+
+```python
+from natizon import loads, EmptyContainerMode
+
+data = loads(".{}", use_tuples=True, empty_mode=EmptyContainerMode.SEQUENCE)
+print(data)  # Output: ()
+```

natizon-0.1.0/README.md

@@ -0,0 +1,88 @@
+# natizon
+
+`natizon` (short for "native-ZON") is a pure Python parser for
+[ZON (Zig Object Notation)](https://ziglang.org/documentation/0.16.0/std/#std.zon). Built on top of
+[Lark](https://github.com/lark-parser/lark), it provides a familiar, `json`-like interface for decoding ZON strings
+directly into Python data structures: like dictionaries, lists, strings, booleans, and numbers.
+It relies strictly on standard Python types, without AST wrappers and so on.
+
+> [!NOTE]
+> `natizon` is slightly more lenient than the official `std.zon` parser. This flexibility is intentional,
+> making it easier to consume and work with data in Python environments.
+
+## ZON to Python Type Mapping
+
+When you pass a ZON string to `natizon.loads()`, the parser automatically converts ZON primitives and structures into
+their closest Python types.
+
+Here's breakdown:
+
+### Primitives and Literals
+
+| ZON Type              | ZON Example          | Python Type | Python Value     | Notes                                                          |
+|:----------------------|:---------------------|:------------|:-----------------|:---------------------------------------------------------------|
+| **Null**              | `null`               | `NoneType`  | `None`           |                                                                |
+| **Boolean**           | `true`, `false`      | `bool`      | `True`, `False`  |                                                                |
+| **Integer**           | `42`, `0x2A`         | `int`       | `42`             |                                                                |
+| **Float**             | `3.14`, `inf`, `nan` | `float`     | `3.14`           | Supports ZON-specific keywords: `nan` and `inf`.               |
+| **Char Literal**      | `'a'`                | `int`       | `97`             | Evaluates to the integer Unicode code point.                   |
+| **String**            | `"Hello"`            | `str`       | `"Hello"`        | Handles standard escapes and Unicode `\u{...}`.                |
+| **Multiline String**  | `\\Line 1`           | `str`       | `"Line 1"`       | Strips the `\\` prefix and joins multiple lines with newlines. |
+| **Enum Literal**      | `.linux`             | `str`       | `"linux"`        | Parsed simply as strings.                                      |
+| **Quoted Identifier** | `.@"complex-key!"`   | `str`       | `"complex-key!"` | Slices off the `@` prefix and evaluates the string.            |
+
+### Structures and Containers
+
+| ZON Type            | ZON Example    | Python Type | Python Value | Notes                                                          |
+|:--------------------|:---------------|:------------|:-------------|:---------------------------------------------------------------|
+| **Array**           | `.{ 1, 2, 3 }` | `list`      | `[1, 2, 3]`  | Parses as a `tuple` if `use_tuples=True` is set.               |
+| **Struct**          | `.{ .x = 1 }`  | `dict`      | `{"x": 1}`   | Raises `ValueError` if duplicate field names are encountered.  |
+| **Empty Container** | `.{}`          | `dict`      | `{}`         | Parses using Array rules if `empty_mode` is set to `SEQUENCE`. |
+
+## Installation
+
+```shell
+pip install natizon
+```
+
+## Usage
+
+`natizon` exposes a `loads()` function that works similarly to the standard library's `json.loads()`.
+
+```python
+from natizon import loads
+
+zon_data = r"""
+.{
+    .package_name = "network_tools",
+    .version = "2.1.0",
+    .supported_platforms = .{ .linux, .macos, .windows },
+    .dependencies = .{
+        .lib_a = .{ .url = "https://server.com/a.tar" },
+        .lib_b = .{ .path = "../local_b" }
+    }
+}
+"""
+
+# Parses directly into standard Python dicts and lists
+parsed_data = loads(zon_data)
+
+print(parsed_data["package_name"])  # "network_tools"
+print(parsed_data["supported_platforms"])  # ["linux", "macos", "windows"]
+```
+
+### Parsing Options
+
+You can customize how `natizon` handles specific ZON structures:
+
+* **`use_tuples`** (`bool`, default `False`): If `True`, parses ZON arrays (e.g., `.{ 1, 2, 3 }`) as Python `tuple`s
+  instead of `list`s.
+* **`empty_mode`** (`EmptyContainerMode`, default `EmptyContainerMode.DICT`): Controls whether an empty container `.{}`
+  becomes an empty dictionary (`{}`) or an empty sequence (`[]` / `()`).
+
+```python
+from natizon import loads, EmptyContainerMode
+
+data = loads(".{}", use_tuples=True, empty_mode=EmptyContainerMode.SEQUENCE)
+print(data)  # Output: ()
+```

natizon-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["flit_core >= 3.12.0, <4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "natizon"
+version = "0.1.0"
+requires-python = ">= 3.12"
+authors = [
+    { name = "Eric Joldasov", email = "bratishkaerik@landless-city.net" }
+]
+description = "A pure Python, native ZON (Zig Object Notation) parser."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = [
+    "LICENSES/*",
+]
+keywords = ["zig", "ZON", "Zig Object Notation", "parser"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Text Processing :: General",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    #
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = [
+    "lark>=1.3.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/BratishkaErik/natizon"
+Repository = "https://github.com/BratishkaErik/natizon"
+Issues = "https://github.com/BratishkaErik/natizon/issues"
+
+[dependency-groups]
+test = [
+    "pytest>=9.1.0",
+]
+lint = [
+    "ruff>=0.15.17",
+    "ty>=0.0.49",
+]
+dev = [
+    { include-group = "test" },
+    { include-group = "lint" },
+]
+
+[tool.ruff]
+preview = true
+
+[tool.ruff.lint]
+# Enable all `pydocstyle` rules, limiting to those that adhere to the
+# Google convention via `convention = "google"`.
+select = ["D"]
+
+# On top of the Google convention, disable `D417`, which requires
+# documentation for every function parameter.
+ignore = ["D417"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]

natizon-0.1.0/src/natizon/__init__.py

@@ -0,0 +1,19 @@
+"""ZON (Zig Object Notation) native Python parser.
+
+This package provides a `json`-like interface
+for decoding ZON strings directly into standard, native
+Python data structures (dicts, lists, primitives).
+"""
+
+from .exceptions import ZonDecodeError, ZonError, ZonInternalError
+from .parser import EmptyContainerMode, loads
+from .types import ZonType
+
+__all__ = (
+    "EmptyContainerMode",
+    "ZonDecodeError",
+    "ZonError",
+    "ZonInternalError",
+    "ZonType",
+    "loads",
+)

natizon-0.1.0/src/natizon/_transformer.py

@@ -0,0 +1,135 @@
+import ast
+import re
+from typing import Final, final, assert_never
+
+from lark import Token, Transformer, v_args
+
+from .types import EmptyContainerMode, ZonType
+
+
+def _decode_zig_string(s: str) -> str:
+    """Decodes Zig escape sequences into Python characters before literal evaluation."""
+
+    def _unicode_replacer(match: re.Match) -> str:
+        hex_val = match.group(1)
+        # Python's \U escape expects exactly 8 padded hex digits
+        return f"\\U{hex_val.zfill(8)}"
+
+    # Translate \u{XXXX} to \U0000XXXX
+    s = re.sub(r"\\u\{([0-9a-fA-F]+)}", _unicode_replacer, s)
+    return ast.literal_eval(s)
+
+
+# Stop warnings, functions are used at runtime by Lark:
+# noinspection PyMethodMayBeStatic
+@final
+class _ZonTransformer(Transformer):
+    """Transforms the parsed Lark Tree directly into Python data structures."""
+
+    use_tuples: Final[bool]
+    empty_mode: Final[EmptyContainerMode]
+
+    def __init__(self, use_tuples: bool, empty_mode: EmptyContainerMode) -> None:
+        super().__init__(visit_tokens=True)
+        self.use_tuples = use_tuples
+        self.empty_mode = empty_mode
+
+    def plain_id(self, token: Token) -> str:
+        return str(token)
+
+    def quoted_id(self, token: Token) -> str:
+        # Slices off the '@' prefix before evaluating the string literal
+        val = _decode_zig_string(token.value[1:])
+        if "\x00" in val:
+            raise ValueError("Identifier cannot contain null bytes")
+        return val
+
+    def single_string(self, token: Token) -> str:
+        return _decode_zig_string(token.value)
+
+    def multiline_string(self, *tokens: Token) -> str:
+        cleaned_lines = (
+            # Strip prefix and normalize line endings
+            t.value.removeprefix("\\\\").rstrip("\r")
+            for t in tokens
+        )
+        return "\n".join(cleaned_lines)
+
+    def float_val(self, token: Token) -> float:
+        val = token.value.replace("_", "")
+        # Safely handle python's limitation with standard float(0x1.0p) via float.fromhex
+        if val.lower().startswith("0x"):
+            return float.fromhex(val)
+        return float(val)
+
+    def neg_float_val(self, token: Token) -> float:
+        # Lark filters anonymous "-" literal; only FLOAT_LIT token is passed
+        return -self.float_val(token)
+
+    def int_val(self, token: Token) -> int:
+        return int(token.value.replace("_", ""), 0)
+
+    def neg_int_val(self, token: Token) -> int:
+        val = self.int_val(token)
+        if val == 0:
+            raise ValueError("Integer literal '-0' is ambiguous")
+        return -val
+
+    def nan_val(self, _: Token) -> float:
+        return float("nan")
+
+    def inf_val(self, _: Token) -> float:
+        return float("inf")
+
+    def neg_inf_val(self, _: Token) -> float:
+        return float("-inf")
+
+    def true_val(self, _: Token) -> bool:
+        return True
+
+    def false_val(self, _: Token) -> bool:
+        return False
+
+    def null_val(self, _: Token) -> None:
+        return None
+
+    def char_val(self, token: Token) -> int:
+        evaluated_char = _decode_zig_string(token.value)
+        return ord(evaluated_char)
+
+    def field_init(self, identifier: str, value: ZonType) -> tuple[str, ZonType]:
+        return identifier, value
+
+    def decl_literal(self, identifier: str) -> str:
+        return identifier
+
+    def keyed_struct(self, *items: tuple[str, ZonType]) -> dict[str, ZonType]:
+        result = dict(items)
+
+        if len(result) != len(items):
+            seen = set()
+
+            for k, _ in items:
+                if k in seen:
+                    raise ValueError(f"Duplicate struct field name: '{k}'")
+                seen.add(k)
+
+        return result
+
+    def array_struct(self, *items: ZonType) -> list[ZonType] | tuple[ZonType, ...]:
+        return items if self.use_tuples else list(items)
+
+    def populated_struct(self, body: ZonType) -> ZonType:
+        return body
+
+    def empty_struct(self) -> dict[str, ZonType] | list[ZonType] | tuple[ZonType, ...]:
+        match self.empty_mode:
+            case EmptyContainerMode.DICT:
+                return {}
+            case EmptyContainerMode.SEQUENCE:
+                return self.array_struct()
+            case _ as unreachable:
+                assert_never(unreachable)
+
+
+ZonTransformer = v_args(inline=True)(_ZonTransformer)

natizon-0.1.0/src/natizon/exceptions.py

@@ -0,0 +1,50 @@
+"""Exceptions for the ZON parser."""
+
+
+class ZonError(Exception):
+    """Base exception for all ZON-related errors."""
+
+
+class ZonInternalError(ZonError, RuntimeError):
+    """Raised when the ZON parser fails to initialize.
+
+    Note: most likely this is a bug or corruption in the `natizon` package,
+    not an error on the user side. Recommended to report to upstream,
+    unless you know what you're doing.
+    """
+
+
+class ZonDecodeError(ZonError, ValueError):
+    """Raised when a ZON string cannot be parsed.
+
+    Similar to `json.JSONDecodeError`.
+
+    Attributes:
+        original_exc: The underlying exception caught during parsing or transformation.
+        line: The line number where the error occurred, if available.
+        column: The column number where the error occurred, if available.
+    """
+
+    original_exc: Exception
+    line: int | None
+    column: int | None
+
+    def __init__(
+        self,
+        message: str,
+        original_exc: Exception,
+        line: int | None = None,
+        column: int | None = None,
+    ) -> None:
+        """Initialize the ZON decode error.
+
+        Args:
+            message: A description of the decode error.
+            original_exc: The underlying exception caught during parsing.
+            line: The line number where the error occurred (1-indexed).
+            column: The column number where the error occurred (1-indexed).
+        """
+        super().__init__(f"Failed to decode ZON: {message}")
+        self.original_exc = original_exc
+        self.line = line
+        self.column = column

natizon-0.1.0/src/natizon/grammar/common_zig.lark

@@ -0,0 +1,60 @@
+// Stuff that exist in both Zig and ZON formats.
+// Mostly terminals
+
+// Identifiers
+PLAIN_ID: /[a-zA-Z_][a-zA-Z0-9_]*/
+QUOTED_ID: /@"([^"\\]|\\.)*"/
+
+// Strings and chars
+_ESCAPE_SINGLE: /\\[nr\\t'"]/
+_ESCAPE_UNICODE: /\\x[0-9a-fA-F]{2}/ | /\\u\{[0-9a-fA-F]+\}/
+
+_STR_UNESCAPED: /[^"\\]/
+STRING_SINGLE: "\"" (_ESCAPE_SINGLE | _ESCAPE_UNICODE | _STR_UNESCAPED)* "\""
+STRING_MULTI: /\\\\[^\n]*/
+
+_CHAR_UNESCAPED: /[^'\\]/
+CHAR_LIT: "'" (_ESCAPE_SINGLE | _ESCAPE_UNICODE | _CHAR_UNESCAPED) "'"
+
+// Keywords
+TRUE: "true"
+FALSE: "false"
+NULL: "null"
+
+// Number parts
+_HEX_START: /[0-9a-fA-F][0-9a-fA-F_]*/
+_HEX_FRAC: /[0-9a-fA-F_]+/
+
+_OCT_START: /[0-7][0-7_]*/
+_BIN_START: /[01][01_]*/
+
+_DEC_START: /[0-9][0-9_]*/
+_DEC_FRAC: /[0-9_]+/
+
+_EXP_P: /[pP][-+]?/ _DEC_FRAC
+_EXP_E: /[eE][-+]?/ _DEC_FRAC
+
+// Integers
+HEX_INT: /0[xX]/ _HEX_START
+OCT_INT: /0[oO]/ _OCT_START
+BIN_INT: /0[bB]/ _BIN_START
+DEC_INT: _DEC_START
+
+INT_LIT: HEX_INT
+       | OCT_INT
+       | BIN_INT
+       | DEC_INT
+
+// Floats
+HEX_FLOAT_FRAC: /0[xX]/ _HEX_START "." _HEX_FRAC _EXP_P?
+HEX_FLOAT_EXP:  /0[xX]/ _HEX_START _EXP_P
+DEC_FLOAT_FRAC: _DEC_START "." _DEC_FRAC _EXP_E?
+DEC_FLOAT_EXP:  _DEC_START _EXP_E
+
+FLOAT_LIT: HEX_FLOAT_FRAC
+         | HEX_FLOAT_EXP
+         | DEC_FLOAT_FRAC
+         | DEC_FLOAT_EXP
+
+// Other stuff
+COMMENT: "//" /[^\n]*/

natizon-0.1.0/src/natizon/grammar/zon.lark

@@ -0,0 +1,52 @@
+// ZON (Zig Object Notation) Grammar
+
+?start: expr
+
+?expr: struct_init
+     | decl_literal
+     | string
+     | number
+     | bool
+     | null_val
+     | char_literal
+
+struct_init: "." "{" struct_body "}" -> populated_struct
+           | "." "{" "}"             -> empty_struct
+
+?struct_body: field_init ("," field_init)* ","? -> keyed_struct
+            | expr ("," expr)* ","?             -> array_struct
+
+field_init: "." identifier "=" expr
+decl_literal: "." identifier
+
+?identifier: PLAIN_ID     -> plain_id
+           | QUOTED_ID    -> quoted_id
+
+?string: STRING_SINGLE    -> single_string
+       | STRING_MULTI+    -> multiline_string
+
+?bool: TRUE               -> true_val
+     | FALSE              -> false_val
+
+null_val: NULL
+
+?char_literal: CHAR_LIT   -> char_val
+
+// ZON-exclusive number literals
+NAN: "nan"
+INF: "inf"
+
+?number: FLOAT_LIT        -> float_val
+       | INT_LIT          -> int_val
+       | "-" FLOAT_LIT    -> neg_float_val
+       | "-" INT_LIT      -> neg_int_val
+       | NAN              -> nan_val
+       | INF              -> inf_val
+       | "-" INF          -> neg_inf_val
+
+%import .common_zig (PLAIN_ID, QUOTED_ID, STRING_SINGLE, STRING_MULTI, CHAR_LIT, FLOAT_LIT, INT_LIT, COMMENT)
+%import .common_zig (TRUE, FALSE, NULL)
+%import common.WS
+
+%ignore COMMENT
+%ignore WS

natizon-0.1.0/src/natizon/parser.py

@@ -0,0 +1,121 @@
+"""ZON parser."""
+
+import logging
+from collections.abc import Mapping
+from functools import lru_cache
+from typing import Final, Self, final
+
+from lark import Lark
+from lark.exceptions import GrammarError, UnexpectedInput, VisitError
+
+from ._transformer import ZonTransformer, _ZonTransformer
+from .exceptions import ZonDecodeError, ZonInternalError
+from .types import EmptyContainerMode, ZonType
+
+log = logging.getLogger(__name__)
+
+
+type _TransformerMap = Mapping[tuple[bool, EmptyContainerMode], _ZonTransformer]
+
+
+@final
+class _ZonParserImpl:
+    """Cache Lark parser and stateless transformers."""
+
+    parser: Final[Lark]
+    _transformers: Final[_TransformerMap]
+
+    def __init__(self):
+        log.debug("Initializing Lark ZON parser...")
+
+        options = {
+            "parser": "lalr",
+            "cache": True,
+        }
+
+        current_package = __package__ or "natizon"
+
+        try:
+            self.parser = Lark.open_from_package(
+                package=current_package,
+                search_paths=("grammar",),
+                grammar_path="zon.lark",
+                **options,
+            )
+        except (OSError, GrammarError, ImportError) as e:
+            raise ZonInternalError(
+                "Failed to load ZON grammar. The package may be corrupted."
+            ) from e
+
+        self._transformers = {
+            (False, EmptyContainerMode.DICT): ZonTransformer(
+                use_tuples=False, empty_mode=EmptyContainerMode.DICT
+            ),
+            (False, EmptyContainerMode.SEQUENCE): ZonTransformer(
+                use_tuples=False, empty_mode=EmptyContainerMode.SEQUENCE
+            ),
+            (True, EmptyContainerMode.DICT): ZonTransformer(
+                use_tuples=True, empty_mode=EmptyContainerMode.DICT
+            ),
+            (True, EmptyContainerMode.SEQUENCE): ZonTransformer(
+                use_tuples=True, empty_mode=EmptyContainerMode.SEQUENCE
+            ),
+        }
+
+    @classmethod
+    @lru_cache(maxsize=1)
+    def get_instance(cls) -> Self:
+        return cls()
+
+    def parse(
+        self, text: str, use_tuples: bool, empty_mode: EmptyContainerMode
+    ) -> ZonType:
+        try:
+            tree = self.parser.parse(text)
+            transformer = self._transformers[(use_tuples, empty_mode)]
+            return transformer.transform(tree)
+        except UnexpectedInput as e:
+            # Lark's UnexpectedEOF uses -1. UnexpectedToken can use '?'.
+            # We normalize any non-positive integer to None.
+            line = e.line if isinstance(e.line, int) and e.line > 0 else None
+            column = e.column if isinstance(e.column, int) and e.column > 0 else None
+
+            raise ZonDecodeError(
+                "Syntax error in ZON text",
+                original_exc=e,
+                line=line,
+                column=column,
+            ) from e
+        except VisitError as e:
+            raise ZonDecodeError(
+                f"Data transformation failed: {e.orig_exc!s}",
+                original_exc=e.orig_exc,
+            ) from e
+
+
+def loads(
+    text: str,
+    *,
+    use_tuples: bool = False,
+    empty_mode: EmptyContainerMode = EmptyContainerMode.DICT,
+) -> ZonType:
+    """Parses a ZON string into standard Python data structures.
+
+    Similar to `json.loads()`.
+
+    Args:
+        text: The ZON string to parse.
+        use_tuples: If True, parses "ZON arrays" as tuples instead of lists.
+        empty_mode: Controls whether an empty structure `.{}`
+                    becomes a "dict", or a "list/tuple".
+
+    Returns:
+        ZonType: The parsed Python data structure.
+
+    Raises:
+        ZonDecodeError: If the ZON string contains invalid syntax or cannot be transformed.
+        ZonInternalError: If the parser's internal grammar fails to load.
+    """
+    return _ZonParserImpl.get_instance().parse(
+        text, use_tuples=use_tuples, empty_mode=empty_mode
+    )

natizon-0.1.0/src/natizon/types.py

@@ -0,0 +1,29 @@
+"""Type definitions for the ZON parser."""
+
+from enum import StrEnum
+from typing import final
+
+# Represents any valid ZON value, including recursive collections.
+type ZonType = (
+    None
+    | str
+    | int
+    | float
+    | bool
+    | dict[str, ZonType]
+    | list[ZonType]
+    | tuple[ZonType, ...]
+)
+
+
+@final
+class EmptyContainerMode(StrEnum):
+    """Controls how empty ZON structures `.{}` are parsed.
+
+    Attributes:
+        DICT: Parses `.{}` as an empty dictionary `{}`.
+        SEQUENCE: Parses `.{}` as an empty sequence (list `[]` or tuple `()`, depending on parser settings).
+    """
+
+    DICT = "dict"
+    SEQUENCE = "sequence"