COOL Compiler

.gitignore

@@ -408,3 +408,8 @@ dmypy.json
 
 # Custom rules (everything added below won't be overriden by 'Generate .gitignore File' if you use 'Update' option)
 
+env/
+.idea/
+
+settings.json
+code.mips

doc/Readme.md

@@ -1,33 +1,41 @@
 # Documentación
 
-## Readme
+## Como usar el compilador
 
-Modifique el contenido de este documento para documentar de forma clara y concisa los siguientes aspectos:
+Para compilar un fichero de COOL se puede usar el comando:
 
-- Cómo ejecutar (y compilar si es necesario) su compilador.
-- Requisitos adicionales, dependencias, configuración, etc.
-- Opciones adicionales que tenga su compilador.
+```
+python3 coolc.py "path/to/file.cl"
+```
 
-## Sobre los Equipos de Desarrollo
+Este compila el fichero `file.cl` y almacena el código generado en un fichero del mismo nombre pero pero con extension `.mips`.
 
-Para desarrollar el compilador del lenguaje COOL se trabajará en equipos de 2 o 3 integrantes. El proyecto de Compilación será recogido y evaluado únicamente a través de Github. Es imprescindible tener una cuenta de Github para cada participante, y que su proyecto esté correctamente hosteado en esta plataforma. 
+Se pueden consultar las demás opciones de la línea de comandos para el compilador ejecutando `python3 coolc.py -h`.
 
-**⚠️ NOTA**: Debe completar el archivo `team.yml` con los datos correctos de cada miembro de su equipo.
+```
+usage: coolc.py [-h] [--out OUT] [--run | --no-run] [--verbose | --no-verbose] file
 
-## Sobre los Materiales a Entregar
+positional arguments:
+  file                  COOL source file.
 
-Para la evaluación del proyecto Ud. debe entregar un informe en formato PDF (`report.pdf`) en esta carpeta, que resuma de manera organizada y comprensible la arquitectura e implementación de su compilador.
-El documento no tiene límite de extensión.
-En él explicará en más detalle su solución a los problemas que, durante la implementación de cada una de las fases del proceso de compilación, hayan requerido de Ud. especial atención.
+optional arguments:
+  -h, --help            show this help message and exit
+  --out OUT             Name for .mips generated file after compilation.
+  --run, --no-run       Execute the file compiled with SPIM. (default: False)
+  --verbose, --no-verbose
+                        Verbose output. (default: False)
+```
 
-## Estructura del reporte
+- `--out`: modifica el fichero de salida para el `.mips` generado, que por defecto es creado con el mismo nombre del fichero de COOL.
+- `--run`: facilita la ejecución del programa escrito en COOL ejecutando automáticamente el fichero `.mips` de salida. Para realizar dicha acción es necesario tener `spim` instalado y en el path.
+- `--verbose`: imprime en consola el AST generado después de concluido el análisis lexico, parsing y análisis semántico, asi como el código intermedio (CIL) generado previamente a la generación de código final. 
 
-Usted es libre de estructurar su reporte escrito como más conveniente le parezca. A continuación le sugerimos algunas secciones que no deberían faltar, aunque puede mezclar, renombrar y organizarlas de la manera que mejor le parezca:
+## Requerimientos
 
-- **Uso del compilador**: detalles sobre las opciones de líneas de comando, si tiene opciones adicionales (e.j., `--ast` genera un AST en JSON, etc.). Básicamente lo mismo que pondrá en este Readme.
-- **Arquitectura del compilador**: una explicación general de la arquitectura, en cuántos módulos se divide el proyecto, cuantas fases tiene, qué tipo de gramática se utiliza, y en general, como se organiza el proyecto. Una buena imagen siempre ayuda.
-- **Problemas técnicos**: detalles sobre cualquier problema teórico o técnico interesante que haya necesitado resolver de forma particular.
+### Ambiente de ejecución
 
-## Sobre la Fecha de Entrega
+El proyecto fue desarrollado y probado bajo un ambiente en `Python 3.9.5`, asi que se espera compatibilidad con esta version y superiores (`3.9+`). No se garantiza la correctitud del compilador o que este sea ejecutable en versiones inferiores.
 
