varphi-devkit 1.0.0__tar.gz

varphi_devkit-1.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Hassan El-Sheikha
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

varphi_devkit-1.0.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.3
+Name: varphi-devkit
+Version: 1.0.0
+Summary: A Python framework for creating compilers that target the Varphi language
+License: BSD-3-Clause
+Keywords: compiler,turing-machine,dsl,antlr,parser
+Author: Hassan El-Sheikha
+Author-email: hmelsheikha@gmail.com
+Requires-Python: >=3.10
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: antlr4-python3-runtime (>=4.13.2,<5.0.0)
+Description-Content-Type: text/markdown
+
+# Varphi Development Kit
+
+A Python framework for creating compilers that target the Varphi language - a domain-specific language for describing Turing machine transition rules.
+
+## Overview
+
+Varphi is a minimalist language designed to represent Turing machine programs using simple transition rules. The Varphi Development Kit provides a flexible compiler framework that allows you to build custom compilers to transform Varphi programs into any target format.
+
+## Installation
+
+```bash
+pip install varphi-devkit
+```
+
+**Requirements:**
+- Python ≥ 3.10
+
+## Varphi Language Syntax
+
+Varphi programs consist of transition rules with the following syntax:
+
+```
+STATE TAPE_CHARACTER STATE TAPE_CHARACTER HEAD_DIRECTION
+```
+
+Where:
+- **STATE**: Current/target state (format: `q` followed by alphanumeric characters, e.g., `q0`, `q_start`, `q1_accept`)
+- **TAPE_CHARACTER**: Tape symbol (`0` for blank, `1` for marked)
+- **HEAD_DIRECTION**: Head movement (`L` for left, `R` for right)
+
+### Example Varphi Program
+
+```varphi
+// Simple addition-by-one program
+q0 1 q0 1 R
+q0 0 qHalt 1 R
+```
+
+### Language Features
+
+- **Comments**: Single-line (`//`) and multi-line (`/* */`) comments are supported
+- **Whitespace**: Flexible whitespace handling (spaces, tabs, newlines)
+- **States**: Flexible state naming with `q` prefix
+
+## Core Architecture
+
+The framework is built around these key components:
+
+### Data Model
+
+- **`VarphiTapeCharacter`**: Enum for tape symbols (`BLANK="0"`, `ONE="1"`)
+- **`VarphiHeadDirection`**: Enum for head movement (`LEFT="L"`, `RIGHT="R"`)
+- **`VarphiLine`**: Dataclass representing a transition rule with fields:
+  - `if_state`: Current state
+  - `if_condition`: Current tape character
+  - `then_state`: Next state  
+  - `then_character`: Character to write
+  - `then_direction`: Direction to move
+
+### Compiler Framework
+
+- **`VarphiCompiler`**: Abstract base class for implementing custom compilers
+- **`compile_varphi()`**: Function to parse and compile Varphi programs
+- **`VarphiSyntaxError`**: Exception for syntax errors
+
+## Usage
+
+### Creating a Custom Compiler
+
+To create a Varphi compiler, subclass `VarphiCompiler` and implement three methods:
+
+```python
+from varphi_devkit import VarphiCompiler, VarphiLine, compile_varphi
+
+class MyCompiler(VarphiCompiler):
+    def __init__(self):
+        # Initialize your compiler's state
+        self.output = []
+    
+    def handle_line(self, line: VarphiLine):
+        # Process each transition rule
+        self.output.append(f"Transition: {line.if_state} -> {line.then_state}")
+    
+    def generate_compiled_program(self) -> str:
+        # Return the final compiled output
+        return "\n".join(self.output)
+
+# Use your compiler
+program = """
+q0 0 q1 1 R
+q1 1 q_halt 0 L
+"""
+
+compiler = MyCompiler()
+result = compile_varphi(program, compiler)
+print(result)
+```
+
+## Example Toy Compilers
+
+The framework's test suite includes several [example compilers](/tests/toy_compilers) that demonstrate different use cases.
+
+## Error Handling
+
+The framework provides comprehensive syntax error reporting out of the box:
+
+```python
+from varphi_devkit import VarphiSyntaxError, compile_varphi
+from your_compiler import YourCompiler
+
+try:
+    result = compile_varphi("invalid syntax here", YourCompiler())
+except VarphiSyntaxError as e:
+    print(f"Syntax error at line {e.line}, column {e.column}: {e.message}")
+```
+
+## API Reference
+
+### Core Functions
+
+#### `compile_varphi(program: str, compiler: VarphiCompiler) -> str`
+
+Parses and compiles a Varphi program using the provided compiler.
+
+- **Parameters:**
+  - `program`: Varphi source code as a string
+  - `compiler`: VarphiCompiler instance to process the program
+- **Returns:** Compiled program output from the compiler
+- **Raises:** `VarphiSyntaxError` for invalid syntax
+
+### Abstract Base Class
+
+#### `VarphiCompiler`
+
+Abstract base class for implementing custom Varphi compilers.
+
+**Abstract Methods:**
+- `__init__(self) -> None`: Initialize compiler state
+- `handle_line(self, line: VarphiLine) -> None`: Process a transition rule (line in the Varphi program)
+- `generate_compiled_program(self) -> str`: Return final compiled output
+
+### Data Classes
+
+#### `VarphiLine`
+
+Represents a single transition rule with attributes:
+- `if_state: str` - Current state
+- `if_condition: VarphiTapeCharacter` - Current tape character
+- `then_state: str` - Next state
+- `then_character: VarphiTapeCharacter` - Character to write
+- `then_direction: VarphiHeadDirection` - Head movement direction
+
+#### `VarphiTapeCharacter`
+
+Enum for tape characters:
+- `BLANK = "0"` - Empty tape cell
+- `ONE = "1"` - Marked tape cell
+
+#### `VarphiHeadDirection`
+
+Enum for head movement:
+- `LEFT = "L"` - Move head left
+- `RIGHT = "R"` - Move head right
+
+### Exceptions
+
+#### `VarphiSyntaxError`
+
+Exception raised for syntax errors in Varphi programs.
+
+**Attributes:**
+- `message: str` - Error description
+- `line: int` - Line number where error occurred
+- `column: int` - Column position of error
+
+## License
+
+This project is available under the BSD-3-Clause License (see [LICENSE](LICENSE)).
+

