antlr4-c3 Python Port

This is a Python port of the antlr4-c3 library, providing code completion capabilities for ANTLR4-based parsers in Python.

Overview

The antlr4-c3 library provides a grammar-agnostic code completion engine for ANTLR4 parsers. This Python port maintains compatibility with the original TypeScript implementation while following Python conventions and best practices.

Installation

pip install antlr4-c3-python

Requirements

• Python 3.8+
• antlr4-python3-runtime

Usage

from antlr4 import InputStream, CommonTokenStream
from antlr4_c3 import CodeCompletionCore
from your_grammar import YourLexer, YourParser

# Setup parser
input_stream = InputStream("your code here")
lexer = YourLexer(input_stream)
token_stream = CommonTokenStream(lexer)
parser = YourParser(token_stream)

# Create completion core
core = CodeCompletionCore(parser)

# Configure preferred rules (optional)
core.preferred_rules = {YourParser.RULE_variableRef, YourParser.RULE_functionRef}

# Configure ignored tokens (optional)
core.ignored_tokens = {YourLexer.WS, YourLexer.COMMENT}

# Get completion candidates
candidates = core.collect_candidates(caret_position)

# Process results
for token_type, following_tokens in candidates.tokens.items():
    token_name = parser.vocabulary.get_display_name(token_type)
    print(f"Token: {token_name}")

for rule_index, rule_info in candidates.rules.items():
    rule_name = parser.rule_names[rule_index]
    print(f"Rule: {rule_name}")

Features

• Grammar-agnostic code completion
• Support for preferred rules and ignored tokens
• Debug output capabilities
• Symbol table integration
• Compatible with ANTLR4 Python runtime

Differences from TypeScript Version

• Uses Python naming conventions (snake_case instead of camelCase)
• Leverages Python's built-in data structures (set, dict, list)
• Uses Python logging framework for debug output
• Type hints for better IDE support

License

MIT License - see LICENSE file for details.