-Se realizarán recogidas parciales del proyecto a lo largo del curso. En el Canal de Telegram se anunciará la fecha y requisitos de cada entrega.
+### Dependencias
+
+La única dependencia del compilador es `ply==3.11`, la cual puede ser instalada ejecutando el comando `python3 -m pip install ply==3.11`.

doc/report.md

@@ -0,0 +1,161 @@
+# Proyecto de compilación
+
+## Integrantes
+
+- Enmanuel Verdesia Suárez C-411
+- Samuel David Suárez Rodríguez C-412
+
+## Instalación / Ejecución
+
+Para compilar un fichero de COOL se puede usar el comando:
+
+```
+python3 coolc.py "path/to/file.cl"
+```
+
+Este compila el fichero `file.cl` y almacena el código generado en un fichero del mismo nombre pero pero con extension `.mips`.
+
+Se pueden consultar las demás opciones de la línea de comandos para el compilador ejecutando `python3 coolc.py -h`.
+
+```
+usage: coolc.py [-h] [--out OUT] [--run | --no-run] [--verbose | --no-verbose] file
+
+positional arguments:
+  file                  COOL source file.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --out OUT             Name for .mips generated file after compilation.
+  --run, --no-run       Execute the file compiled with SPIM. (default: False)
+  --verbose, --no-verbose
+                        Verbose output. (default: False)
+```
+
+- `--out`: modifica el fichero de salida para el `.mips` generado, que por defecto es creado con el mismo nombre del fichero de COOL.
+- `--run`: facilita la ejecución del programa escrito en COOL ejecutando automáticamente el fichero `.mips` de salida. Para realizar dicha acción es necesario tener `spim` instalado y en el path.
+- `--verbose`: imprime en consola el AST generado después de concluido el análisis lexico, parsing y análisis semántico, asi como el código intermedio (CIL) generado previamente a la generación de código final. 
+
+### Requerimientos
+
+El proyecto fue desarrollado y probado bajo un ambiente en `Python 3.9.5`, asi que se espera compatibilidad con esta version y superiores (`3.9+`). No se garantiza la correctitud del compilador o que este sea ejecutable en versiones inferiores.
+
+La única dependencia del compilador es `ply==3.11`, la cual puede ser instalada ejecutando el comando `python3 -m pip install ply==3.11`.
+
+
+## Arquitectura
+
+Para la implementación del compilador de `COOL` se dividió el proceso de desarrollo en las etapas siguientes:
+
+- Análisis Sintáctico
+  - Lexing
+  - Parsing
+- Análisis Semántico
+  - Recolección de tipos (Type collection)
+  - Construcción de tipos (Type building)
+  - Chequeo de tipos (Type checking)
+- Generación de código (Code generation)
+  - COOL -> CIL
+  - CIL -> MIPS
+
+## Lexing
+
+Para el análisis léxico se utilizó el módulo `ply` de `Python`, el cual permite generar esta parte del proceso de manera automática simplemente definiendo el conjunto de tokens del lenguaje.
+
+Se emplearon dos estados exclusivos para el automata además del incial, uno para tokenizar los string y otros para los comentarios que ocupan multiples líneas.
+
+Al concluir esta fase se obtuvo cada uno de los tokens relevantes involcrados en el código fuente, estos almacenan su lexema y tipo de token.
+
+## Parsing
+
+De igual manera se utilizó `ply` para la fase de parsing debido a que soporta varios tipos de parsers como el parser `LALR(1)` que resuelve de manera eficiente la gramática de `COOL`, esta gramática se definió en base al manual oficial de `COOL` [cool-manual](./cool-manual.pdf), definida en su página 16.
+
+En esta fase se estableció la precedencia de los operadores de acuerdo al manual en la sección 11.1. Se establecieron las reglas de la gramática de forma apropiada para obtener el AST una vez finalizado el proceso de parsing de los tokens y asegurar que cada nodo almacena la línea y columna correspondiente al token, esto permite mejorar la información de los errores en el chequeo semántico.
+
+## Recolección de tipos
+
+Esta fase se encarga de recorrer el AST generado previamente y definir los tipos del lenguaje. Entre estos tipos tenemos los BUILT_IN (Bool, String, Int, IO, Object), así como los tipos definidos en el código por el usuario en las declaraciones de clases. En un recorrido posterior se realiza el chequeo y asignación de padres de tipos, debido a que en el lenguaje las declaraciones de clases se pueden encontrar en cualquier orden, por lo que es necesario recolectar los tipos primeramente. En esta fase se resuelven también las excepciones de herencia cíclica.
+
+La lógica para esta fase se implementó en el archivo `collector.py`
+
+## Construcción de tipos
+
+En esta fase se recorre el AST con el objetivo de visitar cada `feature`(método o atributo) de las clases para asignarla a cada tipo y chequear la existencia de una clase `Main` con el método `main`.
+
+La lógica para esta fase se implementó en el archivo `builder.py`
+
+## Chequeo de tipos
+
+Esta fase es la encargada de validar el uso correcto de los tipos definidos en el programa y detectar otros errores definidos dentro de la semántica de COOL, estos errores con su correspondiente descripcion pueden ser encontrados bajo el fichero `errors.py`.
+
+Por ejemplo entre ellos se encuentran:
+- Verificar que las asignaciones de las variables sea el tipo adecuado a su definición, así como los argumentos de funciones.
+- `self` es de solo lectura.
+- no violar el número de argumentos y los tipos de estos cuando se sobreescribe una función.
+- No usar variables que no estén definidas previamente en el contexto.
+- Evitar herencia de los tipos Int, String y Bool.
+- Verificar el correcto uso de los operadores +, -, /, *, <, <=, =, etc.
+- Evitar ramas duplicadas en el `case of`.
+
+En este recorrido sobre el AST además se crea el scope del programa para cada una de las clases, funciones, el `let in` y el `case of`. Los scopes establecen una jerarquía de herencia, de tal forma que el scope de una clase es hijo del scope de la clase que esta hereda, el scope de una función es hijo del scope de la clase en que esta se encuentra definida y los scopes de los `let in` y `case of` son hijos del scope del contexto en que se encuentren.
+
+Los scopes permiten ocultar las definiciones de variables de los contextos superiores. La salida de este recorrido sobre el AST es el scope raíz resultante de la visita a cada uno de los nodos.
+
+La lógica para esta fase se implementó en el archivo `checker.py`
+
+## Generación de código intermedio COOL -> CIL
+
+Para compilar el código en `COOL` a un lenguaje de bajo nivel como `MIPS`, se utilizó un lenguaje intermedio para disminuir la dificultad en la generación de código entre estas dos partes. Para ello definimos un pseudolenguaje (`CIL`) que posee elementos similares al estudiado en clase más algunos agregados y permiten controlar de una manera más sencilla el flujo del programa al generar el código en `MIPS`. Entre estos añadidos tenemos:
+
+- Abort
+
+  `ABORT`: Termina el programa con un mensaje indicando el tipo desde el cual se llamó esta instrucción.
+
+- Errores en tiempo de ejecución:
+
+  `CASE_MATCH_RUNTIME_ERROR`: Devuelve un error en tiempo de ejecución con el mensaje `"RuntimeError: Case statement without a match branch"`. Se usa en las expresiones de tipo case of cuando ninguna rama conforma el resultado de la expresión.
+
+  `EXPR_VOID_RUNTIME_ERROR`: Devuelve un error en tiempo de ejecución con el mensaje: `"RuntimeError: Expression is void"`. Usado para controlar excepciones con expresiones de tipo `void`
+
+- Conforms
+
+  `<var> = CONFORMS <expr> <Type>`: Usada para saber si el resultado de `<expr>` conforma el tipo `<Type>`. Se creó por la necesidad de saber en tiempo de ejecución si el tipo que retorna la expresión en un `case of` podía ser asignado a una rama de un tipo dado.
+
+Dicho esto, se implementaron 2 visitors encargados de generar el código en `CIL`. El primero se encuentra en el archivo `types_data_visitor.py` y es el encargado de definir las secciones `.TYPES` y `.DATA`, en donde se alojarán los tipos definidos en `COOL` y los datos constantes (mensajes de excepción, strings definidos en el código, ...) respectivamente. El segundo visitor encontrado en el archivo `code_visitor.py` se encarga de generar la sección `.CODE` en la cual se encuentra toda la lógica del programa. Ambos visitors fueron encargados de devolver un AST de `CIL` para el próximo paso de generación de código.
+
+### Manejo de `case of`
+
+Este tipo de expresión tuvo un tratamiento especial debido a que la evaluación del tipo de la expresión dentro del `case` se debe realizar en tiempo de ejecución, y en base a esta seleccionar la rama correspondiente como valor de retorno. Para resolver esto hacemos uso de la instrucción definida anteriormente en `CIL`: `CONFORMS`, sin embargo, con esto solo sabemos si el tipo de este resultado conforma el tipo de la rama, pero según la definición del `case of` queremos el tipo más específico que lo cumpla. Esto lo resolvimos reordenando las ramas del case en función a su profundidad en el árbol de tipos de mayor a menor, quedando como primeras ramas las más específicas. De esta manera, la primera rama que cumpla que `CONFORMS <expr> <branch.type>` sea verdadero, es la seleccionada, y será la más específica para ese tipo puesto que las de mayor profundidad ya fueron visitadas, por tanto se hace un salto para esa rama.
+
+## Generación de código intermedio: CIL -> MIPS
+
+Una vez tenemos el AST de `CIL`, solo resta el paso final, generar el código final `MIPS` que será el que se ejecutará desde el emulador `spim`. Para esto definimos un visitor encargado de traducir cada instrucción.
+
+### Representación de Instancias en Memoria
+
+Para representar los objetos de `CIL` en memoria desde `MIPS` usamos la siguiente notación:
+
+```
+Type: # Nombre del tipo
+  .word 4 # Espacio necesario para una instancia de este tipo
+  .word <Padre> # Label del tipo padre
+
+  # Métodos de la instancia
+  .word Type__init
+  .word Type__abort
+  .
+  .
+  .
+  #
+  .word Type_type_name # Label para direccionar el string del typename
+  .asciiz "Type" # Typename (String del tipo)
+```
+
+Esta definición se encuentra en la sección del `.data` de MIPS y se puede decir que sirve de esqueleto para la las instancias.
+
+Por lo visto anteriormente cada tipo contiene información relacionada con este, como la lista de atributos, métodos, el string correspondiente a su typename, así como una referencia al address del label de su padre. Todos los tipos son tratados como instancias de clases, incluyendo los `BUILT_IN` como `Int, String y Bool` en los que podemos ver su valor en el offset 4 de su dirección. Los métodos se representan con labels que son definidos posteriormente en la sección `.text` de `MIPS`. Existe un label especial llamado `main` que será el encargado de correr el programa, su función es instanciar el tipo `Main` y ejecutar sus instrucciones.
+
+Cada una de las instancias posee como primer atributo un puntero a su tipo correspondiente (ubicado en `.data`). En los bytes continuos almacena cada uno de sus atributos.
+
+Para resolver el método de una instancia primeramente se resuelve el tipo de la instancia, al cual apunta el primer byte de esta. Este puntero más el offset del método permite encontrar el label de la función correspondiente en mips e invocarla.
+
+Todos los procedimientos en mips esperan recibir las instancias por referencia, por tanto realizan internamente el unboxing de los atributos de estas. De igual forma al retornar un tipo Int, String, Bool, se retorna una nueva instancia con su tipo y valor correctamente asignados, no el valor que esta contiene.

