timewarp-ide 1.0.0__tar.gz

timewarp_ide-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,218 @@
+# Contributing to TimeWarp IDE
+
+Welcome to the TimeWarp IDE project! We're excited to have you contribute to this educational programming environment.
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.9 or higher
+- Git
+- A GitHub account
+
+### Setting Up Development Environment
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/James-HoneyBadger/Time_Warp.git
+   cd Time_Warp
+   ```
+
+2. **Run the automated setup:**
+   ```bash
+   ./setup_dev.sh
+   ```
+
+3. **Manual setup (if needed):**
+   ```bash
+   # Create and activate virtual environment
+   python3 -m venv .Time_Warp
+   source .Time_Warp/bin/activate
+   
+   # Install dependencies
+   pip install -r requirements.txt
+   
+   # Install pre-commit hooks
+   pre-commit install
+   ```
+
+## 🏗️ Project Structure
+
+```
+Time_Warp/
+├── TimeWarp.py                 # Main application entry point
+├── core/                       # Core interpreter and language engines
+│   ├── interpreter.py          # Central execution engine
+│   ├── languages/             # Language-specific executors
+│   ├── editor/                # Enhanced code editor components
+│   └── hardware/              # Hardware integration modules
+├── tools/                     # Utility tools and theme management
+├── plugins/                   # Plugin system and extensions
+├── gui/                       # GUI components and dialogs
+├── games/                     # Game engine and examples
+├── examples/                  # Sample programs and demos
+├── tests/                     # Test suites
+└── .github/                   # GitHub workflows and templates
+```
+
+## 🧪 Development Workflow
+
+### Running TimeWarp IDE
+```bash
+# Activate virtual environment
+source .Time_Warp/bin/activate
+
+# Run the IDE
+python TimeWarp.py
+```
+
+### Testing
+```bash
+# Run all tests
+python run_tests.py
+
+# Run specific test categories
+python -m pytest tests/ -v
+```
+
+### Code Quality
+```bash
+# Format code
+black .
+
+# Lint code
+flake8 .
+
+# Type checking
+mypy TimeWarp.py core/
+
+# Run pre-commit hooks manually
+pre-commit run --all-files
+```
+
+## 📝 Coding Standards
+
+### Code Style
+- Use **Black** for code formatting (line length: 88)
+- Follow **PEP 8** naming conventions
+- Use **type hints** where appropriate
+- Write **docstrings** for all public functions and classes
+
+### File Organization
+- **Test files**: `test_*.py` for unit tests, `*_test.py` for integration tests
+- **Language demos**: Use appropriate extensions (`.pilot`, `.bas`, `.logo`, `.timewarp`)
+- **Documentation**: Use Markdown for all documentation files
+
+### Commit Messages
+Follow conventional commit format:
+```
+type(scope): brief description
+
+Detailed explanation of the changes made.
+
+- List specific changes
+- Include any breaking changes
+- Reference issues if applicable
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+## 🎯 Contributing Guidelines
+
+### 1. Fork and Branch
+- Fork the repository to your GitHub account
+- Create a feature branch: `git checkout -b feature/your-feature-name`
+
+### 2. Make Changes
+- Follow the coding standards above
+- Add tests for new functionality
+- Update documentation if needed
+- Ensure all tests pass
+
+### 3. Submit Pull Request
+- Push to your fork: `git push origin feature/your-feature-name`
+- Create a pull request with a clear description
+- Link any related issues
+- Wait for review and feedback
+
+### 4. Code Review Process
+- All PRs require at least one review
+- Address feedback promptly
+- Keep PRs focused and reasonably sized
+- Update your branch if requested
+
+## 🐛 Bug Reports
+
+When reporting bugs, please include:
+- **OS and Python version**
+- **Steps to reproduce**
+- **Expected vs actual behavior**
+- **Error messages or logs**
+- **Screenshots if relevant**
+
+Use the bug report template in `.github/ISSUE_TEMPLATE/`
+
+## 💡 Feature Requests
+
+For new features:
+- Check existing issues first
+- Provide clear use cases
+- Consider implementation complexity
+- Be open to discussion and alternatives
+
+## 🏷️ Areas for Contribution
+
+### High Priority
+- **Language Support**: Add new programming languages
+- **Educational Tools**: Learning assistants and tutorials  
+- **Testing**: Improve test coverage and edge cases
+- **Documentation**: User guides and API documentation
+
+### Medium Priority
+- **UI/UX**: Interface improvements and accessibility
+- **Performance**: Optimization and profiling
+- **Plugins**: New plugin development
+- **Hardware Integration**: IoT and sensor support
+
+### Good First Issues
+Look for issues labeled `good-first-issue` or `help-wanted`
+
+## 🔧 Development Tips
+
+### Adding New Languages
+1. Create executor class in `core/languages/new_language.py`
+2. Implement required methods following existing patterns
+3. Register in `core/interpreter.py`
+4. Add syntax highlighting support
+5. Create test programs and unit tests
+
+### Plugin Development
+- See `plugins/sample_plugin/` for template
+- Follow plugin API conventions
+- Include proper initialization and cleanup
+- Add configuration options if needed
+
+### Testing Best Practices
+- Write tests for new features
+- Test edge cases and error conditions
+- Use meaningful test names
+- Keep tests isolated and fast
+
+## 📞 Getting Help
+
+- **GitHub Discussions**: Ask questions and share ideas
+- **Issues**: Report bugs or request features
+- **Wiki**: Documentation and guides
+- **Code Comments**: Inline documentation for complex logic
+
+## 📄 License
+
+By contributing to TimeWarp IDE, you agree that your contributions will be licensed under the same license as the project.
+
+## 🙏 Recognition
+
+Contributors are recognized in:
+- GitHub contributors list
+- Release notes for significant contributions
+- Special mentions in documentation
+
+Thank you for contributing to TimeWarp IDE! 🚀✨

