Metadata-Version: 2.4
Name: exonware-xwsyntax
Version: 0.6.0.5
Summary: Universal grammar engine with bidirectional parsing and generation for 31+ formats
Project-URL: Homepage, https://exonware.com
Project-URL: Repository, https://github.com/exonware/xwsyntax
Project-URL: Documentation, https://github.com/exonware/xwsyntax#readme
Project-URL: Subtree, https://github.com/exonware/xwsyntax.git
Author-email: eXonware Backend Team <connect@exonware.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: lark>=1.1.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: exonware-xwlazy; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: aiofiles; extra == 'full'
Requires-Dist: atomicwrites; extra == 'full'
Requires-Dist: attrs; extra == 'full'
Requires-Dist: bcrypt; extra == 'full'
Requires-Dist: bottleneck; extra == 'full'
Requires-Dist: brotli; extra == 'full'
Requires-Dist: cachebox; extra == 'full'
Requires-Dist: cachetools; extra == 'full'
Requires-Dist: cbor2>=5.0.0; extra == 'full'
Requires-Dist: charset-normalizer; extra == 'full'
Requires-Dist: cloudpickle; extra == 'full'
Requires-Dist: cryptography; extra == 'full'
Requires-Dist: cython; extra == 'full'
Requires-Dist: dicttoxml; extra == 'full'
Requires-Dist: httpx; extra == 'full'
Requires-Dist: hyperlight-hyperjson; extra == 'full'
Requires-Dist: interegular; extra == 'full'
Requires-Dist: json5; extra == 'full'
Requires-Dist: lz4; extra == 'full'
Requires-Dist: msgpack>=1.0.0; extra == 'full'
Requires-Dist: msgspec; extra == 'full'
Requires-Dist: numexpr; extra == 'full'
Requires-Dist: numpy; extra == 'full'
Requires-Dist: opentelemetry-api; extra == 'full'
Requires-Dist: orjson; extra == 'full'
Requires-Dist: pandas; extra == 'full'
Requires-Dist: psutil; extra == 'full'
Requires-Dist: pyarrow; extra == 'full'
Requires-Dist: pygls>=1.0.0; extra == 'full'
Requires-Dist: pylru; extra == 'full'
Requires-Dist: pymongo; extra == 'full'
Requires-Dist: pytz; extra == 'full'
Requires-Dist: pyyaml; extra == 'full'
Requires-Dist: regex; extra == 'full'
Requires-Dist: rich; extra == 'full'
Requires-Dist: scikit-learn; extra == 'full'
Requires-Dist: tomli-w; extra == 'full'
Requires-Dist: tree-sitter>=0.20.0; extra == 'full'
Requires-Dist: uarray; extra == 'full'
Requires-Dist: xmltodict; extra == 'full'
Requires-Dist: zstandard; extra == 'full'
Provides-Extra: lazy
Requires-Dist: exonware-xwlazy; extra == 'lazy'
Description-Content-Type: text/markdown

# xwsyntax

**One bidirectional grammar engine.** Parse text to AST, generate back, or convert between syntaxes (e.g. JSON to SQL). 100+ grammars (328+ files) for query, data, and code. Powers xwquery and editors; use it to create new syntaxes or bridge formats.

**Company:** eXonware.com · **Author:** eXonware Backend Team · **Email:** connect@exonware.com  
**Version:** [version.py](src/exonware/xwsyntax/version.py) (`__version__`, `__date__`)

[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://exonware.com)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

---

## Install

```bash
pip install exonware-xwsyntax
# Optional: full extras
pip install exonware-xwsyntax[full]
```

Depends on xwsystem. See [docs/GUIDE_01_USAGE.md](docs/GUIDE_01_USAGE.md) for details.

---

## Quick start

```python
from exonware.xwsyntax import BidirectionalGrammar

grammar = BidirectionalGrammar.load('json')
ast = grammar.parse('{"name": "Alice", "age": 30}')
json_str = grammar.generate(ast)

# Convert between syntaxes
sql_grammar = BidirectionalGrammar.load('sql')
sql = sql_grammar.generate(ast)
# Same AST, different format
```

Facade: `XWSyntax().parse(text, format_name)` or `validate(text, format_name)`.  
List grammars: `list_grammars_quick()`, `load_grammar_quick(name)`.  
Key code: [REF_14_DX](docs/REF_14_DX.md) · API: [REF_15_API](docs/REF_15_API.md).

---

## Examples

### Parse and validate with the facade

```python
from exonware.xwsyntax import XWSyntax

engine = XWSyntax()
ast = engine.parse("a = 1 + 2", format_name="python")
is_valid = engine.validate("a = 1 + 2", format_name="python")
```

### List grammars and load by name

```python
from exonware.xwsyntax import list_grammars_quick, load_grammar_quick

names = list_grammars_quick()
grammar = load_grammar_quick(names[0])
```

### Convert JSON to SQL by reusing the AST

```python
from exonware.xwsyntax import BidirectionalGrammar

ast = BidirectionalGrammar.load("json").parse('{"name": "Alice", "age": 30}')
sql = BidirectionalGrammar.load("sql").generate(ast)
```

---

## What you get

| Area | Description |
|------|-------------|
| **Grammar read/write** | Parse input to native objects or tree; generate from AST. Grammar-driven; no hardcoded format maps. |
| **Bidirectional** | Parse to AST, generate back; convert between syntaxes (e.g. JSON to SQL) by swapping grammars. |
| **100+ grammars** | Query (SQL, Cypher, GraphQL, xwqueryscript, …), data/config, programming, markup, storage. 328+ grammar files (.lark + .json). |
| **xwquery and IDE** | Parsing and syntax for query languages; Monaco export and codec integration with xwsystem. |

Current phase: **Alpha.** M1–M2 done; xwquery consumption next. Status: [REF_22_PROJECT](docs/REF_22_PROJECT.md#project-status-overview).

---

## Docs and tests

- **Start:** [docs/INDEX.md](docs/INDEX.md)
- **Usage:** [docs/GUIDE_01_USAGE.md](docs/GUIDE_01_USAGE.md)
- **Requirements and status:** [REF_01_REQ](docs/REF_01_REQ.md), [REF_22_PROJECT](docs/REF_22_PROJECT.md)
- **API and design:** [REF_15_API](docs/REF_15_API.md), [REF_13_ARCH](docs/REF_13_ARCH.md), [REF_14_DX](docs/REF_14_DX.md)
- **Tests:** [REF_51_TEST](docs/REF_51_TEST.md). Run from project root: `python tests/runner.py`.

---

## License and links

MIT — [LICENSE](LICENSE).  
**Homepage:** https://exonware.com · **Repository:** https://github.com/exonware/xwsyntax  

Contributing → CONTRIBUTING.md · Security → SECURITY.md (when present).

*Built with ❤️ by eXonware.com - Revolutionizing Python Development Since 2025*
