add extra docs with php+clojure examples

Author: Chemaclass

content/documentation/basic-types.md

@@ -5,14 +5,38 @@ weight = 2
 
 ## Nil, True, False
 
-Nil, true and false are literal constants. In Phel, `nil` is the same as `null` in PHP. Phel's `true` and `false` are the same as PHP's `true` and `false`.
+Nil, true and false are literal constants.
 
 ```phel
 nil
 true
 false
 ```
 
+In Phel, only `false` and `nil` are falsy. Everything else is truthy—including `0`, `""`, and `[]`.
+
+```phel
+# Truthiness examples
+(if nil "yes" "no")   # => "no"  (nil is falsy)
+(if false "yes" "no") # => "no"  (false is falsy)
+(if 0 "yes" "no")     # => "yes" (0 is truthy!)
+(if "" "yes" "no")    # => "yes" (empty string is truthy!)
+(if [] "yes" "no")    # => "yes" (empty vector is truthy!)
+```
+
+{% php_note() %}
+In PHP, `nil` is the same as `null`, and `true`/`false` are the same. However, truthiness works differently:
+
+**PHP**: `0`, `""`, `[]`, `null`, and `false` are all falsy
+**Phel**: Only `false` and `nil` are falsy
+
+This means `if (0)` in PHP is false, but `(if 0 ...)` in Phel is true!
+{% end %}
+
+{% clojure_note() %}
+Truthiness is the same as Clojure—only `false` and `nil` are falsy.
+{% end %}
+
 ## Symbol
 
 Symbols are used to name functions and variables in Phel.
@@ -26,7 +50,7 @@ my-module/my-function
 
 ## Keywords
 
-A keyword is like a symbol that begins with a colon character. However, it is used as a constant rather than a name for something.
+A keyword is like a symbol that begins with a colon character. However, it is used as a constant rather than a name for something. Keywords are interned and fast for equality checks.
 
 ```phel
 :keyword
@@ -36,6 +60,39 @@ A keyword is like a symbol that begins with a colon character. However, it is us
 ::
 ```
 
+Keywords are commonly used as map keys and function options:
+
+```phel
+# Map keys
+{:name "Alice" :email "[email protected]"}
+
+# Function arguments for options
+(defn greet [name & {:keys [formal?]}]
+  (if formal?
+    (str "Good day, " name)
+    (str "Hey, " name)))
+
+(greet "Alice" :formal? true)  # => "Good day, Alice"
+```
+
+{% php_note() %}
+Keywords are like string constants, but more efficient for map keys. Use keywords instead of strings for map keys:
+
+```phel
+# Less idiomatic:
+{"name" "Alice" "age" 30}
+
+# Idiomatic:
+{:name "Alice" :age 30}
+```
+
+Keywords are interned (only one instance exists in memory), making equality checks very fast.
+{% end %}
+
+{% clojure_note() %}
+Keywords work exactly like in Clojure—they're interned, fast for equality checks, and self-evaluate.
+{% end %}
+
 ## Numbers
 
 Phel supports integers and floating-point numbers. Both use the underlying PHP implementation. Integers can be specified in decimal (base 10), hexadecimal (base 16), octal (base 8) and binary (base 2) notations. Binary, octal and hexadecimal formats may contain underscores (`_`) between digits for better readability.
@@ -69,9 +126,7 @@ Phel supports integers and floating-point numbers. Both use the underlying PHP i
 
 ## Strings
 
-Strings are surrounded by double quotes. They almost work the same as PHP double-quoted strings. One difference is that the dollar sign (`$`) must not be escaped. Internally, Phel strings are represented by PHP strings. Therefore, every PHP string function can be used to operate on the string.
-
-Strings can be written over multiple lines. The line break character is then ignored by the reader.
+Strings are surrounded by double quotes. The dollar sign (`$`) does not need to be escaped.
 
 ```phel
 "hello world"
@@ -89,9 +144,28 @@ string."
 
 "Hexadecimal notation is supported: \x41"
 
-"Unicodes can be encoded as in PHP: \u{1000}"
+"Unicodes can be encoded: \u{1000}"
+```
+
+String concatenation and conversion using `str`:
+
+```phel
+(str "Hello" " " "World")  # => "Hello World"
+(str "The answer is " 42)  # => "The answer is 42"
+```
+
+{% php_note() %}
+Phel strings are PHP strings internally, so you can use all PHP string functions:
+
+```phel
+(php/strlen "hello")                 # => 5
+(php/strtoupper "hello")             # => "HELLO"
+(php/str_replace "o" "0" "hello")    # => "hell0"
 ```
 
