Skip to content

Latest commit

 

History

History
170 lines (109 loc) · 3.42 KB

README.md

File metadata and controls

170 lines (109 loc) · 3.42 KB
Raw

Brainfuck Runner

A command-line tool for executing Brainfuck scripts with debugging capabilities and real-time memory visualization.

Features

  • 🚀 Execute Brainfuck scripts from the command line
  • 🔍 Debug mode with memory state visualization
  • 💡 Breakpoint support using '#' in scripts
  • 📊 Real-time execution statistics
  • 📝 Comprehensive logging system
  • ⚡ Infinite loop detection and prevention
  • 🎯 Step-by-step execution in debug mode
  • 📂 Script management in /bf-scripts directory

Installation

  1. Clone the repository:
git clone https://github.com/RedFox-Studios/brainfuck-runner.git
  1. Navigate to the project directory:
cd brainfuck-runner
  1. Install dependencies:
npm install

Usage

Basic Commands

  1. Run a Brainfuck script:
npm start run <filename>
  1. List available scripts:
npm start list
  1. Run with debug mode:
npm start run <filename> -d

Debug Mode Controls

When running in debug mode (-d flag), you can use the following commands:

  • c - Continue execution
  • s - Enable step mode
  • q - Quit execution

Example Scripts

Place your Brainfuck scripts in the /bf-scripts directory. Here's a simple "Hello World" script example:

++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++.

Breakpoints

You can add breakpoints to your scripts using the '#' character:

+++++     # Initialize counter
#         # Breakpoint before loop
[>+.<-]   # Print sequence

Features in Detail

Memory Visualization

In debug mode, the tool provides a visual representation of the memory state:

Memory State:
0 0 [5] 0 0 0 0 0 0 0

Execution Statistics

After running a script, you'll see:

  • Execution time
  • Total iterations
  • Final memory state (in debug mode)

Logging

All executions are logged in the /logs directory:

  • error.log - Error messages
  • combined.log - All execution information

Project Structure

brainfuck-runner/
├── src/
│   ├── index.js        # Main entry point
│   ├── interpreter.js   # Brainfuck interpreter
│   ├── debug.js        # Debug utilities
│   ├── logger.js       # Logging configuration
│   └── commands.js     # CLI commands
├── bf-scripts/         # Brainfuck scripts directory
└── logs/              # Execution logs

Error Handling

The runner includes several safety features:

  • Maximum iteration limit (10 million)
  • Infinite loop detection
  • Memory bounds checking
  • Error logging

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • Original Brainfuck language by Urban Müller
  • Node.js and npm community
  • Contributors and users of this tool

Support

If you encounter any issues or have questions, please:

  1. Check the existing issues
  2. Create a new issue with a detailed description
  3. Include relevant script samples and error messages

Made with ❤️ by Michal Flaška

P.S., (I almost died in the process)