Lightweight PEG-style parser combinators for Kotlin Multiplatform

Xarpeg (/ˈʃɑrpɛɡ/) is a compact, operator-driven parser combinator library for Kotlin. It targets JVM, JS (Node.js), and Native platforms (Linux x64, Linux ARM64, Windows x64), works directly on raw input strings without tokenization, and includes built-in memoization for predictable backtracking performance.

• 🎯 Intuitive DSL - Operator-based syntax feels natural: + for literals/regex/choice, * for sequences, - to ignore tokens
• 📦 Multiplatform - Write once, run on JVM, JS (IR/Node.js), and Native (Linux/Windows)
• 🔧 No Tokenizer Needed - Parse directly from strings using character, string, and regex parsers
• ⚡ Built-in Memoization - Automatic caching keeps backtracking predictable; disable for lower memory use
• 🎨 Type-Safe Results - Sequences yield Tuple0..Tuple16 so you explicitly control what's kept or dropped

Here's a complete arithmetic expression parser in just a few lines:

import io.github.mirrgieriana.xarpeg.*
import io.github.mirrgieriana.xarpeg.parsers.*

val expr: Parser<Int> = object {
    val number = +Regex("[0-9]+") map { it.value.toInt() } named "number"
    val brackets: Parser<Int> = -'(' * ref { root } * -')'
    val factor = number + brackets
    val mul = leftAssociative(factor, -'*') { a, _, b -> a * b }
    val add = leftAssociative(mul, -'+') { a, _, b -> a + b }
    val root = add
}.root

fun main() {
    check(expr.parseAll("2*(3+4)").getOrThrow() == 14)  // ✓ Evaluates to 14
}

Key concepts:

• +'x' / +"xyz" / +Regex("...") create parsers from literals or patterns
• * sequences parsers, returning typed tuples
• -parser matches but ignores the result (useful for delimiters)
• + (binary) tries alternatives in order
• named improves error messages
• ref { } enables recursive grammars
• leftAssociative handles operator precedence without manual recursion

Best practices:

• Use +'x' for single characters, not +"x"
• Use +"xyz" for fixed strings, not +Regex("xyz")
• Always use named with Regex parsers for better error messages

💡 New to parser combinators? Start with our step-by-step tutorial!

Follow our comprehensive tutorial to master parser combinators:

1. Quickstart - Your first parser in minutes
2. Combinators - Sequences, choices, repetition, and naming
3. Expressions & Recursion - Build recursive grammars with ref { }
4. Runtime Behavior - Errors, exceptions, and caching
5. Parsing Positions - Extract location information with mapEx
6. Template Strings - Parse embedded expressions naturally

→ Start the Tutorial: [English] [日本語]

🚀 Launch Online Parser Demo

Interactive browser-based parser that demonstrates:

• Real-time parsing and evaluation
• Error reporting with suggestions
• Kotlin/JS multiplatform capabilities

• parseAll(input).getOrThrow() - Parse entire input or throw exception
• parseOrNull(context, start) - Attempt parse at position; return ParseResult<T>?

• ParseException - Thrown when parsing fails (either because no parser matched at the current position or because trailing input remains after successful parse)
• The exception provides context with errorPosition and suggestedParsers for detailed error reporting

• Memoization - Enabled by default (useMemoization = true); disable with useMemoization = false for lower memory usage
• Backtracking - Memoized results make repeated attempts predictable; alternatives backtrack automatically

• JSON Parser - Full JSON implementation with escape sequences, numbers, arrays, and nested objects
• Arithmetic Interpreter - Expression parser with evaluation and error reporting
• Online Parser Demo - Interactive browser-based parser (source)

Xarpite - The original project from which Xarpeg was extracted. Demonstrates:

• Large-scale grammar design and organization
• Integration into a complete application
• Performance optimization with caching
• Complex parsing scenarios in production

Try the samples locally to see Xarpeg in action:

Minimal JVM Sample:

cd samples/minimal-jvm-sample && ./gradlew run

Online Parser Sample:

cd samples/online-parser && ./gradlew build
# Open samples/online-parser/build/site/index.html in your browser

Arithmetic Interpreter:

cd samples/interpreter && ./gradlew run --args='-e "2*(3+4)"'

Add Xarpeg to your project using Gradle. Replace <latest-version> with the version from Releases.

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.mirrgieriana:xarpeg:<latest-version>")
}

The xarpeg artifact uses Gradle module metadata to automatically resolve to the correct platform-specific variant (JVM, JS, Native, etc.) based on your project configuration.

Note: The API may evolve as we refine the DSL. Pin a specific version for production use.

• Documentation - Complete tutorial [English] [日本語]
• API Reference - Browse source for KDoc
• Examples - Sample applications
• Issues - Bug reports and feature requests
• Releases - Version history

⚠️ Documentation Notice: The natural language descriptions throughout this documentation (including this README) were predominantly generated by AI and may contain inaccuracies. When in doubt, please verify against the actual source code and test the behavior directly.

MIT License - See LICENSE for details.

_{Logo uses Monaspace}