LISP Interpreter

This LISP interpreter is an improved version of my old interpreter, which can be found here.

Due to poorly implemented algorithms, I have decided to rebuild the interpreter in a better way, this time utilizing the mechanics and speed of the programming language C++.

Table of contents:

1. Description
2. System requirements
3. Usage
4. First steps
5. Coding
6. How to contribute
7. License

---

Description:

This repository resembles an interpreter for a custom dialect of the programming language Lisp.

An interpreter is a program which is capable of evaluating and executing sourcecode. Unlike a compiler, the interpreter does not create any executable file, so the source code must be interpreted every time one wants to execute it.

Unlike you might thing, Lisp is no programming language, but rather a collection of multiple programming languages, which all have similar paradigms which makes them all feel more alike. The Lisp dialect, which this interpreter can evaluate is inspired by the much more common STELLA dialect, but still different in many ways (and of course with a much smaller functional scope). For further information on my Lisp dialect, visit the Lisp documentation of this repository.

---

System requirements:

In order for the interpreter to run on your system, you need to have at least Windows 10 installed.

Due to changes with the Windows Console and Terminal Ecosystem, I do not recommend to run the interpreter with the newly introduced terminal within Windows 11. Instead, I would recommend to use the old Windows 10 terminal when executing the interpreter under Windows 11. The interpreter itself will still work correctly with the new terminal, however there are some irritating occurrences with the displayment within the new terminal.

---

Usage:

Download the executable:

In order to use the interpreter, you do not need to install any program.

You can download the newest release of the interpreter here. The downloaded file resembles the developer command prompt, which you can execute. After that, skip the next paragraph and continue with your first steps.

Download and compile the sourcecode:

If you prefer to download the sourcecode from the code-page, feel free to do so. This interpreter is written in the programming language C++ and needs to be compiled with a respective compiler. The source code of this repository has only been compiled using Microsoft's MSVC compiler and may not be compilable with other C/C++-Compilers.

After successfully compiling the sourcecode you can continue with your first steps.

---

First steps:

After executing the interpreter, you are welcomed with a command promt. The visual depition of the command prompt may change in different versions, but the principle of executing sourcecode should stay the same.

Write the sourcecode:

The first thing you need to do is to write the source code which you want to execute with the interpreter. In the following, we will write a simple Hello World-program in Lisp. Copy the following source code into a file, which is located in the same directory as the previously downloaded executable and name said file "sampleCode.lsp".

;File: sampleCode.lsp
(void main () (
    (println "Hello World")
))

Start the developer command prompt:

After successfully saving your sourcecode to the directory, start the command prompt. You should see a terminal that looks something like this:

Execute the sourcecode:

After that, type execute sampleCode.lsp into the command prompt. If you have saved the file with the sourcecode to the same directory as the executable, the sourcecode should be executed by now and the string "Hello World" should be shown in the terminal.

If you have saved the sourcecode to another directory, you need to provide the filepath to the interpreter. In order not to provide the filepath with every execution, you may change the path by using the cd command.

Available commands:

The command promt is capable of executing a small number of comamnds. You can type help in order to get further information on available commands.

---

Coding:

After you finished with your first steps, you may deal with other elements of this LISP dialect.

Elements of the LISP dialect:

This LISP dialect comes with a variety of keywords, control flow statements and data types. It is even possible to implement functions with this programming language.

For further information on arithmetic-, relational- or boolean operations, look up this document.

Exception handling:

Incorrectly implemented LISP source code might cause the interpreter to throw an exception. Exceptions usually display the file, line and token which caused the error. In addition to that, an error message is displayed. The following source code generates an exception:

;File: sampleCode.lsp
(void main (
    (int myVar "Hello World")
    ;Cannot store String in integer-variable
))

The corresponding exception:

As you can see, the filename, line number and token which caused the error are mentioned. The error message Cannot convert string to integer implies that the String "Hello World" cannot be converted and stored in a variable of type integer.

If the provided error message does not help you to solve the error, you may look up the documentation of every possible error message here.

---

How to contribute:

If you want to contribute to the project, feel free to open a pull request.

If you find any bugs or errors while playing with the interpreter, please create an issue.

---

License:

The interpreter is licensed under the MIT License. See the full license here.