Metadata-Version: 2.4
Name: hyperlark
Version: 0.1.0b1
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Text Processing :: General
Classifier: Topic :: Text Processing :: Linguistic
Requires-Dist: lark>=1.2,<2.0 ; extra == 'compat'
Provides-Extra: compat
License-File: LICENSE
Summary: A reimplementation of the Lark parsing toolkit, using Rust, to be used as a drop-in replacement
Keywords: parsing,parser,lark,earley,lalr,grammar,ebnf,lexer
Author-email: Esh Software <hyperlark@eshsoft.com>
License-Expression: LicenseRef-Hyperlark-Beta
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://hyperlark.io/

# Hyperlark

Hyperlark is a Rust reimplementation of the
[Lark parsing toolkit](https://github.com/lark-parser/lark), built with a focus
on ergonomics, performance and modularity.

Hyperlark can parse all context-free languages. To put it simply, it means that
it is capable of parsing almost any programming language out there, and to some
degree most natural languages too.

Hyperlark implements the vast majority of Lark's features, and can often be used
as a drop-in replacement, with none or very few code changes.

**Status: `0.1.0-beta.1`** — pre-1.0, APIs may still change between betas.

## Install

```bash
pip install hyperlark
```

Wheels are CPython 3.10+ (stable-ABI, `abi3`), for Linux (glibc and musl,
x86-64 and aarch64), macOS 13+ (x86-64 and arm64) and Windows x64.

**Not supported:** PyPy, and **free-threaded CPython** (`3.13t` / `3.14t`)

## Hello World

```python
import hyperlark

parser = hyperlark.Lark(r"""
    start: WORD+
    %import common.WORD
    %ignore " "
""")

tree = parser.parse("hello world")
print(tree.pretty())
```

For complete, runnable programs — a calculator, JSON, an indentation-sensitive
language, ambiguity, interactive parsing, error reporting — see the
[examples page](https://hyperlark.io/examples/).

## Features

- **An industry-standard grammar.** Lark is widely used, its grammar syntax was
  adopted by OpenAI for their official API, and `.lark` files get syntax
  highlighting on GitHub.
- **Choose between LALR(1) and Earley (SPPF) parsers.** LALR(1) is fast,
  linear-time and low on memory. Earley can parse every context-free grammar,
  and can efficiently handle and store every ambiguity, for later queries.
- **Choose between several lexers, or provide your own.** Hyperlark provides
  sophisticated lexers that can help LALR(1) disambiguate tokens based on the
  parser state, and that help Earley handle lexical ambiguities much faster than
  scannerless methods. A `postlex` pass, such as the bundled `Indenter`, covers
  indentation-sensitive languages.
- **Automatic tree construction.** Use the `Transformer` / `Visitor` /
  `Interpreter` classes on the parse tree, or hand the transformer to
  `transformer=` to skip tree construction entirely.
- **Interactive parsing (for LALR).** Drive the parser and query it at any point
  of the parse. Useful for error handling, checkpoints & backtracking, and even
  debugging.
- **Line positions.** Hyperlark keeps track of the line and column of every
  token, and will even propagate the ranges to the tree nodes when
  `propagate_positions=True`.
- **Grammar composition.** Import rules, terminals, or entire grammars into your grammar, using an inheritance-like interface (namespaces, overrides), for better re-use and modularity.

## Performance

**10× `lark`** engine for engine on LALR, and **16–22×** on Earley.

![hyperlark against sly and lark, on both engines](https://hyperlark.io/bench-python.svg)

Actual speed depends on grammar, input size and how Hyperlark is used.

For more information, see the [benchmarks](https://hyperlark.io/reference/benchmarks/).

## Differences from Lark

### `fast_tokens`

To avoid creating a Python object for each token, Hyperlark uses its own Token
object. As a consequence, `hyperlark.Token` does not inherit from `str`. It does
provide some of the `str` methods (`.upper()`, `.startswith()`, …) for
convenience, but reach for `.value` wherever a real `str` is required.

This can be disabled with the `fast_tokens=False` option, which restores
Lark-identical `str`-subclass tokens everywhere, at some cost in performance.

### Not implemented

The reconstructor, tree templates, the standalone tool, and `TextSlice` inputs.

These options are recognized but not supported. Each raises a clear
`ConfigurationError` at construction, rather than silently doing nothing:

| Option | Note |
| --- | --- |
| `strict=` | |
| `cache_grammar=` | `cache=` itself works |
| `use_bytes=` | |
| `edit_terminals=` | |
| `regex=` | the third-party `regex` module |
| `ambiguity='forest'` | `'resolve'` and `'explicit'` work |
| `parser='cyk'` | `'lalr'` and `'earley'` work |
| `parser=None` | Lark's lexer-only mode; build a parser and call `.lex()` |

Beyond these, a handful of behaviors differ in detail: lexer callbacks, the
parser object's surface, class identity under mixed `lark` + `hyperlark`
imports, and recursion inside your own callbacks. See the full
[list of divergences](https://hyperlark.io/reference/divergences/).

## Links

- [Documentation](https://hyperlark.io/) — the grammar language, guides, and
  the API reference
- [Lark](https://github.com/lark-parser/lark) — the API and grammar language
  Hyperlark reimplements
- Questions and bug reports: <erezshin@gmail.com>
- Commercial licensing: <hyperlark@eshsoft.com>

Hyperlark's source hasn't been published at this time.

## License

Free for noncommercial use, including evaluation and testing inside commercial
organizations. Commercial use requires a separate license — contact
<hyperlark@eshsoft.com>.

Copyright © 2026 Esh Software LLC. Full text in the `LICENSE` file in the
distribution.

