antlr-ng-python - Next Generation ANTLR (Python Implementation)

Another Tool for Language Recognition - Python Edition

A Python implementation of the next generation ANTLR parser generator tool. This project ports the TypeScript antlr-ng tool to Python, providing a native Python experience while maintaining full compatibility with the original implementation.

🚀 Features

• Full ANTLR4 Grammar Support - Process any ANTLR4 grammar file
• Multiple Target Languages - Generate parsers for TypeScript, Java, C++, C#, Go, Python3, Dart, Swift, JavaScript, PHP
• Advanced Parsing - Adaptive LL(*) parsing algorithms
• Grammar Analysis - Built-in grammar validation and optimization
• Template-based Code Generation - Flexible output generation
• Python-Native - Idiomatic Python implementation with type hints

📦 Installation

# Install from PyPI (when published)
pip install antlr-ng-python

# Install from source
git clone https://github.com/djdax/antlr-ng-python.git
cd antlr-ng-python
pip install -e .

🛠️ Usage

Command Line Interface

# Basic usage
antlr-ng MyGrammar.g4

# Generate Python3 target
antlr-ng -Dlanguage=Python3 MyGrammar.g4

# Specify output directory
antlr-ng -o ./generated MyGrammar.g4

# Generate with listener and visitor
antlr-ng --generate-listener --generate-visitor MyGrammar.g4

# Show help
antlr-ng --help

Python API

from antlr_ng import Tool

# Create and configure tool
tool = Tool()

# Load and process grammar
grammar = tool.load_grammar("MyGrammar.g4")
tool.process(grammar, gen_code=True)

# Access generated files in output directory

Testing Grammars

# Test grammar with TestRig
testrig MyGrammar startRule input.txt

# Interactive interpreter
interpreter MyGrammar.g4 startRule

🏗️ Development Status

This is a work-in-progress Python port of the antlr-ng tool. Current status:

✅ Completed

• Project structure and packaging
• CLI interface with click
• Basic Tool class architecture
• Parameter parsing and validation
• Test framework setup

🚧 In Progress

• Grammar parsing with ANTLR4 Python runtime
• AST construction and manipulation
• Code generation pipeline
• Target language templates
• Error reporting system

📋 Planned

• Full feature parity with TypeScript version
• Performance optimizations
• Comprehensive test suite
• Documentation and examples

🔧 Development Setup

# Clone the repository
git clone https://github.com/djdax/antlr-ng-python.git
cd antlr-ng-python

# Set up development environment
python setup_dev.py

# Run tests
pytest

# Format code
black src/ tests/

# Type checking
mypy src/

📚 Examples

Check out the examples/ directory for sample grammars and usage patterns:

• simple_grammar.g4 - Basic arithmetic grammar
• usage_example.py - Python API demonstration

🤝 Contributing

Contributions are welcome! This project aims to:

1. Maintain API compatibility with the original TypeScript version
2. Follow Python best practices and conventions
3. Provide comprehensive type hints and documentation
4. Ensure cross-platform compatibility

📄 License

MIT License - see LICENSE.txt for details.

🔗 Related Projects

• antlr-ng - Original TypeScript implementation
• ANTLR4 - The original ANTLR parser generator
• antlr4-python3-runtime - ANTLR4 Python runtime

🌟 About ANTLR Next Generation

This Python implementation is part of the ANTLR Next Generation Project, which modernizes the ANTLR toolchain by:

• Separating the tool from target runtimes
• Improving maintainability and development velocity
• Adding new features while preserving compatibility
• Supporting modern development workflows

---

Note: This is an independent Python port and is not officially affiliated with the ANTLR project, though it aims to maintain compatibility and contribute to the ANTLR ecosystem.