neotoma-py

Python bindings for the Neotoma parsing library.

Installation

pip install maturin
maturin build --release
target/wheels/neotoma_py-VERSION.whl

Usage

import neotoma

# Parse a grammar and use it to parse input
grammar = neotoma.Grammar('digits')
result = grammar.parse("12345")
print(result)

# Or use the convenience function
result = neotoma.parse_with_grammar('digits', "12345")
print(result)

Grammar Syntax

Terminals and Literals

• "terminal" - matches literal string (with \" for escaped quotes)

Built-in Character Classes

• digits - matches one or more decimal digits (0-9)
• alpha - matches one or more alphabetic characters (ASCII)
• alphanumeric - matches one or more alphanumeric characters (ASCII)
• whitespace - matches one or more whitespace characters (ASCII)
• hexdigits - matches one or more hexadecimal digits (0-9, a-f, A-F)

Unicode Character Classes

• udigits - matches one or more decimal digits (Unicode)
• ualpha - matches one or more alphabetic characters (Unicode)
• ualphanumeric - matches one or more alphanumeric characters (Unicode)
• uwhitespace - matches one or more whitespace characters (Unicode)

Custom Character Classes

• [abc] - matches any character in the set (custom character class)
• [^abc] - matches any character NOT in the set (negated character class)

Combinators

• (A B C) - matches A followed by B followed by C (sequence)
• (| A B C) - matches either A or B or C (alternatives)

Repetition

• (* A) - matches zero or more instances of A
• (+ A) - matches one or more instances of A
• (? A) - matches zero or one instances of A

Separated Repetition

• (* A / B) - matches zero or more A’s separated by B (trailing B allowed but not required)
• (+ A / B) - matches one or more A’s separated by B (trailing B allowed but not required)

Special Operators

• (< A) - reads until condition A is met (UTF-8 aware)
• (< A B) - reads until A, then parses the captured content with B

Named Rules

• name = rule - Names a parsing rule, for use in other rules and/or recursive rule definitions
• name - References a named rule. The built-in keywords (digits, alpha, etc.) are not valid rule names
• @start name - Identifies the starting rule for the grammar. If not provided, defaults to the last rule defined

Examples

import neotoma

# Simple digit parsing
grammar = neotoma.Grammar('digits')
result = grammar.parse("12345")

# Custom grammar with rules
grammar_text = '''
number = digits
word = alpha
sentence = (+ word whitespace)
@start sentence
'''
grammar = neotoma.Grammar(grammar_text)
result = grammar.parse("hello world test")

# Character class example
grammar = neotoma.Grammar('[aeiou]')  # vowels only
result = grammar.parse("a")

# Sequence and alternatives
grammar = neotoma.Grammar('(| "hello" "hi" "hey")')
result = grammar.parse("hello")

# Repetition with separator
grammar = neotoma.Grammar('(+ digits / ",")')  # comma-separated numbers
result = grammar.parse("1,2,3,4")