+Strings work almost the same as PHP double-quoted strings, with one difference: the dollar sign (`$`) doesn't need escaping.
+{% end %}
+
 ## Lists
 
 A list is a sequence of whitespace-separated values surrounded by parentheses.
@@ -118,17 +192,42 @@ A vector in Phel is an indexed data structure. In contrast to PHP arrays, Phel v
 
 ## Maps
 
-A map is a sequence of whitespace-separated key/value pairs surrounded by curly braces, wherein the key and value of each key/value pair are separated by whitespace. There must be an even number of items between curly braces or the parser will signal a parse error. The sequence is defined as key1, value1, key2, value2, etc.
+A map is a sequence of whitespace-separated key/value pairs surrounded by curly braces. The sequence is defined as key1, value1, key2, value2, etc. There must be an even number of items.
 
 ```phel
 {} # same as (hash-map)
 {:key1 "value1" :key2 "value2"}
-{'(1 2 3) '(4 5 6)}
-{[] []}
-{1 2 3 4 5 6}
+
+# Any type can be a key
+{'(1 2 3) '(4 5 6)}  # Lists as keys
+{[] []}              # Vectors as keys
+{1 2 3 4 5 6}        # Numbers as keys
+
+# Common pattern: keywords as keys
+{:name "Alice" :age 30 :email "[email protected]"}
+```
+
+{% php_note() %}
+Unlike PHP associative arrays, Phel maps:
+- Can have **any type** as keys (not just strings/integers): vectors, lists, or even other maps
+- Are **immutable**: operations return new maps without modifying the original
+- Are **not** PHP arrays internally—they're their own data structure
+
+```phel
+# PHP:
+$map = ['name' => 'Alice'];
+$map['name'] = 'Bob';  // Mutates in place
+
+# Phel:
+(def map {:name "Alice"})
+(def new-map (assoc map :name "Bob"))  # Returns new map
+# map is still {:name "Alice"}
 ```
+{% end %}
 
-In contrast to PHP associative arrays, Phel maps can have any types of keys.
+{% clojure_note() %}
+Maps work exactly like Clojure maps, including support for any hashable type as keys.
+{% end %}
 
 ## Sets
 

content/documentation/control-flow.md

@@ -17,9 +17,9 @@ The _test_ evaluates to `false` if its value is `false` or equal to `nil`. Every
 (if true 10) # Evaluates to 10
 (if false 10) # Evaluates to nil
 (if true (print 1) (print 2)) # Prints 1 but not 2
-(if 0 (print 1) (print 2)) # Prints 2
+(if 0 (print 1) (print 2)) # Prints 1
 (if nil (print 1) (print 2)) # Prints 2
-(if [] (print 1) (print 2)) # Prints 2
+(if [] (print 1) (print 2)) # Prints 1
 ```
 
 ## Case
@@ -145,11 +145,11 @@ have the form `:modifier argument`. The following modifiers are supported:
 (for [[k v] :pairs {:a 1 :b 2 :c 3}] [v k]) # Evaluates to [[1 :a] [2 :b] [3 :c]]
 (for [[k v] :pairs [1 2 3]] [k v]) # Evaluates to [[0 1] [1 2] [2 3]]
 (for [[k v] :pairs {:a 1 :b 2 :c 3} :reduce [m {}]]
-  (put m k (inc v))) # Evaluates to {:a 2 :b 3 :c 4}
+  (assoc m k (inc v))) # Evaluates to {:a 2 :b 3 :c 4}
 (for [[k v] :pairs {:a 1 :b 2 :c 3} :reduce [m {}] :let [x (inc v)]]
-  (put m k x)) # Evaluates to {:a 2 :b 3 :c 4}
+  (assoc m k x)) # Evaluates to {:a 2 :b 3 :c 4}
 (for [[k v] :pairs {:a 1 :b 2 :c 3} :when (contains-value? [:a :c] k) :reduce [acc {}]]
-    (put acc k v)) # Evaluates to {:a 1 :c 3}
+    (assoc acc k v)) # Evaluates to {:a 1 :c 3}
 
 (for [x :in [2 2 2 3 3 4 5 6 6] :while (even? x)] x) # Evaluates to [2 2 2]
 (for [x :in [2 2 2 3 3 4 5 6 6] :when (even? x)] x) # Evaluates to [2 2 2 4 6 6]