Metadata-Version: 2.4
Name: nyx-lang
Version: 0.1.3
Summary: Python parser and converter for the Nyx 0.1.2 data serialization language
License: Proprietary
License-File: LICENSE
Keywords: converter,data,json,nyx,parser,serialization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing
Classifier: Topic :: Text Processing :: Markup
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# nyx-lang

A small, dependency-free Python parser and converter for the Nyx 0.1.2 data
serialization language.

Nyx is a flat, context-stateful format built around boxes, items, sub-items,
pieces, and `tape` seals. It maps cleanly to JSON while keeping authoring
readable for nested personal data.

## Installation

```bash
pip install nyx-lang
```

## Quick Start

```python
import nyx_lang

source = """
^nyx=0.1.2
box: "Inventory"
sub-box: "Electronics"

item: "Console"
sub-item: "manufacturer"
sub-item: "Nintendo"
tape
sub-item: "controllers"
piece: "Pro Controller"
piece: "Joy-Con"
"""

data = nyx_lang.parse(source)
print(nyx_lang.to_json(data))
```

Output:

```json
{
  "Inventory": {
    "Electronics": {
      "Console": {
        "manufacturer": "Nintendo",
        "controllers": [
          "Pro Controller",
          "Joy-Con"
        ]
      }
    }
  }
}
```

## Command Line

The package installs a `nyx` command. You can also run it as a module with
`python -m nyx_lang`.

```bash
# Nyx -> JSON
nyx to-json input.nyx --output output.json
python -m nyx_lang to-json input.nyx --output output.json

# JSON -> Nyx
nyx to-nyx input.json --output output.nyx
python -m nyx_lang to-nyx input.json --output output.nyx

# Print parsed JSON to the terminal
nyx parse input.nyx

# Validate a Nyx document
nyx validate input.nyx
```

On Windows, prefer `--output` over shell redirection so files are written as
UTF-8.

## API

### `nyx_lang.parse(source, *, strict=True) -> dict`

Parse a Nyx document string into a Python dictionary.

```python
from nyx_lang import parse

data = parse('^nyx=0.1.2\nbox: "Settings"\nitem: "theme"\nsub-item: "dark"')
assert data == {"Settings": {"theme": "dark"}}
```

`strict=True` raises `NyxSyntaxError` for unsupported versions. Version `0.1`
documents are accepted for compatibility with earlier package builds.

### `nyx_lang.to_json(data, *, indent=2, **kwargs) -> str`

Serialize parsed Nyx data to JSON. Extra keyword arguments are passed to
`json.dumps`.

```python
from nyx_lang import to_json

print(to_json({"Settings": {"theme": "dark"}}, indent=2))
```

### `nyx_lang.to_nyx(data) -> str`

Serialize a Python dictionary to a Nyx 0.1.2 document.

```python
from nyx_lang import to_nyx

print(to_nyx({"Settings": {"theme": "dark"}}))
```

## Nyx Primer

Every document starts with a version header:

```nyx
^nyx=0.1.2
```

Core statements:

| Keyword | Effect |
| --- | --- |
| `box: "Name"` | Open a root container. |
| `sub-box: "Name"` | Open a nested container inside the active box. |
| `sub-box: ""` | Open the next anonymous array-object slot. |
| `item: "Name"` | Create an item in the active box. |
| `sub-item: "key"` | Add a child key under the active item. |
| `piece: value` | Append a scalar element to the active item list. |
| `tape` | Seal the current context and step up one level. |

Primitive values:

```nyx
sub-item: "string"
sub-item: 42
sub-item: 3.14
sub-item: true
sub-item: false
sub-item: null
```

A sub-item with exactly one scalar child collapses to a key-value pair:

```nyx
sub-item: "temperature"
sub-item: -4.5
```

Result:

```json
{ "temperature": -4.5 }
```

Flat arrays use `piece`:

```nyx
item: "controllers"
piece: "Pro Controller"
piece: "Joy-Con"
```

Arrays of objects use anonymous sub-boxes:

```nyx
box: "tabs"
sub-box: ""
item: "pageTitle"
sub-item: "Home"
tape
tape
sub-box: ""
item: "pageTitle"
sub-item: "Settings"
```

Result:

```json
{
  "tabs": [
    { "pageTitle": "Home" },
    { "pageTitle": "Settings" }
  ]
}
```

## Exceptions

| Exception | When raised |
| --- | --- |
| `NyxSyntaxError` | Invalid syntax, invalid keyword, missing header, wrong context, or mixed item/list usage. |
| `NyxVersionWarning` | Unsupported version in lenient mode. |

## Development

```bash
python -m pip install -e ".[dev]"
python -m pytest
python -m build
```

Build artifacts are written to `dist/`.

## Publishing Checklist

1. Confirm `pyproject.toml` has the intended version.
2. Run `python -m pytest`.
3. Run `python -m build`.
4. Inspect the wheel and source distribution in `dist/`.
5. Upload to TestPyPI first:

```bash
python -m twine upload --repository testpypi dist/*
```

6. Upload to PyPI:

```bash
python -m twine upload dist/*
```

## License

Proprietary. See `LICENSE` for details.
