Metadata-Version: 2.4
Name: krpgscript
Version: 0.1.0
Summary: Typed parser and runtime engine for tiny text RPG scripts
Project-URL: Homepage, https://github.com/kotazzz/krpgscript
Project-URL: Repository, https://github.com/kotazzz/krpgscript
Project-URL: Issues, https://github.com/kotazzz/krpgscript/issues
License: MIT
License-File: LICENSE
Keywords: cli,game,parser,rpg,script
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/markdown


# krpgscript

[Русский](README.ru.md) | English

Typed parser for a small KRPG DSL.

## What It Does

`krpgscript` parses a brace-based text format into a tree of `Section` and `Command` nodes.
It is intentionally small and focused on syntax parsing, not on game runtime execution.

## Core Concepts

- `Section` is a container node that can hold nested sections and commands
- `Command` is a leaf node with positional arguments
- `TokenType` describes tokenizer output: `NEWLINE`, `BRACE`, `COMMAND`
- `parse_text()` is the main entry point for parsing raw text into an AST

## Example Syntax

See [examples/story.krpg](examples/story.krpg) for a minimal demo.

```text
game {
    title "Small Demo"
    version 1

    player "Aria" {
        hp 100
        mp 25
        skill "quick strike"
    }

    scene intro {
        say "You wake up in a quiet room."
        choice "Open the door" goto hall
        choice "Go back to sleep" goto sleep
    }
}
```

## Usage

### Parse text in Python

```python
from pathlib import Path

from krpgscript import Command, Section, parse_text

root = parse_text(Path("examples/story.krpg").read_text(encoding="utf-8"))

game = root.get("game", command=False, section=True)
assert isinstance(game, Section)

for child in game.children:
    if isinstance(child, Command):
        print(child.name, child.args)
    else:
        print(child.name, child.args)
```

### Run the demo example

```bash
uv run python examples/run_example.py
```

### CLI

Validate syntax for a file, directory, or glob:

```bash
krpgscript check examples/story.krpg examples/
```

Format one or more files in place:

```bash
krpgscript format examples/**/*.krpg
```

Export the tree to JSON:

```bash
krpgscript json examples/story.krpg -o story.json
```

## Development

Install dependencies:

```bash
uv sync --dev
```

Run tests:

```bash
just test
```

Run linting and type checks:

```bash
just check
```

Format code:

```bash
just fmt
```

Build release artifacts:

```bash
just build
```

Validate the release workflow:

```bash
just release-check
```

## Project Layout

```text
krpgscript/
  __init__.py
  main.py
  parser.py
examples/
  run_example.py
  story.krpg
tests/
  test_parser.py
justfile
```

## Notes

- The package has no runtime dependencies
- The public API lives in [krpgscript/__init__.py](krpgscript/__init__.py)
- The current parser API is `Section`, `Command`, `TokenType`, `tokenize`, `parse`, and `parse_text`
