AUTHORS
-------

- FAURE AUGUSTIN
- GILLARD ANTONINO

===============

Description of the project
--------------------------

This μ-project is a simple compiler system composed of two main components: the Pfx virtual machine and the Expr
compiler, both written in OCaml using ocamllex and menhir. It aims to showcase stack-based computation and compiler
design through the implementation of these interconnected systems.

The Pfx virtual machine is designed to execute programs using a stack-based language.
Programs in Pfx are structured as pairs i, Q where:
  - i denotes the number of arguments required for execution.
  - Q represents the sequence of stack-based instructions.

The existing Pfx instructions can be divided into three categories:
  Stack Operations:
    push x: Pushes an integer xx onto the stack.
    pop: Removes the top element from the stack.
    swap: Exchanges the top two elements of the stack.

  Arithmetic Operations:
    Includes add, sub, mul, div, and rem, which:
      Use the top two elements of the stack as operands.
      Push the result back onto the stack after computation.

  Advanced Instructions:
    exec: Executes an executable sequence stored at the top of the stack.
    get: Pops an integer ii and duplicates the ii-th element of the stack at the top.
    append: Dynamically adds commands to executable sequences.

The Expr compiler is a complementary component that translates programs written in the
arithmetic expression language Expr into Pfx instructions.

Expr Language Features:
    Arithmetic Operations: This includes common mathematical operations such as addition,
  subtraction, multiplication, division, and handling negative values.
    Variables and Constants: Provides the ability to use named variables and constant
  values within expressions for greater flexibility and readability.
    Functions and Application Expressions: Allows defining functions and applying them
  within expressions

===============

Sources
-------

Git repository: https://github.com/Gillan0/compiler

No release. Please check the last commit in main branch.

===============

How to…
-------

…retrieve the sources?

  git clone https://github.com/Gillan0/compiler

…compile?

  dune build

…execute and test?

  dune runtest

  dune utop and then use the libraries
  (from project root) dune exec expr/main.exe -- expr/basic/tests/an_example.expr
  (from project root) dune exec ./pfx/pfxVM.exe 
  for pfxVM.exe, you can change the file in its .ml file

===============

Structure of the project
------------------------

The project is organized as following:

project
├── README
├── README.pdf : answers to non-code related questions
├── dune-project
├── expr: the expr compiler
│   ├── README
│   ├── basic : the first version of the expr compiler
│   │   ├── ast.ml : implements expr AST
│   │   ├── ast.mli
│   │   ├── dune
│   │   ├── eval.ml : implements the evaluation of a expr expression
│   │   ├── eval.mli
│   │   ├── lexer.mll : recognize tokens in a program in expr
│   │   ├── parser.mly : recognize sentences from expr tokens, return an AST and control
│   │   ├── tests: for tests
│   │   │   └── an_example.expr
│   │   ├── toPfx.ml : implements the expr semantics
│   │   └── toPfx.mli
│   ├── common : the elements common to both version of the compiler
│   │   ├── binOp.ml : define the binary operations for expr
│   │   ├── binOp.mli
│   │   └── dune
│   ├── compiler.ml: main file for the expr compiler
│   ├── dune
│   ├── fun: the new version of the expr compiler
│   │   ├── tests: for tests
│   │   │   ├── dune
│   │   │   ├── fun_test.expr
│   │   │   └── fun_test.ml : test the evaluation and the compilation for the new version
│   │   ├── ast.ml : implements expr AST
│   │   ├── ast.mli
│   │   ├── dune
│   │   ├── lexer.mll : recognize tokens in a program in expr
│   │   ├── parser.mly : recognize sentences from expr tokens, return an AST and control
│   │   ├── toPfx.ml : implements the expr semantics
│   │   └── toPfx.mli
│   └── main.ml
├── pfx: the pfx VM (Virtual Machine)
│   ├── basic: the first version of the pfx
│   │   ├── ast.ml : define the pfx instructions
│   │   ├── ast.mli
│   │   ├── dune
│   │   ├── eval.ml : implements the step reduction of the stack given an instruction
│   │   ├── eval.mli
│   │   ├── lexer.mll : recognize tokens in a program in pfx
│   │   └── parser.mly : recognize sentences from pfx tokens, return an AST and control
│   ├── fun: the new version of the pfx
│   │   ├── ast.ml : define the pfx instructions
│   │   ├── ast.mli
│   │   ├── dune
│   │   ├── eval.ml : implements the step reduction of the stack given an instruction
│   │   ├── eval.mli
│   │   ├── lexer.mll : recognize tokens in a program in pfx
│   │   └── parser.mly : recognize sentences from pfx tokens, return an AST and control
│   │── tests: for tests
│   │   |── basic_step_test.ml : test the implementation of the step reduction of the stack for the new version
│   │   |── compile_test.ml : test if the first version compile
│   │   |── dune
│   │   |── error_prog.pfx : pfx program that return an error
│   │   |── fun_prog.pfx : pfx program for the new version
│   │   |── fun_step_test.ml : test the implementation of the step reduction of the stack for the new version
│   │   |── fun_test.ml : test both the step reduction and if the new version compile
│   │   └── ok_prog.pfx : pfx program for the compilation test of the first version
│   │── dune
│   └── pfxVM.ml: main file for the pfx VM
└── utils
    ├── dune
    ├── location.ml: module offering a data type for a location in a file
    └── location.mli
===============

Progress
--------

- We stopped at question 13.6 (Describe step by step the evaluation of Pfx translation)
- None of the extensions have been tackled

===============

Know bugs and issues
--------------------

- None that we are aware of

===============


Difficulties
------------

- Understanding how dune works to run tests (writing dune files, ...)
- Tracking variable values in the stack for both implementation of expr/fun/toPfx.ml