All tests for the Varphi project are located under the testsdirectory. When testing Python code, please use Pytest as the testing framework (for examples of Pytest tests, please check the existing tests). When implementing a new feature for Varphi, please be sure to test it thoroughly before opening a pull request on GitHub. When you're finished testing your own feature, make sure your new code does not break any existing tests by running all existing tests, as shown below.
The easiest way to run all tests is to run
This will rebuild Varphi and run all tests.
For pull requests to be considered, the codebase is checked against a linter. We use Pylint to do this. The easiest way to run linting on the codebase is to run
This will rebuild Varphi and run linting on the varphidirectory.
We also have a GitHub workflow to automatically test and lint the code base in the event that a pull request is made to the main branch. You should double check that your code passes these checks when you open a pull request.
Varphi is a completely open-source language. It is hosted on a public GitHub repository. You can get the source on your local machine by cloning the repository. You can do so by running the following command in a new terminal:
A new directory named varphi should now be created with the source code under it. Change into this directory:
For the rest of this guide, it is assumed that your terminal is changed into the Varphi root directory.
Varphi uses Make for building the project. The easiest way to build everything in the Varphi project is by running
This will generate the lexer and parser, install the Varphi-to-Python Compiler as a package (called varphi) in a Python virtual environment, and generate the Varphi Interpreter (vpi) binary for your operating system under bin/vpi(or bin\vpi.exe if you have a Windows machine).
You can also build individual components of the Varphi project, as shown below.
Thank you for your interest in contributing to Varphi! We believe that open collaboration is key to making Varphi the best it can be. Whether you're fixing a bug, improving documentation, suggesting features, or sharing your insights, every contribution is valued and appreciated.
There are many ways to contribute:
Code Contributions: Help improve Varphi by fixing bugs, optimizing performance, or adding new features.
Documentation: Clear and comprehensive documentation makes Varphi more accessible to everyone.
Bug Reports & Feature Requests: Found an issue or have an idea? Let us know!
Community Engagement: Join discussions, answer questions, and help others get started.
Check out our Contributing Guide for guidelines and best practices.
Explore our open issues to find something to work on.
We are grateful for your time and effort in making Varphi better. Every contribution, big or small, helps shape the future of the project. Thank you for being a part of this journey!
Here is a timeline of events that happen when a user invokes the Varphi Interpreter (vpi) on a Varphi file:
The Varphi Interpreter executable, through Python's argparse, parses the arguments supplied to the executable. It extract's the user's Varphi source code file path, and determines what the compilation target will be (either a command-line program, command-line program with debugging, or debug adapter).
The user's Varphi source code file is opened for reading, and it's contents are passed through a lexer. The lexer tokenizes the code and catches specific syntax errors at this stage (specifically, a syntax error is thrown by the lexer only if a line element does not fit the criteria to be a state name, tally, blank, or head direction).
Once every line has been stepped through by the translator, a string containing the compiled Python code is sent to the interpreter. A call to Python's exec is made on the compiled Python code, which opens a session that the user can pass the input tape to and receive output from.
The Varphi codebase consists of two parts:
The Varphi-to-Python Compiler
The Varphi Interpreter
The Varphi-to-Python Compiler is a (non-published) Python package and is located under the varphi directory in the source code directory.
The three components of the Varphi-to-Python Compiler are:
The lexer and parser
The translators (Compilers)
The Varphi Runtime Library
The lexer and parser are generated from a grammar file (Varphi.g4) and are not included in the source code. When Varphi is built, they are located under varphi/parsing/VarphiLexer.py and varphi/parsing/VarphiParser.py, respectively.
Varphi includes a translator, or compiler, for every possible target (command-line program, debug adapter, etc.). These are located under varphi/compilation/varphi_translator.py.
The Varphi Runtime Library is a set of utilities used by the Python code which Varphi programs are compiled to. This library is located under varphi/runtime.