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 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 res/syntax.ebnf   | 12 ++++++++++
 src/interpreter.c |  2 +-
 3 files changed, 76 insertions(+), 9 deletions(-)

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
diff --git a/res/syntax.ebnf b/res/syntax.ebnf
index 85990c5..af6b5ea 100644
--- a/res/syntax.ebnf
+++ b/res/syntax.ebnf
@@ -44,4 +44,16 @@ statement             = "skip"
                       | ( "if" , boolean_expression , "then" , statement , "else" , statement , "end" )
                       | ( "while" , boolean_expression , "do" , statement , "end" )
                       | ( "var" , variable , ":=", arithmetic_expression , "in" , statement , "end" )
+                      | proc_decl
+                      | proc_call
+                      ;
+
+arg_list              = variable
+                      | ( arg_list , "," , variable )
+                      ;
+
+proc_decl             = "procedure" , identifier , "(" , arg_list , ";" , arg_list , ")" , "begin" , statement , "end"
+                      ;
+
+proc_call             = identifier , "(" , arg_list , ";" , arg_list , ")"
                       ;
\ No newline at end of file
diff --git a/src/interpreter.c b/src/interpreter.c
index 9dc5a22..2f13ec0 100644
--- a/src/interpreter.c
+++ b/src/interpreter.c
@@ -208,7 +208,7 @@ int interp_ast(Context *context, ASTNode *node) {
         fprintf(stderr, "Error: procedure %s already defined\n", name);
         return -1;
       }
-      ASTNode *procdecl = ast_clone(node);      
+      ASTNode *procdecl = ast_clone(node);
       context_set_proc(context, name, procdecl);
       return 0;
     }
-- 
cgit v1.2.3