# 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)).
Raw data
{
"_id": null,
"home_page": null,
"name": "varphi-devkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "compiler, turing-machine, dsl, antlr, parser",
"author": "Hassan El-Sheikha",
"author_email": "hmelsheikha@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/61/65/2d8301b31a6ad5b4bc6b388779eb22536dc66ac3333811b871f3cdf20078/varphi_devkit-1.1.4.tar.gz",
"platform": null,
"description": "# Varphi Development Kit\n\nA Python framework for creating compilers that target the Varphi language - a domain-specific language for describing Turing machine transition rules.\n\n## Overview\n\nVarphi 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.\n\n## Installation\n\n```bash\npip install varphi-devkit\n```\n\n**Requirements:**\n- Python \u2265 3.10\n\n## Varphi Language Syntax\n\nVarphi programs consist of transition rules with the following syntax:\n\n```\nSTATE TAPE_CHARACTER STATE TAPE_CHARACTER HEAD_DIRECTION\n```\n\nWhere:\n- **STATE**: Current/target state (format: `q` followed by alphanumeric characters, e.g., `q0`, `q_start`, `q1_accept`)\n- **TAPE_CHARACTER**: Tape symbol (`0` for blank, `1` for marked)\n- **HEAD_DIRECTION**: Head movement (`L` for left, `R` for right)\n\n### Example Varphi Program\n\n```varphi\n// Simple addition-by-one program\nq0 1 q0 1 R\nq0 0 qHalt 1 R\n```\n\n### Language Features\n\n- **Comments**: Single-line (`//`) and multi-line (`/* */`) comments are supported\n- **Whitespace**: Flexible whitespace handling (spaces, tabs, newlines)\n- **States**: Flexible state naming with `q` prefix\n\n## Core Architecture\n\nThe framework is built around these key components:\n\n### Data Model\n\n- **`VarphiTapeCharacter`**: Enum for tape symbols (`BLANK=\"0\"`, `ONE=\"1\"`)\n- **`VarphiHeadDirection`**: Enum for head movement (`LEFT=\"L\"`, `RIGHT=\"R\"`)\n- **`VarphiLine`**: Dataclass representing a transition rule with fields:\n - `if_state`: Current state\n - `if_condition`: Current tape character\n - `then_state`: Next state \n - `then_character`: Character to write\n - `then_direction`: Direction to move\n\n### Compiler Framework\n\n- **`VarphiCompiler`**: Abstract base class for implementing custom compilers\n- **`compile_varphi()`**: Function to parse and compile Varphi programs\n- **`VarphiSyntaxError`**: Exception for syntax errors\n\n## Usage\n\n### Creating a Custom Compiler\n\nTo create a Varphi compiler, subclass `VarphiCompiler` and implement three methods:\n\n```python\nfrom varphi_devkit import VarphiCompiler, VarphiLine, compile_varphi\n\nclass MyCompiler(VarphiCompiler):\n def __init__(self):\n # Initialize your compiler's state\n self.output = []\n \n def handle_line(self, line: VarphiLine):\n # Process each transition rule\n self.output.append(f\"Transition: {line.if_state} -> {line.then_state}\")\n \n def generate_compiled_program(self) -> str:\n # Return the final compiled output\n return \"\\n\".join(self.output)\n\n# Use your compiler\nprogram = \"\"\"\nq0 0 q1 1 R\nq1 1 q_halt 0 L\n\"\"\"\n\ncompiler = MyCompiler()\nresult = compile_varphi(program, compiler)\nprint(result)\n```\n\n## Example Toy Compilers\n\nThe framework's test suite includes several [example compilers](/tests/toy_compilers) that demonstrate different use cases.\n\n## Error Handling\n\nThe framework provides comprehensive syntax error reporting out of the box:\n\n```python\nfrom varphi_devkit import VarphiSyntaxError, compile_varphi\nfrom your_compiler import YourCompiler\n\ntry:\n result = compile_varphi(\"invalid syntax here\", YourCompiler())\nexcept VarphiSyntaxError as e:\n print(f\"Syntax error at line {e.line}, column {e.column}: {e.message}\")\n```\n\n## API Reference\n\n### Core Functions\n\n#### `compile_varphi(program: str, compiler: VarphiCompiler) -> str`\n\nParses and compiles a Varphi program using the provided compiler.\n\n- **Parameters:**\n - `program`: Varphi source code as a string\n - `compiler`: VarphiCompiler instance to process the program\n- **Returns:** Compiled program output from the compiler\n- **Raises:** `VarphiSyntaxError` for invalid syntax\n\n### Abstract Base Class\n\n#### `VarphiCompiler`\n\nAbstract base class for implementing custom Varphi compilers.\n\n**Abstract Methods:**\n- `__init__(self) -> None`: Initialize compiler state\n- `handle_line(self, line: VarphiLine) -> None`: Process a transition rule (line in the Varphi program)\n- `generate_compiled_program(self) -> str`: Return final compiled output\n\n### Data Classes\n\n#### `VarphiLine`\n\nRepresents a single transition rule with attributes:\n- `if_state: str` - Current state\n- `if_condition: VarphiTapeCharacter` - Current tape character\n- `then_state: str` - Next state\n- `then_character: VarphiTapeCharacter` - Character to write\n- `then_direction: VarphiHeadDirection` - Head movement direction\n\n#### `VarphiTapeCharacter`\n\nEnum for tape characters:\n- `BLANK = \"0\"` - Empty tape cell\n- `ONE = \"1\"` - Marked tape cell\n\n#### `VarphiHeadDirection`\n\nEnum for head movement:\n- `LEFT = \"L\"` - Move head left\n- `RIGHT = \"R\"` - Move head right\n\n### Exceptions\n\n#### `VarphiSyntaxError`\n\nException raised for syntax errors in Varphi programs.\n\n**Attributes:**\n- `message: str` - Error description\n- `line: int` - Line number where error occurred\n- `column: int` - Column position of error\n\n## License\n\nThis project is available under the BSD-3-Clause License (see [LICENSE](LICENSE)).\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A Python framework for creating compilers that target the Varphi language",
"version": "1.1.4",
"project_urls": null,
"split_keywords": [
"compiler",
" turing-machine",
" dsl",
" antlr",
" parser"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c8f9a1a989838a50adb822efd4cfeb1124b718911b587662daf0bd48bf41b160",
"md5": "c23bbda27d68727da23c79dd5473c8b0",
"sha256": "55b582e24f38ade1d8a5238792575cb0ca503d27c6db5c48282d7f9af31cdd07"
},
"downloads": -1,
"filename": "varphi_devkit-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c23bbda27d68727da23c79dd5473c8b0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 13092,
"upload_time": "2025-08-04T01:00:26",
"upload_time_iso_8601": "2025-08-04T01:00:26.672679Z",
"url": "https://files.pythonhosted.org/packages/c8/f9/a1a989838a50adb822efd4cfeb1124b718911b587662daf0bd48bf41b160/varphi_devkit-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "61652d8301b31a6ad5b4bc6b388779eb22536dc66ac3333811b871f3cdf20078",
"md5": "b250a4409e7211ed6b7657dede1fff62",
"sha256": "4b4d92965424a3990aa2e6f0e82a57b13578d25ae8fe7eeda8e5214df98ec616"
},
"downloads": -1,
"filename": "varphi_devkit-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "b250a4409e7211ed6b7657dede1fff62",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 11451,
"upload_time": "2025-08-04T01:00:28",
"upload_time_iso_8601": "2025-08-04T01:00:28.034828Z",
"url": "https://files.pythonhosted.org/packages/61/65/2d8301b31a6ad5b4bc6b388779eb22536dc66ac3333811b871f3cdf20078/varphi_devkit-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 01:00:28",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "varphi-devkit"
}
JSON