From dd02cc1fc47d3dc87e35d8f363ae12c26919acd5 Mon Sep 17 00:00:00 2001
From: TudbuT <forge-public@mail.tudbut.de>
Date: Tue, 19 Nov 2024 07:16:28 +0100
Subject: [PATCH] better readme

---
 README.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/README.md b/README.md
index 98ff53c..b4e04fe 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,9 @@ func main { mega | with args ;
         &print swap:foreach
     "" println
     println<"and with that, we're done">
+    [ ^hello ^pattern-matching ] => [ ^hello &=args ] if { 
+        args println "prints pattern-matching";
+    }
     0
 }
 ```
@@ -262,3 +265,42 @@ As you can see, it's relatively straight-forward to do; but there are some major
 The second one is easy to fix, but I intend to fix the first one first. Sadly, fixing it requires
 compiling the code as a dynamic library and also getting it to work with the program its running in. 
 If anyone knows how to do this properly, I'd REALLY appreciate a PR or issue explaining it.
+
+## Syntactic sugar
+
+There's a lot of things that look kinda tedious to do in SPL, syntactically speaking. So over time,
+I regularly add syntactic sugar:
+
+- `a => b` -> `a b match`
+- `a =>? b` -> `a dup b match _'match-else-push` (match that will push the offending value on error)
+- `a =>! b` -> `a b match _'match-else-error` (match that throws an error when unable to match)
+- `a<| b c d e>` -> `a<{ | b c d e }>` -> `{ | b c d e } a`
+- `def a, b, c` -> `def a def b def c`
+
+## Matching
+
+The match function `match` and its accompanying sugar take in two values and essentially do a special
+compare for equality on them. Unlike everything else, which is just compared normally, arrays are
+iterated through and their items checked individually, recursively. When a callable (`{ ... | ... }`)
+is found in b, any value in a is accepted for it, and the function is called *if and only if* every
+other part of the match also succeeds.
+The function returns 1 on success, otherwise 0.
+
+Example:
+```js
+def a, val
+[ ^ok "hey matcher" ] =a
+
+a =>! [ ^ok &=val ]
+val println
+
+a =>? [ ^ok &=val ] not if {
+  "error: " swap concat panic
+}
+val println
+
+a => [ ^ok &=val ] not if {
+  "error" panic
+}
+val println
+```