varphi_devkit-1.0.0/README.md

@@ -0,0 +1,178 @@
+# Varphi Development Kit
+
+A Python framework for creating compilers that target the Varphi language - a domain-specific language for describing Turing machine transition rules.
+
+## Overview
+
+Varphi is a minimalist language designed to represent Turing machine programs using simple transition rules. The Varphi Development Kit provides a flexible compiler framework that allows you to build custom compilers to transform Varphi programs into any target format.
+
+## Installation
+
+```bash
+pip install varphi-devkit
+```
+
+**Requirements:**
+- Python ≥ 3.10
+
+## Varphi Language Syntax
+
+Varphi programs consist of transition rules with the following syntax:
+
+```
+STATE TAPE_CHARACTER STATE TAPE_CHARACTER HEAD_DIRECTION
+```
+
+Where:
+- **STATE**: Current/target state (format: `q` followed by alphanumeric characters, e.g., `q0`, `q_start`, `q1_accept`)
+- **TAPE_CHARACTER**: Tape symbol (`0` for blank, `1` for marked)
+- **HEAD_DIRECTION**: Head movement (`L` for left, `R` for right)
+
+### Example Varphi Program
+
+```varphi
+// Simple addition-by-one program
+q0 1 q0 1 R
+q0 0 qHalt 1 R
+```
+
+### Language Features
+
+- **Comments**: Single-line (`//`) and multi-line (`/* */`) comments are supported
+- **Whitespace**: Flexible whitespace handling (spaces, tabs, newlines)
+- **States**: Flexible state naming with `q` prefix
+
+## Core Architecture
+
+The framework is built around these key components:
+
+### Data Model
+
+- **`VarphiTapeCharacter`**: Enum for tape symbols (`BLANK="0"`, `ONE="1"`)
+- **`VarphiHeadDirection`**: Enum for head movement (`LEFT="L"`, `RIGHT="R"`)
+- **`VarphiLine`**: Dataclass representing a transition rule with fields:
+  - `if_state`: Current state
+  - `if_condition`: Current tape character
+  - `then_state`: Next state  
+  - `then_character`: Character to write
+  - `then_direction`: Direction to move
+
+### Compiler Framework
+
+- **`VarphiCompiler`**: Abstract base class for implementing custom compilers
+- **`compile_varphi()`**: Function to parse and compile Varphi programs
+- **`VarphiSyntaxError`**: Exception for syntax errors
+
+## Usage
+
+### Creating a Custom Compiler
+
+To create a Varphi compiler, subclass `VarphiCompiler` and implement three methods:
+
+```python
+from varphi_devkit import VarphiCompiler, VarphiLine, compile_varphi
+
+class MyCompiler(VarphiCompiler):
+    def __init__(self):
+        # Initialize your compiler's state
+        self.output = []
+    
+    def handle_line(self, line: VarphiLine):
+        # Process each transition rule
+        self.output.append(f"Transition: {line.if_state} -> {line.then_state}")
+    
+    def generate_compiled_program(self) -> str:
+        # Return the final compiled output
+        return "\n".join(self.output)
+
+# Use your compiler
+program = """
+q0 0 q1 1 R
+q1 1 q_halt 0 L
+"""
+
+compiler = MyCompiler()
+result = compile_varphi(program, compiler)
+print(result)
+```
+
+## Example Toy Compilers
+
+The framework's test suite includes several [example compilers](/tests/toy_compilers) that demonstrate different use cases.
+
+## Error Handling
+
+The framework provides comprehensive syntax error reporting out of the box:
+
+```python
+from varphi_devkit import VarphiSyntaxError, compile_varphi
+from your_compiler import YourCompiler
+
+try:
+    result = compile_varphi("invalid syntax here", YourCompiler())
+except VarphiSyntaxError as e:
+    print(f"Syntax error at line {e.line}, column {e.column}: {e.message}")
+```
+
+## API Reference
+
+### Core Functions
+
+#### `compile_varphi(program: str, compiler: VarphiCompiler) -> str`
+
+Parses and compiles a Varphi program using the provided compiler.
+
+- **Parameters:**
+  - `program`: Varphi source code as a string
+  - `compiler`: VarphiCompiler instance to process the program
+- **Returns:** Compiled program output from the compiler
+- **Raises:** `VarphiSyntaxError` for invalid syntax
+
+### Abstract Base Class
+
+#### `VarphiCompiler`
+
+Abstract base class for implementing custom Varphi compilers.
+
+**Abstract Methods:**
+- `__init__(self) -> None`: Initialize compiler state
+- `handle_line(self, line: VarphiLine) -> None`: Process a transition rule (line in the Varphi program)
+- `generate_compiled_program(self) -> str`: Return final compiled output
+
+### Data Classes
+
+#### `VarphiLine`
+
+Represents a single transition rule with attributes:
+- `if_state: str` - Current state
+- `if_condition: VarphiTapeCharacter` - Current tape character
+- `then_state: str` - Next state
+- `then_character: VarphiTapeCharacter` - Character to write
+- `then_direction: VarphiHeadDirection` - Head movement direction
+
+#### `VarphiTapeCharacter`
+
+Enum for tape characters:
+- `BLANK = "0"` - Empty tape cell
+- `ONE = "1"` - Marked tape cell
+
+#### `VarphiHeadDirection`
+
+Enum for head movement:
+- `LEFT = "L"` - Move head left
+- `RIGHT = "R"` - Move head right
+
+### Exceptions
+
+#### `VarphiSyntaxError`
+
+Exception raised for syntax errors in Varphi programs.
+
+**Attributes:**
+- `message: str` - Error description
+- `line: int` - Line number where error occurred
+- `column: int` - Column position of error
+
+## License
+
+This project is available under the BSD-3-Clause License (see [LICENSE](LICENSE)).