timewarp_ide-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TimeWarp IDE Development Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

timewarp_ide-1.0.0/MANIFEST.in

@@ -0,0 +1,87 @@
+include README.md
+include LICENSE
+include requirements.txt
+include CONTRIBUTING.md
+include .pre-commit-config.yaml
+include pytest.ini
+
+# Include example programs
+recursive-include examples *.pilot
+recursive-include examples *.bas
+recursive-include examples *.logo
+recursive-include examples *.py
+recursive-include examples *.js
+recursive-include examples *.pl
+recursive-include examples *.timewarp
+
+# Include sample programs
+recursive-include samples *.pilot
+recursive-include samples *.bas
+recursive-include samples *.logo
+recursive-include samples *.py
+recursive-include samples *.js
+recursive-include samples *.pl
+recursive-include samples *.timewarp
+
+# Include documentation
+recursive-include docs *.md
+recursive-include docs *.txt
+recursive-include docs *.rst
+
+# Include test files (for development)
+recursive-include tests *.py
+recursive-include test_* *.py
+recursive-include test_* *.pilot
+recursive-include test_* *.bas
+recursive-include test_* *.logo
+recursive-include test_* *.py
+
+# Include game files
+recursive-include games *.py
+recursive-include games *.json
+
+# Include plugin files
+recursive-include plugins *.py
+recursive-include plugins *.json
+
+# Include feature files
+recursive-include features *.py
+
+# Include tool files
+recursive-include tools *.py
+
+# Include data files
+recursive-include data *.desktop
+recursive-include data *.png
+recursive-include data *.svg
+recursive-include data *.ico
+
+# Exclude development files
+exclude .gitignore
+exclude .gitattributes
+exclude .pre-commit-config.yaml
+exclude pytest.ini
+exclude run_tests.py
+exclude run_tests_production.py
+exclude integration_tests.py
+exclude benchmark_*.py
+exclude debug_*.py
+exclude test_*.py
+exclude *_test.py
+exclude performance_bench.py
+exclude install_dependencies.py
+exclude setup_dev.sh
+
+# Exclude cache and temporary files
+global-exclude *.pyc
+global-exclude __pycache__
+global-exclude .pytest_cache
+global-exclude *.log
+global-exclude debug_output.txt
+global-exclude benchmark_results.json
+global-exclude integration_test_report.json
+
+# Exclude compiled outputs
+global-exclude *_compiled
+global-exclude *.ppm
+global-exclude *.db

timewarp_ide-1.0.0/PKG-INFO

