Metadata-Version: 2.4
Name: parsil-peg
Version: 0.1.1
Summary: A lightweight PEG parser combinator library for Python.
Project-URL: Homepage, https://github.com/shahilahmed/parsil
Project-URL: Repository, https://github.com/shahilahmed/parsil
Project-URL: Issues, https://github.com/shahilahmed/parsil/issues
Project-URL: PyPI, https://pypi.org/project/parsil-peg/
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Parsil

A lightweight PEG parser combinator library for Python.

Parsil provides a small set of composable parsing rules for building recursive-descent parsers. It is designed to be simple, readable, and easy to extend.

## Features

- Lightweight and dependency-free
- PEG-style parser combinators
- Recursive grammars
- Regular expression support
- Rule composition with operators
- Rule transformation with `Map`
- Structured parsing results (`Success` / `Failure`)
- Full-input parsing
- Helpful parse error reporting

## Installation

Install from PyPI:

```bash
pip install parsil-peg
```

Or install the latest development version from source:

```bash
git clone https://github.com/shahilahmed/parsil.git
cd parsil
pip install -e .
```

## Quick Start

```python
from parsil import *

grammar = Grammar()

grammar["number"] = R(r"\d+").map(int)

parser = Parser(grammar, "123")

result = parser.parse("number")

if result.ok:
    print(result.value)
```

Output:

```text
123
```

## Building Grammars

Parsil supports a concise DSL for composing parser rules.

| Expression | Equivalent |
| :--------- | :--------- |
| `a + b` | `Sequence(a, b)` |
| `a \| b` | `Choice(a, b)` |
| `rule.star()` | `Repeat(rule)` |
| `rule.plus()` | `Repeat(rule, minimum=1)` |
| `rule.optional()` | `Repeat(rule, maximum=1)` |
| `rule.map(func)` | `Map(rule, func)` |

Helper functions:

| Function | Equivalent |
| :------- | :--------- |
| `L(text)` | `Literal(text)` |
| `R(pattern)` | `Regex(pattern)` |
| `Ref_(name)` | `Ref(name)` |

## Example

```python
from parsil import *

grammar = Grammar()

grammar["word"] = (
    L("hello")
    + L(" ")
    + L("world")
)

parser = Parser(grammar, "hello world")

result = parser.parse("word")

if result.ok:
    print(result.value)
```

Output:

```python
['hello', ' ', 'world']
```

## Parse Results

Every parse returns either a `Success` or `Failure`.

Successful parse:

```python
result = parser.parse("number")

if result.ok:
    print(result.value)
```

Failed parse:

```python
result = parser.parse("number")

if result.failed:
    print(result.position)
    print(result.expected)
```

Example:

```text
Failure(position=4, expected=[')'])
```

## Available Rules

| Rule | Description |
| :--- | :---------- |
| `Literal` | Match an exact string |
| `Regex` | Match a regular expression |
| `Sequence` | Match rules in order |
| `Choice` | Match the first successful rule |
| `Repeat` | Match a rule repeatedly |
| `Ref` | Reference another grammar rule |
| `Map` | Transform a matched value |

## Project Structure

```text
parsil/
├── examples/
├── parsil/
│   ├── grammar.py
│   ├── parser.py
│   ├── result.py
│   └── rules/
│       ├── base.py
│       ├── literal.py
│       ├── regex.py
│       ├── sequence.py
│       ├── choice.py
│       ├── repeat.py
│       ├── ref.py
│       └── map.py
├── tests/
├── LICENSE
├── README.md
└── pyproject.toml
```

## Running Tests

```bash
pytest
```

## Requirements

- Python 3.8 or later

## License

This project is licensed under the MIT License.

---

## PyPI

https://pypi.org/project/parsil-peg/

## Source Code

https://github.com/shahilahmed/parsil