varphi_devkit-1.0.0/pyproject.toml

@@ -0,0 +1,110 @@
+[project]
+name = "varphi-devkit"
+version = "1.0.0"
+description = "A Python framework for creating compilers that target the Varphi language"
+authors = [
+    {name = "Hassan El-Sheikha",email = "hmelsheikha@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["compiler", "turing-machine", "dsl", "antlr", "parser"]
+license = {text = "BSD-3-Clause"}
+homepage = "https://github.com/varphi-lang/varphi-devkit"
+repository = "https://github.com/varphi-lang/varphi-devkit"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Compilers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "antlr4-python3-runtime (>=4.13.2,<5.0.0)",
+]
+
+[tool.poetry]
+packages = [{include = "varphi_devkit", from = "src"}]
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.4.1"
+pylint = "^3.3.7"
+antlr4-tools = "^0.2.2"
+python-semantic-release = "^10.2.0"
+build = "^1.3.0"
+twine = "^6.1.0"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[semantic_release]
+assets = []
+build_command_env = []
+commit_message = "{version}\n\nAutomatically generated by python-semantic-release"
+commit_parser = "conventional"
+logging_use_named_masks = false
+major_on_zero = true
+allow_zero_version = false
+repo_dir = "."
+no_git_verify = false
+tag_format = "v{version}"
+version_toml = ["pyproject.toml:project.version"]
+
+[semantic_release.branches.main]
+match = "(main|master)"
+prerelease_token = "rc"
+prerelease = false
+
+[semantic_release.changelog]
+exclude_commit_patterns = []
+mode = "update"
+insertion_flag = "<!-- version list -->"
+template_dir = "templates"
+
+[semantic_release.changelog.default_templates]
+changelog_file = "CHANGELOG.md"
+output_format = "md"
+mask_initial_release = true
+
+[semantic_release.changelog.environment]
+block_start_string = "{%"
+block_end_string = "%}"
+variable_start_string = "{{"
+variable_end_string = "}}"
+comment_start_string = "{#"
+comment_end_string = "#}"
+trim_blocks = false
+lstrip_blocks = false
+newline_sequence = "\n"
+keep_trailing_newline = false
+extensions = []
+autoescape = false
+
+[semantic_release.commit_author]
+env = "GIT_COMMIT_AUTHOR"
+default = "semantic-release <semantic-release>"
+
+[semantic_release.commit_parser_options]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+other_allowed_tags = ["build", "chore", "ci", "docs", "style", "refactor", "test"]
+allowed_tags = ["feat", "fix", "perf", "build", "chore", "ci", "docs", "style", "refactor", "test"]
+default_bump_level = 0
+parse_squash_commits = true
+ignore_merge_commits = true
+
+[semantic_release.remote]
+name = "origin"
+type = "github"
+ignore_token_for_push = false
+insecure = false
+
+[semantic_release.publish]
+dist_glob_patterns = ["dist/*"]
+upload_to_vcs_release = true
+

varphi_devkit-1.0.0/src/varphi_devkit/__init__.py

@@ -0,0 +1,33 @@
+"""
+Varphi Development Kit
+
+A Python toolkit for working with the Varphi language - a domain-specific
+language for describing Turing machine transition rules.
+
+Main Components:
+
+Model Classes:
+- VarphiTapeCharacter: Represents tape characters (0 for blank, 1 for tally)
+- VarphiHeadDirection: Represents head movement (L for left, R for right)  
+- VarphiLine: Represents a complete transition rule
+
+Compilation:
+- VarphiCompiler: Abstract base class for implementing Varphi compilers
+- compile: Function to compile Varphi programs using a given compiler
+
+Error Handling:
+- VarphiSyntaxError: Exception raised for syntax errors in Varphi code
+"""
+
+from .model import VarphiTapeCharacter, VarphiHeadDirection, VarphiLine
+from .compilation import VarphiCompiler, compile_varphi
+from .syntax.error_listener import VarphiSyntaxError
+
+__all__ = [
+    "VarphiTapeCharacter",
+    "VarphiHeadDirection", 
+    "VarphiLine",
+    "VarphiCompiler",
+    "compile_varphi",
+    "VarphiSyntaxError",
+]

varphi_devkit-1.0.0/src/varphi_devkit/compilation.py

@@ -0,0 +1,119 @@
+"""Compilation infrastructure for Varphi language programs.
+
+This module provides the compilation framework for translating Varphi programs 
+(Turing machine descriptions) into target languages. Users implement custom 
+compilers by subclassing VarphiCompiler and defining how individual transition 
+rules should be processed.
+
+Usage:
+    1. Subclass VarphiCompiler and implement the abstract methods:
+       - __init__(): Set up your compiler's initial state
+       - handleLine(): Process each transition rule (VarphiLine)  
+       - generate_compiled_program(): Return the final compiled output
+    
+    2. Use the compile() function with your compiler instance:
+       compiled_output = compile(varphi_program_text, your_compiler_instance)
+
+Classes:
+    VarphiCompiler: Abstract base class for implementing custom compilers.
+
+Functions:
+    compile: Parses a Varphi program and compiles it using the provided compiler.
+"""
+
+import logging
+from abc import ABC, abstractmethod
+
+from antlr4 import InputStream, CommonTokenStream, ParseTreeWalker
+
+from .syntax.antlr.VarphiLexer import VarphiLexer
+from .syntax.antlr.VarphiParser import VarphiParser
+from .syntax.antlr.VarphiListener import VarphiListener
+from .syntax.error_listener import VarphiSyntaxErrorListener
+from .model import VarphiTapeCharacter, VarphiHeadDirection, VarphiLine
+
+
+
+logger = logging.getLogger(__name__)
+
+
+class VarphiCompiler(VarphiListener, ABC):
+    """Abstract base class for compiling Varphi programs into target languages.
+    
+    Subclasses must implement the abstract methods to define compilation behavior.
+    Inherits from VarphiListener to receive ANTLR parse tree events.
+    
+    Abstract Methods:
+        __init__: Initialize compiler state
+        handleLine: Process a single transition rule
+        generate_compiled_program: Return the final compiled output
+    """
+    @abstractmethod
+    def __init__(self) -> None:
+        """Initialize the compiler's state and data structures."""
+
+
+    @abstractmethod
+    def handle_line(self, line: VarphiLine) -> None:
+        """Process a single transition rule (line in the Varphi program).
+        
+        Args:
+            line: The VarphiLine object representing a transition rule
+        """
+
+
+    @abstractmethod
+    def generate_compiled_program(self) -> str:
+        """Generate and return the final compiled program as a string.
+        
+        Returns:
+            The complete compiled program in the target language
+        """
+
+
+    def enterLine(self, ctx: VarphiParser.LineContext) -> None:
+        """Parse ANTLR line context and delegate to handleLine.
+        
+        Args:
+            ctx: The ANTLR parser context for the line rule
+        """
+        logging.debug("Entering line %s", ctx.start.line)
+        if_state = str(ctx.STATE(0).getText())
+        logging.debug("If state: %s", if_state)
+        tape_character = VarphiTapeCharacter(ctx.TAPE_CHARACTER(0).getText())
+        logging.debug("Tape character: %s", tape_character)
+        then_state = str(ctx.STATE(1).getText())
+        logging.debug("Then state: %s", then_state)
+        then_character = VarphiTapeCharacter(ctx.TAPE_CHARACTER(1).getText())
+        logging.debug("Then character: %s", then_character)
+        then_direction = VarphiHeadDirection(ctx.HEAD_DIRECTION().getText())
+        logging.debug("Then direction: %s", then_direction)
+        line = VarphiLine(if_state, tape_character, then_state, then_character, then_direction)
+        logging.debug("Delegating to handleLine() helper method")
+        self.handle_line(line)
+
+
+
+def compile_varphi(program: str, compiler: VarphiCompiler) -> str:
+    """Parse and compile a Varphi program using the provided compiler.
+    
+    Args:
+        program: The Varphi program source code as a string
+        compiler: A VarphiCompiler instance to process the program
+        
+    Returns:
+        The compiled program output from the compiler
+    """
+    input_stream = InputStream(program)
+    error_listener = VarphiSyntaxErrorListener(program)
+    lexer = VarphiLexer(input_stream)
+    lexer.removeErrorListeners()
+    lexer.addErrorListener(error_listener)
+    token_stream = CommonTokenStream(lexer)
+    parser = VarphiParser(token_stream)
+    parser.removeErrorListeners()
+    parser.addErrorListener(error_listener)
+    parse_tree = parser.program()
+    walker = ParseTreeWalker()
+    walker.walk(compiler, parse_tree)
+    return compiler.generate_compiled_program()

varphi_devkit-1.0.0/src/varphi_devkit/model.py

@@ -0,0 +1,53 @@
+"""Data model for representing Varphi language programs.
+
+This module provides the core data types for representing Varphi programs
+(Turing machine descriptions) including tape characters, head directions,
+and transition rules.
+
+Classes:
+    VarphiTapeCharacter: Enum for possible tape characters (0, 1).
+    VarphiHeadDirection: Enum for head movement directions (L, R).
+    VarphiLine: Dataclass representing a single transition rule.
+"""
+
+from enum import Enum
+from dataclasses import dataclass
+
+class VarphiTapeCharacter(Enum):
+    """Represents the possible characters on a Turing machine tape.
+    
+    Attributes:
+        BLANK: Represents the blank/empty tape cell (character '0').
+        ONE: Represents the marked tape cell (character '1').
+    """
+    BLANK = "0"
+    ONE = "1"
+
+
+class VarphiHeadDirection(Enum):
+    """Represents the possible head movement directions for the Turing machine head.
+    
+    Attributes:
+        LEFT: Move the head one position to the left (character 'L').
+        RIGHT: Move the head one position to the right (character 'R').
+    """
+    LEFT = "L"
+    RIGHT = "R"
+
+
+@dataclass
+class VarphiLine:
+    """Represents a single line (transition rule) in a Varphi program.
+    
+    Attributes:
+        if_state: current state
+        if_condition: current tape character
+        then_state: next state
+        then_character: character to write
+        then_direction: direction to move the head
+    """
+    if_state: str
+    if_condition: VarphiTapeCharacter
+    then_state: str
+    then_character: VarphiTapeCharacter
+    then_direction: VarphiHeadDirection

varphi_devkit-1.0.0/src/varphi_devkit/syntax/Varphi.g4

@@ -0,0 +1,24 @@
+grammar Varphi;
+
+// Parser rules
+program : line* EOF;
+line : STATE TAPE_CHARACTER STATE TAPE_CHARACTER HEAD_DIRECTION;
+
+// Lexer rules
+fragment LEFT : 'L';
+fragment RIGHT : 'R';
+fragment TALLY : '1';
+fragment BLANK : '0';
+
+STATE : 'q'[a-zA-Z0-9_]+;
+TAPE_CHARACTER : TALLY | BLANK;
+HEAD_DIRECTION : LEFT | RIGHT;
+
+// Single-line comment (starts with // and ends at the end of the line)
+COMMENT : '//' ~[\r\n]* -> skip;
+
+// Multi-line comment (starts with /* and ends with */, can span multiple lines)
+MULTI_COMMENT : '/*' .*? '*/' -> skip;
+
+// Skip unnecessary whitespaces
+WHITESPACE : [ \t\r\n]+ -> skip;

varphi_devkit-1.0.0/src/varphi_devkit/syntax/__init__.py

@@ -0,0 +1,28 @@
+"""
+Varphi Syntax Module
+
+This module provides syntax analysis components for the Varphi language.
+
+Components:
+- VarphiLexer: Tokenizes Varphi source code
+- VarphiParser: Parses tokens into parse tree
+- VarphiListener: Provides callback interface for parse tree traversal
+- VarphiSyntaxError: Exception for syntax errors
+- VarphiSyntaxErrorListener: Error handler for parsing
+"""
+
+# Error handling components
+from .error_listener import VarphiSyntaxError, VarphiSyntaxErrorListener
+
+# ANTLR generated components
+from .antlr.VarphiLexer import VarphiLexer
+from .antlr.VarphiParser import VarphiParser
+from .antlr.VarphiListener import VarphiListener
+
+__all__ = [
+    "VarphiSyntaxError",
+    "VarphiSyntaxErrorListener", 
+    "VarphiLexer",
+    "VarphiParser", 
+    "VarphiListener",
+]

varphi_devkit-1.0.0/src/varphi_devkit/syntax/antlr/VarphiLexer.py

@@ -0,0 +1,76 @@
+# Generated from src/varphi_devkit/syntax/Varphi.g4 by ANTLR 4.13.2
+from antlr4 import *
+from io import StringIO
+import sys
+if sys.version_info[1] > 5:
+    from typing import TextIO
+else:
+    from typing.io import TextIO
+
+
+def serializedATN():
+    return [
+        4,0,6,75,6,-1,2,0,7,0,2,1,7,1,2,2,7,2,2,3,7,3,2,4,7,4,2,5,7,5,2,
+        6,7,6,2,7,7,7,2,8,7,8,2,9,7,9,1,0,1,0,1,1,1,1,1,2,1,2,1,3,1,3,1,
+        4,1,4,4,4,32,8,4,11,4,12,4,33,1,5,1,5,3,5,38,8,5,1,6,1,6,3,6,42,
+        8,6,1,7,1,7,1,7,1,7,5,7,48,8,7,10,7,12,7,51,9,7,1,7,1,7,1,8,1,8,
+        1,8,1,8,5,8,59,8,8,10,8,12,8,62,9,8,1,8,1,8,1,8,1,8,1,8,1,9,4,9,
+        70,8,9,11,9,12,9,71,1,9,1,9,1,60,0,10,1,0,3,0,5,0,7,0,9,1,11,2,13,
+        3,15,4,17,5,19,6,1,0,3,4,0,48,57,65,90,95,95,97,122,2,0,10,10,13,
+        13,3,0,9,10,13,13,32,32,76,0,9,1,0,0,0,0,11,1,0,0,0,0,13,1,0,0,0,
+        0,15,1,0,0,0,0,17,1,0,0,0,0,19,1,0,0,0,1,21,1,0,0,0,3,23,1,0,0,0,
+        5,25,1,0,0,0,7,27,1,0,0,0,9,29,1,0,0,0,11,37,1,0,0,0,13,41,1,0,0,
+        0,15,43,1,0,0,0,17,54,1,0,0,0,19,69,1,0,0,0,21,22,5,76,0,0,22,2,
+        1,0,0,0,23,24,5,82,0,0,24,4,1,0,0,0,25,26,5,49,0,0,26,6,1,0,0,0,
+        27,28,5,48,0,0,28,8,1,0,0,0,29,31,5,113,0,0,30,32,7,0,0,0,31,30,
+        1,0,0,0,32,33,1,0,0,0,33,31,1,0,0,0,33,34,1,0,0,0,34,10,1,0,0,0,
+        35,38,3,5,2,0,36,38,3,7,3,0,37,35,1,0,0,0,37,36,1,0,0,0,38,12,1,
+        0,0,0,39,42,3,1,0,0,40,42,3,3,1,0,41,39,1,0,0,0,41,40,1,0,0,0,42,
+        14,1,0,0,0,43,44,5,47,0,0,44,45,5,47,0,0,45,49,1,0,0,0,46,48,8,1,
+        0,0,47,46,1,0,0,0,48,51,1,0,0,0,49,47,1,0,0,0,49,50,1,0,0,0,50,52,
+        1,0,0,0,51,49,1,0,0,0,52,53,6,7,0,0,53,16,1,0,0,0,54,55,5,47,0,0,
+        55,56,5,42,0,0,56,60,1,0,0,0,57,59,9,0,0,0,58,57,1,0,0,0,59,62,1,
+        0,0,0,60,61,1,0,0,0,60,58,1,0,0,0,61,63,1,0,0,0,62,60,1,0,0,0,63,
+        64,5,42,0,0,64,65,5,47,0,0,65,66,1,0,0,0,66,67,6,8,0,0,67,18,1,0,
+        0,0,68,70,7,2,0,0,69,68,1,0,0,0,70,71,1,0,0,0,71,69,1,0,0,0,71,72,
+        1,0,0,0,72,73,1,0,0,0,73,74,6,9,0,0,74,20,1,0,0,0,7,0,33,37,41,49,
+        60,71,1,6,0,0
+    ]
+
+class VarphiLexer(Lexer):
+
+    atn = ATNDeserializer().deserialize(serializedATN())
+
+    decisionsToDFA = [ DFA(ds, i) for i, ds in enumerate(atn.decisionToState) ]
+
+    STATE = 1
+    TAPE_CHARACTER = 2
+    HEAD_DIRECTION = 3
+    COMMENT = 4
+    MULTI_COMMENT = 5
+    WHITESPACE = 6
+
+    channelNames = [ u"DEFAULT_TOKEN_CHANNEL", u"HIDDEN" ]
+
+    modeNames = [ "DEFAULT_MODE" ]
+
+    literalNames = [ "<INVALID>",
+ ]
+
+    symbolicNames = [ "<INVALID>",
+            "STATE", "TAPE_CHARACTER", "HEAD_DIRECTION", "COMMENT", "MULTI_COMMENT", 
+            "WHITESPACE" ]
+
+    ruleNames = [ "LEFT", "RIGHT", "TALLY", "BLANK", "STATE", "TAPE_CHARACTER", 
+                  "HEAD_DIRECTION", "COMMENT", "MULTI_COMMENT", "WHITESPACE" ]
+
+    grammarFileName = "Varphi.g4"
+
+    def __init__(self, input=None, output:TextIO = sys.stdout):
+        super().__init__(input, output)
+        self.checkVersion("4.13.2")
+        self._interp = LexerATNSimulator(self, self.atn, self.decisionsToDFA, PredictionContextCache())
+        self._actions = None
+        self._predicates = None
+
+

varphi_devkit-1.0.0/src/varphi_devkit/syntax/antlr/VarphiListener.py

@@ -0,0 +1,30 @@
+# Generated from src/varphi_devkit/syntax/Varphi.g4 by ANTLR 4.13.2
+from antlr4 import *
+if "." in __name__:
+    from .VarphiParser import VarphiParser
+else:
+    from VarphiParser import VarphiParser
+
+# This class defines a complete listener for a parse tree produced by VarphiParser.
+class VarphiListener(ParseTreeListener):
+
+    # Enter a parse tree produced by VarphiParser#program.
+    def enterProgram(self, ctx:VarphiParser.ProgramContext):
+        pass
+
+    # Exit a parse tree produced by VarphiParser#program.
+    def exitProgram(self, ctx:VarphiParser.ProgramContext):
+        pass
+
+
+    # Enter a parse tree produced by VarphiParser#line.
+    def enterLine(self, ctx:VarphiParser.LineContext):
+        pass
+
+    # Exit a parse tree produced by VarphiParser#line.
+    def exitLine(self, ctx:VarphiParser.LineContext):
+        pass
+
+
+
+del VarphiParser

varphi_devkit-1.0.0/src/varphi_devkit/syntax/antlr/VarphiParser.py

@@ -0,0 +1,180 @@
+# Generated from src/varphi_devkit/syntax/Varphi.g4 by ANTLR 4.13.2
+# encoding: utf-8
+from antlr4 import *
+from io import StringIO
+import sys
+if sys.version_info[1] > 5:
+	from typing import TextIO
+else:
+	from typing.io import TextIO
+
+def serializedATN():
+    return [
+        4,1,6,19,2,0,7,0,2,1,7,1,1,0,5,0,6,8,0,10,0,12,0,9,9,0,1,0,1,0,1,
+        1,1,1,1,1,1,1,1,1,1,1,1,1,0,0,2,0,2,0,0,17,0,7,1,0,0,0,2,12,1,0,
+        0,0,4,6,3,2,1,0,5,4,1,0,0,0,6,9,1,0,0,0,7,5,1,0,0,0,7,8,1,0,0,0,
+        8,10,1,0,0,0,9,7,1,0,0,0,10,11,5,0,0,1,11,1,1,0,0,0,12,13,5,1,0,
+        0,13,14,5,2,0,0,14,15,5,1,0,0,15,16,5,2,0,0,16,17,5,3,0,0,17,3,1,
+        0,0,0,1,7
+    ]
+
+class VarphiParser ( Parser ):
+
+    grammarFileName = "Varphi.g4"
+
+    atn = ATNDeserializer().deserialize(serializedATN())
+
+    decisionsToDFA = [ DFA(ds, i) for i, ds in enumerate(atn.decisionToState) ]
+
+    sharedContextCache = PredictionContextCache()
+
+    literalNames = [  ]
+
+    symbolicNames = [ "<INVALID>", "STATE", "TAPE_CHARACTER", "HEAD_DIRECTION", 
+                      "COMMENT", "MULTI_COMMENT", "WHITESPACE" ]
+
+    RULE_program = 0
+    RULE_line = 1
+
+    ruleNames =  [ "program", "line" ]
+
+    EOF = Token.EOF
+    STATE=1
+    TAPE_CHARACTER=2
+    HEAD_DIRECTION=3
+    COMMENT=4
+    MULTI_COMMENT=5
+    WHITESPACE=6
+
+    def __init__(self, input:TokenStream, output:TextIO = sys.stdout):
+        super().__init__(input, output)
+        self.checkVersion("4.13.2")
+        self._interp = ParserATNSimulator(self, self.atn, self.decisionsToDFA, self.sharedContextCache)
+        self._predicates = None
+
+
+
+
+    class ProgramContext(ParserRuleContext):
+        __slots__ = 'parser'
+
+        def __init__(self, parser, parent:ParserRuleContext=None, invokingState:int=-1):
+            super().__init__(parent, invokingState)
+            self.parser = parser
+
+        def EOF(self):
+            return self.getToken(VarphiParser.EOF, 0)
+
+        def line(self, i:int=None):
+            if i is None:
+                return self.getTypedRuleContexts(VarphiParser.LineContext)
+            else:
+                return self.getTypedRuleContext(VarphiParser.LineContext,i)
+
+
+        def getRuleIndex(self):
+            return VarphiParser.RULE_program
+
+        def enterRule(self, listener:ParseTreeListener):
+            if hasattr( listener, "enterProgram" ):
+                listener.enterProgram(self)
+
+        def exitRule(self, listener:ParseTreeListener):
+            if hasattr( listener, "exitProgram" ):
+                listener.exitProgram(self)
+
+
+
+
+    def program(self):
+
+        localctx = VarphiParser.ProgramContext(self, self._ctx, self.state)
+        self.enterRule(localctx, 0, self.RULE_program)
+        self._la = 0 # Token type
+        try:
+            self.enterOuterAlt(localctx, 1)
+            self.state = 7
+            self._errHandler.sync(self)
+            _la = self._input.LA(1)
+            while _la==1:
+                self.state = 4
+                self.line()
+                self.state = 9
+                self._errHandler.sync(self)
+                _la = self._input.LA(1)
+
+            self.state = 10
+            self.match(VarphiParser.EOF)
+        except RecognitionException as re:
+            localctx.exception = re
+            self._errHandler.reportError(self, re)
+            self._errHandler.recover(self, re)
+        finally:
+            self.exitRule()
+        return localctx
+
+
+    class LineContext(ParserRuleContext):
+        __slots__ = 'parser'
+
+        def __init__(self, parser, parent:ParserRuleContext=None, invokingState:int=-1):
+            super().__init__(parent, invokingState)
+            self.parser = parser
+
+        def STATE(self, i:int=None):
+            if i is None:
+                return self.getTokens(VarphiParser.STATE)
+            else:
+                return self.getToken(VarphiParser.STATE, i)
+
+        def TAPE_CHARACTER(self, i:int=None):
+            if i is None:
+                return self.getTokens(VarphiParser.TAPE_CHARACTER)
+            else:
+                return self.getToken(VarphiParser.TAPE_CHARACTER, i)
+
+        def HEAD_DIRECTION(self):
+            return self.getToken(VarphiParser.HEAD_DIRECTION, 0)
+
+        def getRuleIndex(self):
+            return VarphiParser.RULE_line
+
+        def enterRule(self, listener:ParseTreeListener):
+            if hasattr( listener, "enterLine" ):
+                listener.enterLine(self)
+
+        def exitRule(self, listener:ParseTreeListener):
+            if hasattr( listener, "exitLine" ):
+                listener.exitLine(self)
+
+
+
+
+    def line(self):
+
+        localctx = VarphiParser.LineContext(self, self._ctx, self.state)
+        self.enterRule(localctx, 2, self.RULE_line)
+        try:
+            self.enterOuterAlt(localctx, 1)
+            self.state = 12
+            self.match(VarphiParser.STATE)
+            self.state = 13
+            self.match(VarphiParser.TAPE_CHARACTER)
+            self.state = 14
+            self.match(VarphiParser.STATE)
+            self.state = 15
+            self.match(VarphiParser.TAPE_CHARACTER)
+            self.state = 16
+            self.match(VarphiParser.HEAD_DIRECTION)
+        except RecognitionException as re:
+            localctx.exception = re
+            self._errHandler.reportError(self, re)
+            self._errHandler.recover(self, re)
+        finally:
+            self.exitRule()
+        return localctx
+
+
+
+
+

varphi_devkit-1.0.0/src/varphi_devkit/syntax/antlr/__init__.py

@@ -0,0 +1,21 @@
+"""
+ANTLR Generated Components for Varphi Language
+
+This module contains the ANTLR-generated lexer, parser, and listener components
+for the Varphi language.
+
+Components:
+- VarphiLexer: Generated lexer for tokenizing Varphi source code
+- VarphiParser: Generated parser for creating parse trees
+- VarphiListener: Generated base listener for parse tree traversal
+"""
+
+from .VarphiLexer import VarphiLexer
+from .VarphiParser import VarphiParser
+from .VarphiListener import VarphiListener
+
+__all__ = [
+    "VarphiLexer",
+    "VarphiParser", 
+    "VarphiListener",
+]

varphi_devkit-1.0.0/src/varphi_devkit/syntax/error_listener.py

@@ -0,0 +1,79 @@
+"""Custom error handling for Varphi language syntax errors.
+
+This module provides error handling components for the Varphi language parser.
+
+Classes:
+    VarphiSyntaxError: Custom exception for Varphi syntax errors with line/column info.
+    VarphiSyntaxErrorListener: ANTLR4 error listener that formats and raises syntax errors.
+"""
+
+from antlr4.error.ErrorListener import ErrorListener
+
+
+class VarphiSyntaxError(Exception):
+    """Exception raised for general syntax errors."""
+
+    line: int
+    column: int
+
+    def __init__(self, message: str, line: int, column: int) -> None:
+        """Initializes a VarphiSyntaxError with a message, line, and column.
+
+        Args:
+            message (str): The error message.
+            line (int): The line where the error occurred.
+            column (int): The column where the error occurred.
+        """
+        super().__init__(message)
+        self.line = line
+        self.column = column
+
+
+class VarphiSyntaxErrorListener(ErrorListener):
+    """Custom error listener for Varphi syntax errors.
+
+    This listener processes syntax errors and raises an exception with a detailed
+    error message, including the specific line and column where the error occurred.
+    """
+
+    input_text: list[str]
+
+    def __init__(self, input_text: str) -> None:
+        """Initializes the VarphiSyntaxErrorListener with the input text.
+
+        Args:
+            input_text (str): The input text to be processed.
+        """
+        super().__init__()
+        self.input_text = input_text.splitlines()
+
+    def syntaxError(self,  # pylint: disable=too-many-arguments, too-many-positional-arguments
+                    recognizer,
+                    offendingSymbol,
+                    line,
+                    column,
+                    msg,
+                    e
+    ) -> None:
+        """Handles syntax errors encountered by the parser.
+
+        Raises a VarphiSyntaxError with detailed information about the error.
+
+        Args:
+            recognizer: The recognizer that encountered the error.
+            offending_symbol: The symbol that caused the error.
+            line (int): The line number where the error occurred.
+            column (int): The column number where the error occurred.
+            msg (str): The error message.
+            e: The exception that caused the error.
+        """
+        error_line = self.input_text[line - 1]
+        # Create a line with ^ pointing to the offending symbol
+        pointer_line = " " * column + "^"
+
+        # Format the error message
+        error = f"Syntax error at line {line}:{column} - {msg}\n"
+        error += f"    {error_line}\n"
+        error += f"    {pointer_line}\n"
+
+        raise VarphiSyntaxError(error, line, column)