Merge pull request #815 from smucclaw/thomasgorissen/documentation-v2

feat(documentation): Mixfix/infix/postfix

Author: serrynaimo

doc/README.md

@@ -51,10 +51,10 @@ Learn L4 from scratch. No prior programming experience required.
 
 Deep dives for production use.
 
-- Real Regulatory Schemes
-- Cross-Cutting Concerns
-- Complex Contracts
-- Production Patterns
+- Module A1: Real Regulatory Schemes
+- Module A2: Cross-Cutting Concerns
+- Module A3: Complex Contracts
+- Module A4: Production Patterns
 
 **Prerequisites:** Foundation Course
 

doc/concepts/legal-modeling/regulative-rules.md

@@ -245,8 +245,8 @@ LEST BREACH
 
 ```
 ┌──────────────────────────────────────────────┐
-│                  CREATED                      │
-│           (rule becomes active)               │
+│                  CREATED                     │
+│           (rule becomes active)              │
 └──────────────────────────────────────────────┘
                       │
                       ▼

doc/courses/foundation/module-3-control-flow.md

@@ -33,16 +33,18 @@ GIVETH A STRING
 
 Every `IF` must have both `THEN` and `ELSE` branches—L4 requires you to handle all cases.
 
-### Nested Conditionals
+### Nested Conditionals with BRANCH
 
 ```l4
 GIVEN score IS A NUMBER
 GIVETH A STRING
-`the letter grade` MEANS
-    IF score >= 90 THEN "A"
-    ELSE IF score >= 80 THEN "B"
-    ELSE IF score >= 70 THEN "C"
-    ELSE "F"
+`grade` MEANS
+    BRANCH
+        IF score >= 90 THEN "A"
+        IF score >= 80 THEN "B"
+        IF score >= 70 THEN "C"
+        IF score >= 60 THEN "D"
+        OTHERWISE "F"
 ```
 
 ### Conditional in Context

doc/reference/functions/DECIDE.md

@@ -97,8 +97,6 @@ DECIDE isEligible IF
 - **[WHERE](WHERE.md)** - Local definitions
 - **[IF](../control-flow/IF.md)** - Boolean condition form
 
-> Note: IS is part of the DECIDE syntax, not a separate keyword page.
+## Tutorials
 
-## See Also
-
-- **[Keywords Reference](README.md)** - All keywords
+- **[Using Infix, Postfix, and Mixfix Functions](../../tutorials/natural-language-functions/natural-language-functions.md)** - Define functions that read like natural language

doc/reference/functions/MEANS.md

@@ -80,4 +80,6 @@ LET y MEAN 10 IN y PLUS 1
 - **[DECIDE](DECIDE.md)** - Declares a decision
 - **[WHERE](WHERE.md)** - Local definitions
 
-> Note: IS and BE are alternative forms with the same meaning as MEANS.
+## Tutorials
+
+- **[Using Infix, Postfix, and Mixfix Functions](../../tutorials/natural-language-functions/natural-language-functions.md)** - Define functions that read like natural language

doc/tutorials/README.md

@@ -13,6 +13,15 @@ New to L4? Start here:
 
 ## By Topic
 
+### Natural Language Functions
+
+Write functions that read like legal prose:
+
+- **[Infix, Postfix, and Mixfix Functions](natural-language-functions/natural-language-functions.md)** - Define operators like `` `is eligible for` `` or `` `percent` ``
+
+**Audience:** All L4 users  
+**Prerequisites:** Basic function syntax
+
 ### LLM Integration
 
 Working with AI and language models in L4:

doc/tutorials/SUMMARY.md

@@ -10,6 +10,10 @@
 - [Wedding Vows](getting-started/wedding-vows.md)
 - [Common Patterns](getting-started/common-patterns.md)
 
+## Natural Language Functions
+
+- [Using Infix, Postfix, and Mixfix Functions](natural-language-functions/natural-language-functions.md)
+
 ## LLM Integration
 
 - [Getting Started with LLM](llm-integration/llm-getting-started.md)

doc/tutorials/getting-started/wedding-vows.md

@@ -5,7 +5,7 @@ A fun introduction to regulative rules using wedding vows.
 **Audience:** Anyone new to regulative rules  
 **Prerequisites:** Basic L4 knowledge  
 **Time:** 20 minutes  
-**Goal:** Understand MUST, MAY, SHANT, HENCE, and LEST through a familiar example
+**Goal:** Understand MUST, MAY, SHANT, DO, HENCE, and LEST through a familiar example
 
 ---
 
@@ -38,7 +38,7 @@ DECLARE Action IS ONE OF
     `have and hold`
     `support`
     `care for`
-    abandon
+    `abandon`
     `be unfaithful`
 ```
 
@@ -76,7 +76,7 @@ GIVETH DEONTIC Person Action
 | ------------------------------ | ------------------------------------------------------------------------ |
 | `GIVETH DEONTIC Person Action` | This returns an obligation/permission involving these actors and actions |
 | `PARTY Spouse1`                | Spouse1 is the one with the obligation                                   |