doc/team.yml

@@ -1,10 +1,7 @@
 members:
-  - name: Nombre Apellido1 Apellido2
-    github: github_id
-    group: CXXX
-  - name: Nombre Apellido1 Apellido2
-    github: github_id
-    group: CXXX
-  - name: Nombre Apellido1 Apellido2
-    github: github_id
-    group: CXXX
+  - name: Samuel David Suarez Rodriguez
+    github: samueldsr99
+    group: C412
+  - name: Enmanuel Verdesia Suarez
+    github: svex99
+    group: C411

requirements.txt

@@ -1,2 +1,3 @@
 pytest
 pytest-ordering
+ply==3.11

src/coolc.py

@@ -0,0 +1,93 @@
+"""
+Main entry point of COOL compiler
+"""
+import os
+import subprocess
+
+from coolcmp.codegen.cil2mips.mips_formatter import MIPSFormatter
+from coolcmp.lexing_parsing.lexer import errors as lexer_errors
+from coolcmp.lexing_parsing.parser import parser, errors as parser_errors
+from coolcmp.semantics import check_semantics
+from coolcmp.codegen.cool2cil import build_cil
+
+from coolcmp.codegen.cil2mips import build_mips
+from coolcmp.utils.ast_formatter import ASTFormatter
+from coolcmp.utils.cil_formatter import CILFormatter
+
+from coolcmp.utils.cil import ProgramNode
+
+
+def main(filename: str, cool_code: str, run: bool, verbose: bool):
+    ast = parser.parse(cool_code)
+
+    if verbose:
+        ast_str = ASTFormatter().visit(ast)
+        print(ast_str)
+
+    if lexer_errors:
+        for error in lexer_errors:
+            print(error)
+        exit(1)
+
+    if parser_errors:
+        for error in parser_errors:
+            print(error)
+        exit(1)
+
+    sem_errors, ctx, scope = check_semantics(ast)
+    if sem_errors:
+        for error in sem_errors:
+            print(error)
+        exit(1)
+
+    cil: ProgramNode
+    cil = build_cil(ast, ctx, scope)
+
+    if verbose:
+        cil_str = CILFormatter().visit(cil)
+        print(cil_str)
+
+    mips = build_mips(cil, None, None)
+    mips_str = MIPSFormatter().visit(mips)
+
+    mips_file = filename + '.mips'
+
+    with open(mips_file, 'w') as fd:
+        fd.write(mips_str)
+
+    if run:
+        print('=' * 20, 'Running SPIM', '=' * 20)
+        subprocess.run(['spim', '-f', mips_file])
+
+
+if __name__ == "__main__":
+    from argparse import ArgumentParser, FileType, BooleanOptionalAction
+
+    arg_parser = ArgumentParser()
+    arg_parser.add_argument(
+        '--out', required=False,
+        help='Name for .mips generated file after compilation.'
+    )
+    arg_parser.add_argument(
+        '--run', default=False, action=BooleanOptionalAction,
+        help='Execute the file compiled with SPIM.'
+    )
+    arg_parser.add_argument(
+        '--verbose', default=False, action=BooleanOptionalAction,
+        help='Verbose output.'
+    )
+    arg_parser.add_argument(
+        'file', type=FileType(mode='r', encoding='utf8'),
+        help='COOL source file.'
+    )
+    args = arg_parser.parse_args()
+
+    full_name = args.file.name
+    filename = full_name[:full_name.rfind('.')]
+    cool_code = args.file.read()
+    main(
+        filename=args.out or filename,
+        cool_code=cool_code,
+        run=args.run,
+        verbose=args.verbose
+    )

src/coolc.sh

@@ -1,11 +1,9 @@
-# Incluya aquí las instrucciones necesarias para ejecutar su compilador
-
 INPUT_FILE=$1
 OUTPUT_FILE=${INPUT_FILE:0: -2}mips
 
-# Si su compilador no lo hace ya, aquí puede imprimir la información de contacto
-echo "LINEA_CON_NOMBRE_Y_VERSION_DEL_COMPILADOR"        # TODO: Recuerde cambiar estas
-echo "Copyright (c) 2019: Nombre1, Nombre2, Nombre3"    # TODO: líneas a los valores correctos
+echo "COOL-Compiler v1.0.0"
+echo "Copyright (c) 2021: Samuel David Suárez Rodríguez, Enmanuel Verdesia Suárez"
+
+# echo "Compiling $INPUT_FILE into $OUTPUT_FILE"
 
-# Llamar al compilador
-echo "Compiling $INPUT_FILE into $OUTPUT_FILE"
+python3 coolc.py $INPUT_FILE

src/coolcmp/codegen/cil2mips/__init__.py

@@ -0,0 +1,5 @@
+from .cil2mips_visitor import CILToMipsVisitor
+
+
+def build_mips(ast, context, scope):
+    return CILToMipsVisitor().visit(ast)