From 544bbfac72a510c55d56165871d1d3f3d7c6f017 Mon Sep 17 00:00:00 2001
From: "Johan B.W. de Vries" <info@jbwdevries.nl>
Date: Sat, 7 Jun 2025 14:00:03 +0200
Subject: [PATCH] Updates the README for clarity

---
 README.md | 99 +++++++++++++++++++++++++++++++------------------------
 1 file changed, 56 insertions(+), 43 deletions(-)

diff --git a/README.md b/README.md
index dffe84f..a3419ca 100644
--- a/README.md
+++ b/README.md
@@ -3,46 +3,14 @@ phasm
 
 Elevator pitch
 --------------
-A programming language, that looks like Python, handles like Haskell,
+A programming language that looks like Python, handles like Haskell,
 and compiles directly to WebAssembly.
 
-Project state
--------------
-This is a hobby project for now. Use at your own risk.
-
-How to run
-----------
-You should only need make and python3. Currently, we're working with python3.10,
-since we're using the python ast parser, it might not work on other versions.
-
-To run the examples:
-```sh
-make examples
-```
-
-To run the tests:
-```sh
-make test
-```
-
-To run the linting and type checking:
-```sh
-make lint typecheck
-```
-
-To compile a Phasm file:
-```sh
-python3.12 -m phasm source.py output.wat
-```
-
-Additional required tools
--------------------------
-At the moment, the compiler outputs WebAssembly text format. To actually
-get a binary, you will need the wat2wasm tool[6].
-
 Example
 -------
-For more examples, see the examples directory.
+
+From `examples/fib.py`:
+
 ```py
 def helper(n: u64, a: u64, b: u64) -> u64:
     if n < 1:
@@ -61,6 +29,55 @@ def fib(n: u64) -> u64:
     return helper(n - 1, 0, 1)
 ```
 
+Compile to a WebAssembly text file:
+```sh
+python3 -m phasm examples/fib.py examples/fib.wat
+```
+
+Generate a WebAssembly binary file:
+```sh
+python wat2wasm.py examples/fib.wat -o examples/fib.wasm
+```
+
+Ready for including in your WebAssembly runtime!
+
+Run `make examples` to start a local web server with some more examples. Each example has the source listed, as well as the compiled WebAssembly text.
+
+Project state
+-------------
+This is a hobby project for now. Use at your own risk.
+
+The parser, compiler and type checker are in a reasonably usable state.
+
+What's still lacking is support for runtimes - notably, making it easier to get values in and out of the runtime.
+For example, while Phasm supports a u32 type, when you get your value out, it will probably be a signed value.
+And getting strings, structs, arrays and other combined values in and out requires manual work.
+
+How to run
+----------
+You should only need make and python3. Currently, we're working with python3.12,
+since we're using the python ast parser, it might not work on other versions.
+
+To compile a Phasm file:
+```sh
+python3.12 -m phasm source.py output.wat
+```
+
+To run the examples:
+```sh
+make examples
+```
+
+To run the tests:
+```sh
+make test
+```
+
+To run the linting and type checking:
+```sh
+make lint typecheck
+```
+
 Gotcha's
 --------
 - When importing and exporting unsigned values to WebAssembly, they will become
@@ -83,6 +100,9 @@ Also, if you are trying out Phasm, and you're running into a limitation, we're
 interested in a minimal test case that shows what you want to achieve and how
 Phasm currently fails you.
 
+We're also investigating using WASI - but that's still ongoing research. If you
+have tips or ideas on that, we'd be interested.
+
 Name origin
 -----------
 - p from python
@@ -96,10 +116,3 @@ References
 [3] https://webassembly.org/  
 [4] https://www.w3.org/TR/wasm-core-1/  
 [5] https://en.wikipedia.org/w/index.php?title=WebAssembly&oldid=1103639883  
-[6] https://github.com/WebAssembly/wabt  
-
-Links
------
-
-- https://pengowray.github.io/wasm-ops/  
-  Shorthand overview for supported operations in WebAssembly.