Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/aalhour/pycoolc

:snake: :cool: Compiler for the COOL programming language in Python 3
https://github.com/aalhour/pycoolc

compiler cool python3

Last synced: 2 months ago
JSON representation

:snake: :cool: Compiler for the COOL programming language in Python 3

Host: GitHub
URL: https://github.com/aalhour/pycoolc
Owner: aalhour
License: mit
Created: 2016-05-06T18:53:30.000Z (over 8 years ago)
Default Branch: master
Last Pushed: 2019-04-13T19:43:59.000Z (almost 6 years ago)
Last Synced: 2024-04-20T07:31:38.411Z (9 months ago)
Topics: compiler, cool, python3
Language: Python
Homepage:
Size: 1.6 MB
Stars: 40
Watchers: 3
Forks: 10
Open Issues: 7
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        ![PyCOOLC](misc/pycoolc_logo.png)

An [AOT](https://en.wikipedia.org/wiki/Ahead-of-time_compilation) compiler for **[COOL](https://en.wikipedia.org/wiki/Cool_(programming_language))** (**C**lassroom **O**bject **O**riented **L**anguage), targeting the MIPS 32-bit Architecture and written entirely in Python 3.

**COOL** is a small statically-typed object-oriented language that is type-safe and garbage collected. It has mainly 3 primitive data types: Integers, Strings and Booleans (`true`, `false`). It supports conditional and iterative control flow in addition to pattern matching. Everything in COOL is an expression! Many example COOL programs can be found under the [/examples](/examples/README.md) directory.

A BNF-based specification of **COOL**'s Context-Free Grammar can be found at [/docs/Grammar.md](/docs/Grammar.md).

------------------------------

## CONTENTS

  * [Overview](#overview).

    + [Architecture](#architecture).

    + [Example Scenario](#example-scenario).

  * [Development Status](#dev-status).

  * [Installation](#installation).

    + [Requirements](#requirements).

    + [Installing from Source](#installing-from-source).

    + [Installing from PyPI](#installing-from-pypi).

  * [Usage](#usage).

    + [Standalone](#standalone).

    + [Python Module](#python-module).

  * [Language Features](#language-features).

  * [Literature](#literature).

  * [License](#license)

------------------------------

## OVERVIEW

### Architecture:

PyCOOLC follows classical compiler architecture, it consists mainly of the infamous two logical components: Frontend and Backend.

The flow of compilation goes from Frontend to Backend, passing through the stages in every component.

Compiler Frontend consists of the following three stages:

 

  1. Lexical Analysis (see: [`lexer.py`](/pycoolc/lexer.py)): regex-based tokenizer.

  2. Syntax Analysis (see: [`parser.py`](/pycoolc/parser.py)): an LALR(1) parser.

  3. Semantic Analysis (see: [`semanalyser.py`](/pycoolc/semanalyser.py)).

Compiler Backend consists of the following two stages:

  * Code Optimization.

  * Code Generation:

    + Targets the MIPS 32-bit architecture.

    + Models an SRSM (Single-Register Stack Machine).

### Example Scenario:

A typical compilation scenario would start by the user calling the compiler driver (see: [`pycoolc.py`](/pycoolc/pycoolc.py)) passing to it one or more COOL program files. The compiler starts off by parsing the source code of all program files, lexical analysis, as a stage, is driven by the parser. The parser returns an Abstract Syntax Tree (see: [`ast.py`](/pycoolc/ast.py)) representation of the program(s) if parsing finished successfully, otherwise the compilation process is terminated and errors reported back the user. The compiler driver then initiates the Semantic Analysis stage, out of which the AST representation will be further modified. If any errors where found during this stage, the compilation process will be terminated with all errors reported back. The driver goes on with compilation process, entering the Code Optimization stage where the AST is optimized and dead code is eliminated, after which the Code Generation stage follows, emitting executable MIPS 32-bit assembly code.

## DEV. STATUS

Each Compiler stage and Runtime feature is designed as a separate component that can be used standalone or as a Python module, the following is the development status of each one:

| Compiler Stage     | Python Module                         | Issue(s)                                                | Status                      |

|:-------------------|:--------------------------------------|:--------------------------------------------------------|:----------------------------|

| Lexical Analysis   | [`lexer.py`](/pycoolc/lexer.py)       | [#2](https://git.io/vr1gx)                              | :white_check_mark: **done** |

| Parsing            | [`parser.py`](/pycoolc/parser.py)     | [#3](https://git.io/vr12k)                              | :white_check_mark: **done** |

| Semantic Analysis  | [`semanalyser.py`](/pycoolc/semanalyser.py) | [#4](https://git.io/vr12O)                        | *in progress*               |

| Optimization       | -                                     | [#5](https://git.io/vr1Vd), [#11](https://git.io/vKHuH) | -                           | 

| Code Generation    | -                                     | [#6](https://git.io/vr1VA)                              | -                           |

| Garbage Collection | -                                     | [#8](https://git.io/vof6z)                              | -                           |

## INSTALLATION

### Requirements

 * Python >= 3.5

 * SPIM - MIPS 32-bit Assembly Simulator: [@Homepage](http://spimsimulator.sourceforge.net), [@SourceForge](https://sourceforge.net/projects/spimsimulator/files/).

 * All Python packages listed in: [`requirements.txt`](requirements.txt).

### Installing from Source

```

python3 setup.py install

```

### Installing from PyPI

_Coming soon..._

## USAGE

### Standalone

Help and usage information:

```bash

pycoolc --help

```

Compile a cool program:

```bash

pycoolc hello_world.cl

```

Specify a custom name for the compiled output program:

```bash

pycoolc hello_world.cl --outfile helloWorldAsm.s

```

Run the compiled program (MIPS machine code) with the SPIM simulator:

```bash

spim helloWorldAsm.s

```

### Python Module

```python

from pycoolc.lexer import make_lexer

from pycoolc.parser import make_parser

lexer = make_lexer()

lexer.input(a_cool_program_source_code_str)

for token in lexer:

    print(token)

    

parser = make_parser()

parsing_result = parser.parse(a_cool_program_source_code_str)

print(parsing_result)

```

## LANGUAGE FEATURES

  * Primitive Data Types:

    + Integers.

    + Strings.

    + Booleans (`true`, `false`).

  * Object Oriented:

    + Class Declaration.

    + Object Instantiation.

    + Inheritance.

    + Class Attributes.

    + Class Methods.

  * Strong Static Typing.

  * Pattern Matching.

  * Control Flow:

    + Switch Case.

    + If/Then/Else.

    + While Loops.

  * Automatic Memory Management:

    + Garbage Collection.

## LITERATURE

  * Engineering a Compiler, Cooper and Torczon - [Amazon](https://www.amazon.com/dp/012088478X)

  * Modern Compiler Implementation in ML, Appel - [www](https://www.cs.princeton.edu/~appel/modern/ml/), [Amazon](https://www.amazon.com/dp/0521607647)

  * Stanford's Compiler Theory Course - [www12](https://web.stanford.edu/class/archive/cs/cs143/cs143.1128/), [www16](http://web.stanford.edu/class/cs143/), [YouTube](https://www.youtube.com/playlist?list=PLDcmCgguL9rxPoVn2ykUFc8TOpLyDU5gx)

## LICENSE

This project is licensed under the [MIT License](LICENSE).

All copyrights of the files and documents under the [/docs](/docs) directory belong to their original owners.