nnlpy 0.3.1

NNL parser/serializer - Near Natural Language (JSON-capable)

NNL — Near Natural Language

A Human-Readable, JSON-Compatible Data Language

---

🌱 What is NNL?

NNL (Near Natural Language) is a human-friendly, indentation-based data notation that looks like simple English sentences but maps 1:1 to JSON.

Write this:

user contains:
name is Alice.
age is 30.
roles are admin, editor.

And get this JSON:

{
  "user": {
    "name": "Alice",
    "age": 30,
    "roles": ["admin", "editor"]
  }
}

NNL is perfect for:

• Configuration files
• API payloads
• Human-editable datasets
• Documentation / examples
• Structured content

---

✨ Features

• Full JSON compatibility

• Human-readable, minimal punctuation

• Natural English-like syntax

• Supports:

  • objects (contains:)
  • arrays (are:)
  • inline lists (a, b, c)
  • arrays of objects
  • nested structures
  • numbers, strings, booleans, null

• Round-trip safe (NNL → JSON → NNL)

---

🔧 Installation

After publishing to PyPI:

pip install nnl

Local development install:

pip install -e .

---

🧪 Usage (Python)

from nnl import parse_nnl, dump_nnl

text = """
user contains:
  name is Alice.
  age is 22.
  roles are admin, editor.
"""

data = parse_nnl(text)
print(data)
# {'user': {'name': 'Alice', 'age': 22, 'roles': ['admin', 'editor']}}

print(dump_nnl(data))

---

📝 CLI Usage

After install, the command nnl becomes available:

NNL ➜ JSON

nnl nnl2json file.nnl

Or via stdin:

type file.nnl | nnl nnl2json -

JSON ➜ NNL

nnl json2nnl file.json

---

📚 Language Basics

Objects

project contains:
  name is Atlas.
  version is 1.0.

Inline Lists

tags are alpha, beta, gamma.

Block Lists

items are:
  - apple.
  - banana.
  - cherry.

Arrays of Objects

users are:
  - contains:
      id is 1.
      name is Alice.
  - contains:
      id is 2.
      name is Bob.

Nested Lists (Matrices)

matrix are:
  - 1, 2, 3.
  - 4, 5, 6.

---

📄 Documentation

See the docs directory:

• spec.md — Official NNL Specification v1.0
• examples.md — Practical examples & patterns

---

🧪 Testing

Run the test suite:

pytest -q

---

🔨 Development

Install dependencies

pip install -e . pytest

Project Structure

nnl/
 ├── nnl/
 │    ├── __init__.py
 │    ├── core.py
 │    ├── cli.py
 ├── tests/
 │    ├── test_nnl_basic.py
 ├── docs/
 │    ├── spec.md
 │    ├── examples.md
 ├── example.nnl
 ├── pyproject.toml
 ├── README.md
 ├── LICENSE
 ├── CONTRIBUTING.md

---

🚀 Publishing (PyPI)

Build:

python -m build

Upload:

twine upload dist/*

---

🤝 Contributing

Pull requests and issues are welcome. NNL is designed to be readable, stable, and easy to extend.

---

📜 License

MIT License See LICENSE for details.