v1.5.5-SNAPSHOT started. compile if support

docs/ai_language_reference.md

@@ -132,6 +132,9 @@ Primary sources used: `lynglib/src/commonMain/kotlin/net/sergeych/lyng/{Parser,T
 
 ## 6. Control Flow
 - `if` is expression-like.
+- `compile if (cond) { ... } else { ... }` is a compile-time-only conditional.
+  - current condition grammar is restricted to `defined(NameOr.Package)`, `!`, `&&`, `||`, and parentheses.
+  - the untaken branch is skipped by the compiler and is not name-resolved or type-checked.
 - `when(value) { ... }` supported.
   - branch conditions support equality, `in`, `!in`, `is`, `!is`, and `nullable` predicate.
   - `when { ... }` (subject-less) is currently not implemented.

docs/scopes_and_closures.md

@@ -6,6 +6,7 @@ This page documents the **current** rules: static name resolution, closure captu
 
 ## Current rules (bytecode compiler)
 - **All names resolve at compile time**: locals, parameters, captures, members, imports, and module globals must be known when compiling. Missing symbols are compile-time errors.
+- **Exception: `compile if` can skip dead branches**: inside an untaken `compile if (...)` branch, names are not resolved or type-checked at all. This is the supported way to guard optional classes or packages such as `defined(Udp)` or `defined(lyng.io.net)`.
 - **No runtime fallbacks**: there is no dynamic name lookup, no fallback opcodes, and no “search parent scopes” at runtime for missing names.
 - **Object members on unknown types only**: `toString`, `toInspectString`, `let`, `also`, `apply`, `run` are allowed on unknown types; all other members require a statically known receiver type or an explicit cast.
 - **Closures capture slots**: lambdas and nested functions capture **frame slots** directly. Captures are resolved at compile time and compiled to slot references.

docs/tutorial.md

@@ -1094,6 +1094,37 @@ Or, more neat:
     >>> just 3
     >>> void
 
+## compile if
+
+`compile if` is a compile-time conditional. Unlike normal `if`, the compiler evaluates its condition while compiling
+the file and completely skips the untaken branch. This is useful when some class or package may or may not be
+available:
+
+    compile if (defined(Udp)) {
+        val socket = Udp()
+        println("udp is available")
+    } else {
+        println("udp is not available")
+    }
+
+`compile if` also supports single-statement branches:
+
+    compile if (defined(lyng.io.net) && !defined(Udp))
+        println("network module exists, but Udp is not visible here")
+    else
+        println("either Udp exists or the module is unavailable")
+
+Current condition syntax is intentionally limited to compile-time symbol checks:
+
+- `defined(Name)`
+- `defined(package.name)`
+- `!`, `&&`, `||`
+- parentheses
+
+Examples:
+    compile if (defined(Udp) && defined(Tcp))
+        println("both transports are available")
+
 ## When
 
 See also: [Comprehensive guide to `when`](when.md)