# Tur - Turing Machine Language
**Tur** is a domain-specific language for defining and executing Turing machines, complete with parser, interpreter, and multi-platform visualization tools.
## Language Overview
Tur (`.tur` files) provides a clean, readable syntax for defining both single-tape and multi-tape Turing machines. The language includes:
- **Declarative syntax** for states, transitions, and tape configurations
- **Multi-tape support** with synchronized head movements
- **Built-in validation** and static analysis
- **Cross-platform execution** via CLI, TUI, and web interfaces
## Syntax Examples
### Single-Tape Turing Machine
```tur
name: Binary Counter
tape: 1, 0, 1, 1
rules:
start:
0 -> 0, R, start
1 -> 1, R, start
_ -> _, L, inc # Reached end, go back to start incrementing
inc:
0 -> 1, S, done # 0 becomes 1, no carry needed
1 -> 0, L, inc # 1 becomes 0, carry to next position
_ -> 1, S, done # Reached beginning with carry, add new 1
done:
```
### Multi-Tape Turing Machine
```tur
name: Copy Tape
heads: [0, 0]
tapes:
[a, b, c]
[_, _, _]
rules:
copy:
[a, _] -> [a, a], [R, R], copy
[b, _] -> [b, b], [R, R], copy
[c, _] -> [c, c], [R, R], copy
[_, _] -> [_, _], [S, S], done
done:
```
## Language Specification
### Program Structure
Every `.tur` program consists of:
```tur
name: Program Name
# Single-tape configuration
tape: symbol1, symbol2, symbol3
head: 0 # optional, defaults to 0
# OR multi-tape configuration
tapes:
[tape1_symbol1, tape1_symbol2]
[tape2_symbol1, tape2_symbol2]
heads: [0, 0] # optional, defaults to [0, 0, ...]
# Optional blank symbol (defaults to _)
blank: -
# Transition rules
rules:
state_name:
input -> output, direction, next_state
# ... more transitions
another_state:
# ... transitions
# Note: The first state defined in rules is the start state
```
### Transition Rules
**Single-tape format:**
```tur
current_symbol -> write_symbol, direction, next_state
```
**Multi-tape format:**
```tur
[sym1, sym2, sym3] -> [write1, write2, write3], [dir1, dir2, dir3], next_state
```
> **Note:** The first state defined in the `rules:` section is automatically considered the start state. In the examples above, `start` is the initial state because it appears first.
### Directions
- `L` or `<` - Move left
- `R` or `>` - Move right
- `S` or `-` - Stay (no movement)
### Comments
```tur
# This is a comment
state:
a -> b, R, next # Inline comment
```
### Special Symbols
- `_` - Default blank symbol (can be customized with `blank:`)
- Any other character or string can be used as tape symbols
## Platforms
### Command Line Interface (CLI)
```bash
# Run a program
cargo run --package tur-cli -- examples/binary-addition.tur
# Or with Nix
nix run .#cli -- examples/binary-addition.tur
```
### Terminal User Interface (TUI)
```bash
# Interactive TUI with program selection
cargo run --package tur-tui
# Or with Nix
nix run .#tui
```
**TUI Features:**
- Interactive program selection
- Step-by-step execution
- Real-time tape visualization
- Multi-tape support with synchronized display
- Keyboard controls (Space to step, R to reset, P for auto-play)
### Web Interface
```bash
# Development server with hot reload
cd platforms/web && trunk serve
# Or using just
just dev-web
```
**Web Features:**
- Visual state transition graphs
- Interactive tape display with animations
- Built-in program editor with syntax highlighting
- Real-time validation and error reporting
- Program sharing via URLs
- Multi-tape visualization
## Development Setup
### Prerequisites
- Rust toolchain (1.70+)
- For web development: `trunk` (`cargo install trunk`)
### Quick Start with Nix
```bash
# Enter development environment
nix develop
# Build all platforms
nix build .#cli .#tui .#web
# Development workflow
just dev # Watch and check code
just test # Run all tests
just build-all # Build all platforms
just serve-web # Serve web app with hot reload
```
### Manual Setup
```bash
# Clone and build
git clone <repository-url>
cd turing-machine
cargo build --release
# Run tests
cargo test
# Platform-specific builds
cargo build --package tur-cli
cargo build --package tur-tui
cd platforms/web && trunk build --release
```
## Architecture
This project is structured as a Rust workspace:
- **`tur` (root)** - Core language parser, interpreter, and execution engine
- **`platforms/cli/`** - Command-line interface
- **`platforms/tui/`** - Terminal user interface with ratatui
- **`platforms/web/`** - Web application with Yew framework
- **`platforms/action/`** - Shared action handling
- **`examples/`** - Collection of `.tur` program examples
### Core Features
- **Parser** - Pest-based grammar for `.tur` files
- **Static Analysis** - Validation, reachability analysis, undefined state detection
- **Multi-tape Engine** - Full support for synchronized multi-tape operations
- **Cross-platform** - Consistent behavior across CLI, TUI, and web platforms
## Example Programs
The `examples/` directory contains various Turing machine programs:
- **`binary-addition.tur`** - Adds two binary numbers
- **`binary-counter.tur`** - Increments a binary counter
- **`palindrome.tur`** - Checks if input is a palindrome
- **`subtraction.tur`** - Subtracts binary numbers
- **`multi-tape-addition.tur`** - Multi-tape binary addition
- **`multi-tape-example.tur`** - Basic multi-tape operations
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass: `cargo test`
5. Submit a pull request
## Installation
### From crates.io
```bash
# Install the CLI tool
cargo install tur-cli
# Install the TUI tool
cargo install tur-tui
# Use as a library in your Rust project
cargo add tur
```
### From source
```bash
git clone https://github.com/rezigned/turing-machine
cd turing-machine
cargo build --release
```
## Documentation
- **API Documentation**: [docs.rs/tur](https://docs.rs/tur)
- **Repository**: [github.com/rezigned/turing-machine](https://github.com/rezigned/turing-machine)
- **Examples**: See the `examples/` directory for sample `.tur` programs
## License
Licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT License ([LICENSE-MIT](LICENSE-MIT))
at your option.