@@ -0,0 +1,357 @@
+Metadata-Version: 2.4
+Name: timewarp-ide
+Version: 1.0.0
+Summary: Educational Programming IDE with Multi-Language Support
+Home-page: https://github.com/James-HoneyBadger/Time_Warp
+Author: James-HoneyBadger
+Author-email: TimeWarp Development Team <info@timewarp-ide.org>
+Maintainer-email: James-HoneyBadger <timewarp-ide@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/James-HoneyBadger/Time_Warp
+Project-URL: Documentation, https://timewarp-ide.readthedocs.io/
+Project-URL: Repository, https://github.com/James-HoneyBadger/Time_Warp
+Project-URL: Issues, https://github.com/James-HoneyBadger/Time_Warp/issues
+Project-URL: Changelog, https://github.com/James-HoneyBadger/Time_Warp/blob/main/CHANGELOG.md
+Keywords: education,programming,ide,basic,logo,pilot,compiler,turtle-graphics,educational
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Interpreters
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=8.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: sphinx>=4.0.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=4.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
+Provides-Extra: graphics
+Requires-Dist: Pillow>=8.0.0; extra == "graphics"
+Provides-Extra: hardware
+Requires-Dist: pyserial>=3.0; extra == "hardware"
+Requires-Dist: smbus2>=0.4.0; extra == "hardware"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# ⏰ TimeWarp Compiler
+
+**Compile Educational Programming Languages to Native Executables**
+
+TimeWarp Compiler is a command-line tool that compiles educational programming languages (PILOT, BASIC, Logo) to native Linux executables. Transform your educational code into standalone programs that run without interpreters.
+
+[![PyPI version](https://badge.fury.io/py/timewarp-ide.svg)](https://pypi.org/project/timewarp-ide/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ Features
+
+### 🎯 Multi-Language Compilation
+Compile 3 educational programming languages to native executables:
+
+- **PILOT** - Educational language with turtle graphics (1960s)
+- **BASIC** - Classic line-numbered programming (1960s)
+- **Logo** - Educational turtle graphics language (1960s)
+
+### 🚀 Native Performance
+- **GCC Compilation** - Generate optimized C code and compile to native executables
+- **Cross-Platform** - Linux executables (easily extensible to other platforms)
+- **No Runtime Dependencies** - Standalone binaries that run anywhere
+
+### 📚 Rich Sample Programs
+Comprehensive examples demonstrating language features:
+- **BASIC**: Hello world, arrays, functions, loops
+- **Logo**: Shapes, complex drawings, fractals
+- **PILOT**: Math quizzes, interactive adventures
+
+## 🚀 Quick Start
+
+### Installation
+
+#### Option 1: PyPI (Recommended)
+```bash
+pip install timewarp-ide
+```
+
+#### Option 2: From Source
+```bash
+git clone https://github.com/James-HoneyBadger/Time_Warp.git
+cd Time_Warp
+pip install -e .
+```
+
+### System Requirements
+- **Python**: 3.9 or higher
+- **GCC**: GNU C Compiler (build dependency)
+- **OS**: Linux (executables), macOS/Windows (compilation)
+
+## 📖 Usage
+
+### Basic Compilation
+```bash
+# Compile a BASIC program
+timewarp-compiler hello.bas -o hello
+
+# Compile a Logo program
+timewarp-compiler drawing.logo -o logo_app
+
+# Compile a PILOT program
+timewarp-compiler quiz.pilot -o math_quiz
+```
+
+### Command Line Options
+```bash
+timewarp-compiler [OPTIONS] INPUT_FILE
+
+Options:
+  -o, --output OUTPUT    Output executable name (default: same as input)
+  --list-languages       List supported languages and exit
+  --version              Show version information
+  -h, --help             Show help message
+```
+
+### Supported File Extensions
+- `.bas` - BASIC programs
+- `.logo` - Logo programs
+- `.pilot` - PILOT programs
+
+## 📚 Sample Programs
+
+### BASIC Examples
+
+#### Hello World
+```basic
+10 PRINT "HELLO WORLD BASIC PROGRAM"
+20 PRINT "This demonstrates basic BASIC features"
+30 LET ANSWER = 21 * 2
+40 PRINT "The answer is: "; ANSWER
+50 INPUT "Enter your name"; NAME$
+60 PRINT "Hello, "; NAME$
+70 PRINT "Counting from 1 to 5:"
+80 FOR I = 1 TO 5
+90 PRINT I
+100 NEXT I
+110 PRINT "Done!"
+120 END
+```
+
+#### Array Operations
+```basic
+10 DIM SCORES(10)
+20 FOR I = 1 TO 10
+30 SCORES(I) = I * 10
+40 NEXT I
+50 PRINT "Scores:"
+60 FOR I = 1 TO 10
+70 PRINT "Score"; I; ": "; SCORES(I)
+80 NEXT I
+90 END
+```
+
+### Logo Examples
+
+#### Simple Shapes
+```logo
+TO SQUARE :SIZE
+  REPEAT 4 [FORWARD :SIZE RIGHT 90]
+END
+
+TO TRIANGLE :SIZE
+  REPEAT 3 [FORWARD :SIZE RIGHT 120]
+END
+
+TO CIRCLE :RADIUS
+  REPEAT 36 [FORWARD (2 * 3.14159 * :RADIUS / 36) RIGHT 10]
+END
+
+SQUARE 100
+TRIANGLE 80
+CIRCLE 50
+```
+
+#### Fractal Tree
+```logo
+TO TREE :SIZE
+  IF :SIZE < 5 [STOP]
+  FORWARD :SIZE
+  RIGHT 25
+  TREE :SIZE * 0.7
+  LEFT 50
+  TREE :SIZE * 0.7
+  RIGHT 25
+  BACK :SIZE
+END
+
+TREE 100
+```
+
+### PILOT Examples
+
+#### Math Quiz
+```pilot
+R: PILOT Math Quiz
+R: Test your arithmetic skills
+
+*START
+T: Welcome to the Math Quiz!
+T: Answer the following questions:
+
+T: What is 5 + 3?
+A: Your answer
+C: #CORRECT = 8
+J: (#ANS = #CORRECT) *CORRECT
+T: Sorry, 5 + 3 = 8
+J: *NEXT
+
+*CORRECT
+T: Correct! 5 + 3 = 8
+
+*NEXT
+T: What is 10 - 4?
+A: Your answer
+C: #CORRECT = 6
+J: (#ANS = #CORRECT) *CORRECT2
+T: Sorry, 10 - 4 = 6
+J: *END
+
+*CORRECT2
+T: Excellent! 10 - 4 = 6
+
+*END
+T: Quiz complete!
+E:
+```
+
+#### Interactive Story
+```pilot
+R: Choose Your Own Adventure
+
+*BEGIN
+T: You find yourself in a dark forest.
+T: Do you go LEFT or RIGHT?
+
+A: Your choice (LEFT/RIGHT)
+J: (*ANS = LEFT) *LEFT_PATH
+J: (*ANS = RIGHT) *RIGHT_PATH
+T: Please choose LEFT or RIGHT
+J: *BEGIN
+
+*LEFT_PATH
+T: You find a treasure chest!
+T: Congratulations!
+E:
+
+*RIGHT_PATH
+T: You encounter a dragon!
+T: Game Over!
+E:
+```
+
+## 🏗️ Architecture
+
+### Compilation Pipeline
+1. **Parse Source** - Language-specific parsing of source code
+2. **Generate C Code** - Convert to optimized C with runtime libraries
+3. **Compile Executable** - GCC compilation to native binary
+4. **Standalone Binary** - No external dependencies required
+
+### Language Compilers
+- **BaseCompiler** - Abstract framework for language implementations
+- **BasicCompiler** - Line-numbered BASIC with arrays and functions
+- **LogoCompiler** - Turtle graphics with procedures and recursion
+- **PilotCompiler** - Educational language with branching and variables
+
+### Runtime Libraries
+Each language includes optimized C runtime libraries for:
+- String manipulation and I/O
+- Mathematical operations
+- Turtle graphics rendering (PPM format)
+- Variable management and scope
+
+## 📚 Documentation
+
+### Language References
+- [BASIC Language Reference](docs/languages/basic.md)
+- [Logo Language Reference](docs/languages/logo.md)
+- [PILOT Language Reference](docs/languages/pilot.md)
+
+### Compiler Documentation
+- [Compiler Usage Guide](docs/compiler.md)
+
+## 🔧 Development
+
+### Building from Source
+```bash
+# Clone repository
+git clone https://github.com/James-HoneyBadger/Time_Warp.git
+cd Time_Warp
+
+# Install in development mode
+pip install -e .
+
+# Run tests
+python -m pytest
+
+# Build package
+python -m build
+```
+
+### Testing Compilers
+```bash
+# Test all compilers
+python -m pytest tests/
+
+# Test specific language
+python -c "from timewarp_ide.compiler import compile_file; compile_file('samples/basic/hello.bas', 'test_output')"
+```
+
+### Adding New Languages
+1. Create compiler class inheriting from `BaseCompiler`
+2. Implement `parse_source()` and `generate_c_code()` methods
+3. Add file extension mapping in `compiler.py`
+4. Include runtime library functions
+5. Add comprehensive tests
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md).
+
+### Areas for Contribution
+- **New Languages** - Add support for additional educational languages
+- **Performance** - Optimize compilation and runtime performance
+- **Platforms** - Extend support to Windows/macOS executables
+- **Features** - Enhanced language features and capabilities
+- **Documentation** - Improve guides and examples
+
+## 📄 License
+
+TimeWarp Compiler is open source software licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## 🙏 Acknowledgments
+
+- **PILOT**: Inspired by the original educational programming language
+- **BASIC**: Based on classic BASIC implementations
+- **Logo**: Built on the turtle graphics paradigm
+- **GCC**: For the excellent C compilation toolchain
+- **Python Community**: For the robust packaging ecosystem
+
+---
+
+**⏰ TimeWarp Compiler** - Transform educational code into native executables.