-| `MUST \`exchange vows\``       | They must exchange vows                                                  |
+| `` `MUST `exchange vows` ``    | They must exchange vows                                                  |
 | `WITHIN 1`                     | Within 1 day (the wedding day)                                           |
 | `HENCE ...`                    | If they do, then Spouse2 must respond                                    |
 | `LEST BREACH`                  | If they don't, it's a breach                                             |
@@ -181,6 +181,7 @@ GIVETH DEONTIC Person Action
 | `MUST`  | Required action   | Must love and cherish   |
 | `MAY`   | Permitted action  | May have pets           |
 | `SHANT` | Prohibited action | Shall not be unfaithful |
+| `DO`    | Possible action   | enters the premise      |
 
 ---
 

doc/tutorials/natural-language-functions/natural-language-example.l4

@@ -0,0 +1,146 @@
+§ `Natural Language Functions Tutorial`
+
+-- This file demonstrates infix, postfix, and mixfix function patterns
+-- that allow L4 code to read like natural language.
+
+-- ============================================================================
+-- INFIX FUNCTIONS
+-- Pattern: param `keyword` param
+-- ============================================================================
+
+-- Simple numeric infix operator
+GIVEN a IS A NUMBER, b IS A NUMBER
+GIVETH A NUMBER
+a `plus` b MEANS a + b
+
+-- Multi-word infix operator
+GIVEN person IS A STRING, program IS A STRING
+GIVETH A BOOLEAN
+person `is eligible for` program MEANS TRUE
+
+-- Test infix calls
+#EVAL 3 `plus` 5
+#EVAL "Alice" `is eligible for` "Medicare"
+
+-- Infix can also be called with prefix notation
+#EVAL `plus` 10 20
+
+-- ============================================================================
+-- POSTFIX FUNCTIONS
+-- Pattern: param `keyword`
+-- ============================================================================
+
+-- Simple postfix operator
+GIVEN amount IS A NUMBER
+GIVETH A NUMBER
+amount `percent` MEANS amount / 100
+
+-- Another postfix example
+GIVEN n IS A NUMBER
+GIVETH A NUMBER
+n squared MEANS n * n
+
+-- Test postfix calls
+#EVAL 50 `percent`
+#EVAL 75 percent
+#EVAL 5 squared
+#EVAL 7 `squared`
+
+-- Postfix with expressions
+#EVAL (10 + 5) `percent`
+
+-- ============================================================================
+-- TERNARY MIXFIX FUNCTIONS
+-- Pattern: `keyword` param `keyword` param `keyword` param
+-- ============================================================================
+
+-- Custom conditional operator
+GIVEN cond IS A BOOLEAN, thenVal IS A NUMBER, elseVal IS A NUMBER
+GIVETH A NUMBER
+`myif` cond `mythen` thenVal `myelse` elseVal MEANS
+  IF cond THEN thenVal ELSE elseVal
+
+-- Test ternary mixfix
+#EVAL `myif` TRUE `mythen` 42 `myelse` 0
+#EVAL `myif` FALSE `mythen` 42 `myelse` 0
+#EVAL `myif` (1 = 1) `mythen` (10 + 5) `myelse` (20 - 5)
+
+-- ============================================================================
+-- QUATERNARY MIXFIX FUNCTIONS
+-- Pattern: param `keyword` param `keyword` param `keyword` param
+-- ============================================================================
+
+GIVEN mummy IS A STRING, daddy IS A STRING, baby IS A STRING, nickname IS A STRING
+GIVETH A STRING
+mummy `and` daddy `had` baby `called` nickname MEANS baby
+
+-- Test quaternary mixfix
+#EVAL "Alice" `and` "Bob" `had` "Charlie" `called` "Chuck"
+
+-- Prefix notation also works
+#EVAL `and` "Mom" "Dad" "Kid" "Kiddo"
+
+-- ============================================================================
+-- ARITY-5 MIXFIX FUNCTIONS
+-- ============================================================================
+
+GIVEN a IS A NUMBER, b IS A NUMBER, c IS A NUMBER, d IS A NUMBER, e IS A NUMBER
+GIVETH A NUMBER
+a `op1` b `op2` c `op3` d `op4` e MEANS a + b + c + d + e
+
+#EVAL 1 `op1` 2 `op2` 3 `op3` 4 `op4` 5
+#EVAL (10 - 9) `op1` (1 + 1) `op2` 3 `op3` (2 * 2) `op4` 5
+
+-- ============================================================================
+-- RANGE CHECK MIXFIX
+-- A practical example for legal conditions
+-- ============================================================================
+
+GIVEN lower IS A NUMBER, value IS A NUMBER, upper IS A NUMBER
+GIVETH A BOOLEAN
+lower `is at most` value `which is at most` upper MEANS
+  lower <= value AND value <= upper
+
+#EVAL 0 `is at most` 5 `which is at most` 10
+#EVAL 0 `is at most` 15 `which is at most` 10
+
+-- ============================================================================
+-- PRACTICAL LEGAL EXAMPLE
+-- Functions that read like legal prose
+-- ============================================================================
+
+DECLARE Person HAS
+  name IS A STRING
+  age IS A NUMBER
+
+GIVEN person IS A Person
+GIVETH A BOOLEAN
+person `is an adult` MEANS person's age >= 18
+
+GIVEN person IS A Person
+GIVETH A BOOLEAN
+person `is a minor` MEANS person's age < 18
+
+-- Create test data
+`test adult` MEANS Person WITH name IS "Alice", age IS 30
+`test minor` MEANS Person WITH name IS "Bob", age IS 15
+
+-- Test legal predicates
+#EVAL `test adult` `is an adult`
+#EVAL `test minor` `is a minor`
+
+-- ============================================================================
+-- MIXFIX WITH WHERE CLAUSE
+-- Defining helper operators locally
+-- ============================================================================
+
+GIVEN radius IS A NUMBER
+GIVETH A NUMBER
+`circle area for radius` radius MEANS
+  radius `squared locally` TIMES pi
+  WHERE
+    pi MEANS 3.14159
+    GIVEN r IS A NUMBER
+    r `squared locally` MEANS r * r
+
+#EVAL `circle area for radius` 10