From 41d24756da4fc592f48cc60aa72b4a1042fd9e3d Mon Sep 17 00:00:00 2001
From: Flavian Kaufmann <flavian@flaviankaufmann.ch>
Date: Thu, 22 May 2025 08:20:41 +0200
Subject: updated readme

---
 README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 63 insertions(+), 8 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 5420053..111d122 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,19 @@
 # IMP Interpreter
 
-A small interpreter of the IMP programming language.
+A small interpreter of the IMP programming language, written in *C* with *flex* for lexing and *bison* for parsing.
+Currently the core functionality of IMP is implemented, additionally, the *local variable extension*, and the *procedure extension* also. Furthermore there are some syntactic enhancements, such as the boolean constants `true` and `false`, omitting parenthesis around expressions, and the ability to add arbitrary many semicolons after each statement.
+
+
+## Dependencies
+
+- [flex](https://github.com/westes/flex)
+- [bison](https://www.gnu.org/software/bison)
+- [readline](https://tiswww.case.edu/php/chet/readline/rltop.html)
+
+
+## Resources
+
+- [Formal Methods and Functional Programming (Course Webpage), ETHZ](https://infsec.ethz.ch/education/ss2025/fmfp.html)
 
 
 ## Build
@@ -10,20 +23,34 @@ A small interpreter of the IMP programming language.
 - `make example` to interpret "example/example.imp".
 - `make clean` to remove build folder.
 
+All build artifacts are created in the build folder `./build`, including the imp binary (`./build/imp`).
 
-## Dependencies
 
-- [flex](https://github.com/westes/flex)
-- [bison](https://www.gnu.org/software/bison)
-- [readline](https://tiswww.case.edu/php/chet/readline/rltop.html)
+## Usage
 
-## Resources
+```
+Usage: imp [ARGS]
+  -i <program.imp>   interpret program and exit
+  (no args)          start REPL
+  -h                 show this message
+```
 
-- [Formal Methods and Functional Programming (Course Webpage), ETHZ](https://infsec.ethz.ch/education/ss2025/fmfp.html)
+### REPL
 
+```
+IMP REPL (type IMP statements or commands starting with '%')
+Commands:
+  %quit                   exit
+  %run <path/to/file.imp> interpret program
+  %set <var> <val>        set variable
+  %print [<var>]          print variable, or all variables
+  %help                   show this message
+```
 
 ## IMP
 
+### Syntax
+
 [Syntax](/res/syntax.ebnf)
 
 
@@ -44,6 +71,11 @@ Control flow:
 - `(<stm>; <stm>)` sequential composition, the first statement runs before the second
 - `skip`, nop
 
+Procedures:
+
+- `procedure <ident>(<var>, ... ; <var>, ... ) begin <stm> end` declaration, first argument list are value arguments (vars passed to procedure), second argument list are variable arguments (vars returned from procedure).
+- `<ident>(<var>, ... ; <var>, ... )` call
+
 
 **Expression**
 
@@ -66,13 +98,36 @@ Boolean Expression `<bexp>`:
 - `<aexp> <= <aexp>`
 - `<aexp> > <aexp>`
 - `<aexp> >= <aexp>`
+- `true`
+- `false`
 
 
 **Variable `<var>`**
 
-- `[a-zA-Z][A-Za-z0-9]*`
+- `<ident>`
 
 
 **Numeral `<num>`**
 
 - `[0-9]+`
+
+**Identifier `<ident>`**
+
+- `[a-zA-Z][A-Za-z0-9]*`
+
+### Example
+
+```
+procedure factorial(n;r) begin
+  if n <= 0 then
+    r := 1;
+  else
+    m := n - 1;
+    factorial(m;r);
+    r := r * n;
+  end;
+end;
+
+n := 5;
+factorial(n;r);
+```
\ No newline at end of file
-- 
cgit v1.2.3