Carlos Compiler

This project implements a compiler for the Carlos language in Python. The compiler is structured in several stages, each corresponding to a classical compilation phase: lexing, parsing, AST generation, and visitors (for example, for code generation or display).

Project Structure

The project is organized into several folders, each corresponding to a stage or component of the compiler:

• Lexer/ : Contains code for lexical analysis.
• Parser/ : Contains code for syntactic analysis and AST generation.
• Visitors/ : Contains visitors to traverse the AST, such as a pretty-printer or JavaScript code generator.
• examples/ : Contains example source code in Carlos.
• Lexer/examples_lexed/ : Contains results of lexical analysis of examples.
• Parser/examples_parsed/ : Contains ASTs generated from examples.
• Visitors/examples_js/ : Contains generated JavaScript code from examples.
• Visitors/examples_prettyprinted/ : Contains pretty-printed Carlos source code from examples.

---

Installation and Execution

To use the compiler, you must have Python 3 installed. No libraries are required to run the various files.

You can clone the project from GitHub:

git clone https://github.com/JohanVerne/Carlos_Compiler.git

or download the zip file.

In order to fully compile a .carlos file through to execution as a JavaScript file, you must have Node.js installed. You can get Node.js from https://nodejs.org or from your favorite package manager. If you do not wish to use Node.js or have a different JavaScript interpreter, you will not be able to use the compiler.py file to execute JavaScript code generated from the .carlos file. However, you can use the Visitors/JSCodeGenerator.py file to obtain the JavaScript code and execute it as desired.

Compilation Steps

1. Lexical Analysis (Lexer)

Lexical analysis transforms raw source code into a list of lexemes (tokens). These lexemes represent the smallest syntactic units of the language (keywords, identifiers, operators, etc.).

• Main file : Lexer/lexer.py
• Usage example :

  python3 Lexer/lexer.py examples/hello.carlos

  This displays the lexemes in the terminal. To save the lexemes to a file, add the --save argument :

  python3 Lexer/lexer.py examples/hello.carlos --save

  The lexems will be saved in the Lexer/examples_lexed folder.

2. Syntactic Analysis (Parser)

Syntactic analysis takes the lexemes produced by the lexer and builds an abstract syntax tree (AST). This AST represents the hierarchical structure of the program.

• Main file : Parser/parser.py
• Usage example :

  python3 Parser/parser.py examples/hello.carlos

  This displays the AST in the terminal. To save the AST to a file, add the --save argument:

  python3 Parser/parser.py examples/hello.carlos --save

  The AST will be saved in the Parser/examples_parsed folder.

---

3. Visitors

Visitors traverse the AST to perform various tasks, such as:

• Pretty-printer : Regenerates Carlos source code from the AST.
  • File : Visitors/PrettyPrinter.py
• JavaScript code generator : Converts Carlos code to JavaScript code.
  • Fichier : Visitors/JSCodeGenerator.py

Usage example for the pretty-printer:

python3 Visitors/PrettyPrinter.py examples/hello.carlos --save

---

4. JavaScript Code Generation

The final phase consists of using the JavaScript code generator to obtain the final JavaScript code. This can then be executed using Node.js. Usage example:

python3 Visitors/JSCodeGenerator.py examples/hello.carlos --save

The JavaScript code will be saved in the Visitors/examples_js. folder. It can then be executed with Node.js.

Usage example:

node Visitors/examples_js/hello.js

---

5. Compilation and Execution

To compile a Carlos file and execute it, you can use the compiler.py file :

python3 compiler.py examples/hello.carlos

The JavaScript code will then be executed with Node.js.

To save the JavaScript code, add the --save argument :

python3 compiler.py examples/hello.carlos --save

The JavaScript code will be saved in the Visitors/examples_jsfolder.

Examples

Example Carlos source code is available in the examples. These examples come from examples present in the Carlos project described in sources. An additional example named complex.carlos was generated by ChatGPT to implement as many features as possible supported by Carlos code.

To test the different compilation stages on different examples, the various files named lex_examples.py, parse_examples.py, create_JS_files_from_examples.py and PrettyPrint_examples.py are available in their respective folders. They perform their respective tasks on all files present in the examples folder and save results in their respective example folders.

To test these examples, you can use the following commands:

python3 Lexer/lex_examples.py
python3 Parser/parse_examples.py
python3 Visitors/create_JS_files_from_examples.py
python3 Visitors/PrettyPrint_examples.py

---

Project Objective

The main objective is to convert Carlos code to JavaScript code to enable its execution.

---

Sources

The various sources used to understand the Carlos language as well as links to other projects using the Carlos language are available here:

• https://cs.lmu.edu/~ray/notes/carlos/
• https://github.com/rtoal/carlos/