Xarpeg Tutorial

Learn to build powerful parsers with Kotlin. This tutorial guides you from basic concepts to advanced techniques, step by step.

Prerequisites

• Basic Kotlin knowledge (functions, lambdas, classes)
• Familiarity with regular expressions (helpful but not required)
• IDE with Kotlin support for code completion

Installation

Add Xarpeg to your build.gradle.kts:

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.

Find the latest version in Releases.

---

Tutorial Steps

1. Quickstart

Build your first parser in minutes. Learn the basic syntax and run a simple key-value parser.

What you’ll learn: Creating parsers from literals and regex, sequencing with *, ignoring tokens with -, transforming results with map

---

2. Combinators

Master the building blocks: sequences, choices, repetition, and optional parsing.

What you’ll learn: Alternatives with +, repetition (.zeroOrMore, .oneOrMore), optionals, input boundaries, naming parsers for better error messages

---

3. Expressions & Recursion

Handle recursive grammars and operator precedence for expression parsing.

What you’ll learn: Forward references with ref { }, left/right associativity, building arithmetic parsers, proper type declarations

---

4. Runtime Behavior

Understand how parsers handle errors, consume input, and use caching.

What you’ll learn: Exception types, ParseContext error tracking, memoization control, debugging techniques

---

5. Parsing Positions

Extract location information for better error messages and source mapping.

What you’ll learn: Position tracking with mapEx, calculating line/column numbers, extracting matched text

---

6. Template Strings

Parse complex nested structures without tokenization.

What you’ll learn: Handling embedded expressions, context switching with PEG, recursive string/expression parsing

---

Complete Examples

JSON Parser

Full implementation handling all JSON types with escape sequences, nested structures, and comprehensive tests.

→ View JSON Parser Source

Features:

• String escape sequences (\", \\, \n, \uXXXX)
• Numbers (integers, decimals, scientific notation)
• Recursive arrays and objects with ref { }
• Custom separator handling

Arithmetic Interpreter

Expression parser with evaluation and error reporting including line/column positions.

→ View Interpreter Source

Features:

• Four arithmetic operations with precedence
• Parentheses for grouping
• Division by zero error reporting with positions
• Command-line interface

Online Parser Demo

Interactive browser-based parser demonstrating real-time parsing and evaluation.

→ Try Live Demo

View Source

---

Additional Resources

API Documentation

• KDoc in IDE - Use code completion for inline documentation
• Parser.kt - Core interface and helpers
• parsers package - Combinator implementations

Tests

• ParserTest.kt - Comprehensive behavior examples
• ErrorContextTest.kt - Error tracking examples

Real-World Usage

• Xarpite - Production application using Xarpeg for complex grammar parsing

---

Need Help?

• GitHub Issues - Report bugs or request features
• Main README - Quick reference and overview