or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

character-parsing.mdcombinators.mdcore-primitives.mdindex.mdparser-generation.mdparser-operators.md
tile.json

tessl/pypi-parsec

A universal Python parser combinator library inspired by Parsec library of Haskell

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/parsec@2.0.x

To install, run

npx @tessl/cli install tessl/pypi-parsec@2.0.0

index.mddocs/

Parsec

A universal Python parser combinator library inspired by Haskell's Parsec library. It enables developers to build complex parsers by combining simple parsing primitives using monadic operations and functional composition. The library provides a rich set of parsing combinators, advanced error handling with detailed location information, and supports both imperative and declarative parser construction patterns.

Package Information

  • Package Name: parsec
  • Language: Python
  • Installation: pip install parsec

Core Imports

from parsec import *

Common selective imports:

from parsec import Parser, string, many, letter, digit, regex, generate

Basic Usage

from parsec import *

# Simple string parser
hello_parser = string("hello")
result = hello_parser.parse("hello world")  # Returns "hello"

# Combining parsers with operators
# Parse "hello" followed by space(s) and "world"
greeting_parser = string("hello") >> spaces >> string("world")
result = greeting_parser.parse("hello   world")  # Returns "world"

# Using many combinator to parse repeated elements
letters_parser = many(letter())
result = letters_parser.parse("abc123")  # Returns ['a', 'b', 'c']

# Parser generator approach for complex parsing
@generate
def number_list():
    nums = yield many(digit())
    yield string(",")
    return int("".join(nums))

result = number_list.parse("123,")  # Returns 123

Architecture

Parsec follows functional programming principles with monadic parser combinators:

  • Parser: Core class wrapping parsing functions that operate on text and return Value objects
  • Value: Result container with success/failure status, consumed position, and parsed value
  • ParseError: Detailed error reporting with source location information
  • Combinators: Higher-order functions that combine simple parsers into complex ones
  • Generator decorators: Python-native syntax for building complex parsers using yield

This design enables compositional parsing where complex grammar rules are built by combining simple, reusable parser components.

Capabilities

Core Parsing Primitives

The fundamental classes and types that form the foundation of all parsing operations, including the main Parser class, result handling with Value objects, and comprehensive error reporting.

class Parser:
    def __init__(self, fn): ...
    def parse(self, text): ...
    def parse_partial(self, text): ...
    def parse_strict(self, text): ...

class Value:
    @staticmethod
    def success(index, actual): ...
    @staticmethod  
    def failure(index, expected): ...

class ParseError(RuntimeError):
    def __init__(self, expected, text, index): ...

Core Primitives

Parser Combinators

Higher-order functions for combining and repeating parsers, including repetition operators (many, times, count) and composition utilities that enable building complex parsers from simple building blocks.

def times(p, mint, maxt=None): ...
def count(p, n): ...  
def many(p): ...
def many1(p): ...

Combinators

Character and String Parsing

Specialized parsers for character-level and string-level text processing, including literal string matching, regular expression support, character class matching, and whitespace handling.

def string(s): ...
def regex(exp, flags=0): ...
def one_of(s): ...
def none_of(s): ...
def letter(): ...
def digit(): ...
def space(): ...
def spaces(): ...
def eof(): ...

Character Parsing

Parser Operators

Monadic and compositional operators for sequencing, choice, transformation, and control flow between parsers. These operators enable both infix notation and functional composition patterns.

# Parser class methods for operators
def bind(self, fn): ...        # >>=
def compose(self, other): ...  # >>
def choice(self, other): ...   # |
def try_choice(self, other): ... # ^
def joint(self, other): ...    # +
def parsecmap(self, fn): ...

Parser Operators

Parser Generation

Powerful declarative syntax using Python generators to build complex parsers with natural control flow, variable binding, and conditional logic while maintaining the functional parser combinator foundation.

def generate(fn): ...

# Usage pattern:
@generate
def my_parser():
    result1 = yield parser1
    result2 = yield parser2  
    return combine(result1, result2)

Parser Generation

Types

class ParseError(RuntimeError):
    """Parser error with location information."""
    expected: str
    text: str
    index: int
    
    def loc(self) -> str: ...
    @staticmethod
    def loc_info(text: str, index: int) -> tuple[int, int]: ...

class Value:
    """Parser result container."""
    status: bool
    index: int
    value: any
    expected: str
    
    def aggregate(self, other) -> Value: ...

class Parser:
    """Core parser combinator class."""
    def __call__(self, text: str, index: int) -> Value: ...