From 0d194c59accceab9d87479436915bd1ab00becbd Mon Sep 17 00:00:00 2001
From: gavr123456789 <gavr123456789@gmail.com>
Date: Mon, 10 Mar 2025 00:34:24 +0200
Subject: [PATCH 1/9] init

---
 niva.md | 233 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 233 insertions(+)
 create mode 100644 niva.md

diff --git a/niva.md b/niva.md
new file mode 100644
index 00000000..e09311ba
--- /dev/null
+++ b/niva.md
@@ -0,0 +1,233 @@
+---
+name: niva
+filename: learnniva.niva
+contributors:
+    - ["gavr", "https://github.com/gavr123456789"]
+---
+
+## Intro
+Niva is a simple language that takes a lot of inspiration from Smalltalk. But leaning towards the functional side. Everything is still an object but instead of classes, interfaces, and abstract classes, we have tagged unions, which is the only way to achieve polymorphism.
+
+So basically niva is types, unions and methods for them. 
+
+On an imaginary graph of complexity, I would put it here:
+Go < Niva < Java < Kotlin < Scala
+
+Links:
+- [Site](https://gavr123456789.github.io/niva-site/reference.html)
+- [GitHub](https://github.com/gavr123456789/Niva)
+- [LSP](https://github.com/gavr123456789/vaLSe)
+- [VSC plugin](https://github.com/gavr123456789/niva-vscode-bundle)
+
+## The Basics
+
+#### Variable
+Variables are immutable by default.
+There is no keyword for declarating a variable.
+
+```Scala
+// this is a comment
+int = 1 
+str = "qwf"
+boolean = true 
+char = 'a'
+float = 3.14f
+double = 3.14
+mutltilineStr = """
+qwf ars zxc \n \t "qwf"
+"""
+explicit_type::Int = 5
+
+mut x = 5
+x <- 6 // mutate
+```
+
+
+#### Type
+
+```Scala
+type Square side: Int
+type Person
+    name: String
+    age: Int
+```
+
+#### Create instance
+```Scala
+square = Square side: 42
+alice = Person name: "Alice" age: 24
+
+// destruct fields by names
+{age name} = alice
+```
+
+#### Access fields
+Getting fields is the same as sending message with its name to object 
+```Scala
+// get age, add 1 to it and print
+alice age inc echo // 25
+```
+
+#### Method for type:  
+Everything is an object, just like in Smalltalk, so everything can have a method declared.   
+Here, we add a `double` method to `Int` and then use it inside the `perimeter` method of `Square`.
+
+```Scala
+Int double = this + this
+Square perimeter = side double
+
+square = Square side: 42
+square perimeter // call
+```
+
+
+#### Messages with many args
+```Scala
+type Range from: Int to: Int
+Int to::Int = Range from: this to: to
+
+1 to: 2 // Range
+```
+#### Type constructor
+Its like a message for type itself instead of instance
+```Scala
+constructor Float pi = 3.14
+x = Float pi // 3.14
+```
+
+It can be useful for initializing fields with default values.
+```Scala
+type Point x: Int y: Int
+constructor Point atStart = Point x: 0 y: 0
+
+p1 = Point x: 0 y: 0
+p2 = Point atStart
+// constructor is just a usual message, so it can have params
+constructor Point y::Int = Point x: 0 y: y
+p3 = Point y: 20 // x: 0 y: 20
+
+```
+
+
+#### Conditions
+=> is syntax sugar for ifTrue message, since conditions is pretty common
+```Scala
+// syntax sugar
+1 < 2 => "yay" echo
+// everything is message send(this is free because of lambda-inlining)
+1 < 2 ifTrue: ["yay" echo]
+
+// with else branch
+1 > 2 => "yay" echo |=> "oh no" echo
+
+1 > 2 ifTrue: ["yay" echo] ifFalse: ["oh no" echo]
+```
+
+#### Cycles
+There is no special syntax for cycles, its just keyword messages that takes codeblocs as parameters.  
+(its zero cost thanks for inlining)
+```Scala
+{1 2 3} forEach: [ it echo ]
+1..10 forEach: [ it echo ]
+
+mut c = 10
+[c > 0] whileTrue: [ c <- c dec ]
+```
+`whileTrue` is a message for codeblock of type: 
+`[ -> Boolean] whileTrue::[ -> Unit]`
+
+#### Matching
+there is special syntax for matching, since niva heavily utilize tagged unions
+```Scala
+x = "Alice"
+// matching on x
+| x
+| "Bob" => "Hi Bob!"
+| "Alice" => "Hi Alice!"
+|=> "Hi guest"
+
+
+// It can be used as expression as well
+y = | "b"
+    | "a" => 1
+    | "b" => 2
+    |=> 0
+y echo // 2
+```
+
+#### Unions
+
+```Scala
+union Shape =
+    | Rectangle width: Int height: Int
+    | Circle    radius: Int
+    
+constructor Float pi = 3.14
+
+// match on this(Shape)
+Shape getArea -> Float = | this 
+    | Rectangle => width * height |> toFloat
+    | Circle => Float pi * radius * radius
+    
+// its exhaustive, so when u add new branch 
+// all the matches will become errors until all cases processed
+```
+
+#### Collections 
+```Scala
+// commas are optional
+list = {1 2 3}
+map = #{'a' 1 'b' 2}
+map2 = #{'a' 1, 'b' 2, 'c' 3}
+set = #(1 2 3)
+
+```
+
+#### Nullability
+```Scala
+x::Int? = null
+q = x unpackOrPANIC
+// do something if its not null
+x unpack: [it echo]
+// same but expression with backup value
+w = x unpack: [it inc] or: -1
+// just unpack or backup value
+e = x unpackOrValue: -1
+```
+
+#### Handling the error
+```Scala
+x = file read orPANIC
+x = file read orValue: "no file"
+```
+Look for more in [Error handling](https://gavr123456789.github.io/niva-site/error-handling.html)
+
+## Misc
+
+
+
+#### Local arg names
+```Scala
+Int from: x::Int to: y::Int = this + x + y
+```
+
+#### Syntax sugar for this
+```Scala
+Person foo = [
+    .bar
+    this bar // same thign
+]
+```
+
+#### Compile time reflection
+```Scala
+Foo bar::Int baz::String = [
+    // getting string representation from call side
+    a = Compiler getName: 0
+    b = Compiler getName: 1
+    c = Compiler getName: 2
+    a echo
+    b echo
+    c echo
+]
+```
\ No newline at end of file

From fb6fb274ec8e5e2b2b849367d18c5116aa2872c9 Mon Sep 17 00:00:00 2001
From: gavr123456789 <gavr123456789@gmail.com>
Date: Wed, 12 Mar 2025 04:15:12 +0200
Subject: [PATCH 2/9] Add messages section

---
 niva.md | 85 ++++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 63 insertions(+), 22 deletions(-)

diff --git a/niva.md b/niva.md
index e09311ba..9b16039c 100644
--- a/niva.md
+++ b/niva.md
@@ -6,9 +6,12 @@ contributors:
 ---
 
 ## Intro
-Niva is a simple language that takes a lot of inspiration from Smalltalk. But leaning towards the functional side. Everything is still an object but instead of classes, interfaces, and abstract classes, we have tagged unions, which is the only way to achieve polymorphism.
+Niva is a simple language that takes a lot of inspiration from Smalltalk.
+But leaning towards the functional side.
+Everything is still an object, but instead of classes, interfaces, and abstract classes, we have tagged unions,
+which is the only way to achieve polymorphism.
 
-So basically niva is types, unions and methods for them. 
+So basically niva is types, unions, and methods for them. There are no functions.
 
 On an imaginary graph of complexity, I would put it here:
 Go < Niva < Java < Kotlin < Scala
@@ -23,7 +26,7 @@ Links:
 
 #### Variable
 Variables are immutable by default.
-There is no keyword for declarating a variable.
+There is no keyword for declaring a variable.
 
 ```Scala
 // this is a comment
@@ -33,7 +36,7 @@ boolean = true
 char = 'a'
 float = 3.14f
 double = 3.14
-mutltilineStr = """
+mutltiLineStr = """
 qwf ars zxc \n \t "qwf"
 """
 explicit_type::Int = 5
@@ -42,17 +45,56 @@ mut x = 5
 x <- 6 // mutate
 ```
 
-
-#### Type
-
+#### Messages
 ```Scala
-type Square side: Int
-type Person
-    name: String
-    age: Int
+// hello world is one liner
+"Hello world" echo // echo is a message for String obj
+
+
+// There are 3 types of messages
+1 inc // 2         unary 
+1 + 2 // 3         binary
+"abc" at: 0 // 'a' keyword
+
+
+// they can be chained
+1 inc inc inc dec // 3
+1 + 1 + 2 - 3 // 1
+1 to: 3 do: [it echo] // 1 2 3
+// the last one here to:do: is a single message
+// to chain 2 keyword message you need comma `,`
+"123456" drop: 1, dropLast: 2 // "234" 
+
+// or mixed
+1 inc + 3 dec - "abc" count // 2 + 2 - 3 -> 1
+"123" + "456" drop: 1 + 1   // "123456" drop: 2 -> "3456"
+
+// everything except type and msg declarations are message sends in niva
+// for example `if` is a message for Boolean object that takes lambda
+1 > 2 ifTrue: ["wow" echo]
+// expression
+base = 1 > 2 ifTrue: ["heh"] ifFalse: ["qwf"]
+// same for while
+mut q = 0
+[q > 10] whileTrue: [q <- q inc]
+// all of this is zero cost because of inlining at compile time
 ```
 
+#### Type
+New lines are not significant in niva  
+Type declaration looks like keyword message for type
+```Scala
+type Square side: Int
+
+type Person
+  name: String
+  age: Int
+```
+
+
+
 #### Create instance
+Object creation is just a keyword message with all fields
 ```Scala
 square = Square side: 42
 alice = Person name: "Alice" age: 24
@@ -62,9 +104,9 @@ alice = Person name: "Alice" age: 24
 ```
 
 #### Access fields
-Getting fields is the same as sending message with its name to object 
+Getting fields is the same as sending a unary message with its name to the object 
 ```Scala
-// get age, add 1 to it and print
+// get age, add 1 and print it
 alice age inc echo // 25
 ```
 
@@ -105,7 +147,6 @@ p2 = Point atStart
 // constructor is just a usual message, so it can have params
 constructor Point y::Int = Point x: 0 y: y
 p3 = Point y: 20 // x: 0 y: 20
-
 ```
 
 
@@ -159,15 +200,15 @@ y echo // 2
 
 ```Scala
 union Shape =
-    | Rectangle width: Int height: Int
-    | Circle    radius: Int
+  | Rectangle width: Int height: Int
+  | Circle    radius: Int
     
 constructor Float pi = 3.14
 
 // match on this(Shape)
 Shape getArea -> Float = | this 
-    | Rectangle => width * height |> toFloat
-    | Circle => Float pi * radius * radius
+  | Rectangle => width * height |> toFloat
+  | Circle => Float pi * radius * radius
     
 // its exhaustive, so when u add new branch 
 // all the matches will become errors until all cases processed
@@ -197,15 +238,14 @@ e = x unpackOrValue: -1
 
 #### Handling the error
 ```Scala
+// exit the program with stack trace
 x = file read orPANIC
 x = file read orValue: "no file"
 ```
-Look for more in [Error handling](https://gavr123456789.github.io/niva-site/error-handling.html)
+Errors works like effects, look for more in [Error handling](https://gavr123456789.github.io/niva-site/error-handling.html)
 
 ## Misc
 
-
-
 #### Local arg names
 ```Scala
 Int from: x::Int to: y::Int = this + x + y
@@ -215,11 +255,12 @@ Int from: x::Int to: y::Int = this + x + y
 ```Scala
 Person foo = [
     .bar
-    this bar // same thign
+    this bar // same thing
 ]
 ```
 
 #### Compile time reflection
+You can get string representation of any argument from call site.
 ```Scala
 Foo bar::Int baz::String = [
     // getting string representation from call side

From 6cd883c3c2d17898540055e9c1ba5c9aa843afb4 Mon Sep 17 00:00:00 2001
From: gavr123456789 <gavr123456789@gmail.com>
Date: Wed, 12 Mar 2025 04:33:30 +0200
Subject: [PATCH 3/9] some fixes

---
 niva.md | 54 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 41 insertions(+), 13 deletions(-)

diff --git a/niva.md b/niva.md
index 9b16039c..a43a3a15 100644
--- a/niva.md
+++ b/niva.md
@@ -41,6 +41,11 @@ qwf ars zxc \n \t "qwf"
 """
 explicit_type::Int = 5
 
+
+list = {1 2 3}  
+set = #(1 2 3) 
+map = #{1 'a' 2 'b'} 
+
 mut x = 5
 x <- 6 // mutate
 ```
@@ -82,7 +87,7 @@ mut q = 0
 
 #### Type
 New lines are not significant in niva  
-Type declaration looks like keyword message for type
+Type declaration looks like a keyword message for type
 ```Scala
 type Square side: Int
 
@@ -112,7 +117,7 @@ alice age inc echo // 25
 
 #### Method for type:  
 Everything is an object, just like in Smalltalk, so everything can have a method declared.   
-Here, we add a `double` method to `Int` and then use it inside the `perimeter` method of `Square`.
+Here, we add a `double` method to `Int` and then use it inside the `perimeter` method of `Square`.  
 
 ```Scala
 Int double = this + this
@@ -120,18 +125,29 @@ Square perimeter = side double
 
 square = Square side: 42
 square perimeter // call
+
+
+// explicit return type
+Int double2 -> Int = this * 2
+
+// with body
+Int double3 -> Int = [
+    result = this * 2
+    ^ result // ^ is return
+]
 ```
 
 
-#### Messages with many args
+#### Keyword message declaration
 ```Scala
 type Range from: Int to: Int
+// keyword message with one arg `to`
 Int to::Int = Range from: this to: to
 
 1 to: 2 // Range
 ```
 #### Type constructor
-Its like a message for type itself instead of instance
+It's like a message for type itself instead of instance
 ```Scala
 constructor Float pi = 3.14
 x = Float pi // 3.14
@@ -151,16 +167,10 @@ p3 = Point y: 20 // x: 0 y: 20
 
 
 #### Conditions
-=> is syntax sugar for ifTrue message, since conditions is pretty common
+=> is syntax sugar for ifTrue message, since conditions are pretty common
 ```Scala
-// syntax sugar
-1 < 2 => "yay" echo
-// everything is message send(this is free because of lambda-inlining)
 1 < 2 ifTrue: ["yay" echo]
 
-// with else branch
-1 > 2 => "yay" echo |=> "oh no" echo
-
 1 > 2 ifTrue: ["yay" echo] ifFalse: ["oh no" echo]
 ```
 
@@ -196,9 +206,12 @@ y = | "b"
 y echo // 2
 ```
 
-#### Unions
+#### Tagged unions
 
 ```Scala
+union Color = Red | Blue | Green
+
+// branches can have fields
 union Shape =
   | Rectangle width: Int height: Int
   | Circle    radius: Int
@@ -217,21 +230,36 @@ Shape getArea -> Float = | this
 #### Collections 
 ```Scala
 // commas are optional
-list = {1 2 3}
+list = {1 2 3} 
 map = #{'a' 1 'b' 2}
 map2 = #{'a' 1, 'b' 2, 'c' 3}
 set = #(1 2 3)
 
+// default actions
+{1 2 3 4 5} 
+  map: [it inc], 
+  filter: [it % 2 == 0],
+  forEach: [it echo] // 2 4 6
+
+// iteration on map
+map forEach: [key, value -> 
+  key echo 
+  value echo
+]
 ```
 
 #### Nullability
+Same as in Kotlin or Swift
 ```Scala
 x::Int? = null
 q = x unpackOrPANIC
+
 // do something if its not null
 x unpack: [it echo]
+
 // same but expression with backup value
 w = x unpack: [it inc] or: -1
+
 // just unpack or backup value
 e = x unpackOrValue: -1
 ```

From b510eb9a10752acc130f2c72f762fa0a6eac7560 Mon Sep 17 00:00:00 2001
From: gavr123456789 <gavr123456789@gmail.com>
Date: Mon, 17 Mar 2025 03:56:12 +0200
Subject: [PATCH 4/9] add install instructions

---
 niva.md | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/niva.md b/niva.md
index a43a3a15..2a70593c 100644
--- a/niva.md
+++ b/niva.md
@@ -1,6 +1,6 @@
 ---
 name: niva
-filename: learnniva.niva
+filename: main.niva
 contributors:
     - ["gavr", "https://github.com/gavr123456789"]
 ---
@@ -22,6 +22,14 @@ Links:
 - [LSP](https://github.com/gavr123456789/vaLSe)
 - [VSC plugin](https://github.com/gavr123456789/niva-vscode-bundle)
 
+Install:
+```bash
+git clone https://github.com/gavr123456789/Niva.git
+cd Niva
+./gradlew buildJvmNiva
+# LSP here https://github.com/gavr123456789/niva-vscode-bundle
+```
+
 ## The Basics
 
 #### Variable
@@ -175,8 +183,9 @@ p3 = Point y: 20 // x: 0 y: 20
 ```
 
 #### Cycles
-There is no special syntax for cycles, its just keyword messages that takes codeblocs as parameters.  
-(its zero cost thanks for inlining)
+There is no special syntax for cycles.
+It's just keyword messages that take codeblocks as parameters.  
+(it's zero cost thanks for inlining)
 ```Scala
 {1 2 3} forEach: [ it echo ]
 1..10 forEach: [ it echo ]
@@ -270,7 +279,7 @@ e = x unpackOrValue: -1
 x = file read orPANIC
 x = file read orValue: "no file"
 ```
-Errors works like effects, look for more in [Error handling](https://gavr123456789.github.io/niva-site/error-handling.html)
+Errors work like effects, look for more in [Error handling](https://gavr123456789.github.io/niva-site/error-handling.html)
 
 ## Misc
 
@@ -288,7 +297,7 @@ Person foo = [
 ```
 
 #### Compile time reflection
-You can get string representation of any argument from call site.
+You can get string representation of any argument from a call site.
 ```Scala
 Foo bar::Int baz::String = [
     // getting string representation from call side

From d95333b1792919df9440ca511adc079711fc1eeb Mon Sep 17 00:00:00 2001
From: gavr123456789 <gavr123456789@gmail.com>
Date: Mon, 17 Mar 2025 04:14:34 +0200
Subject: [PATCH 5/9] add install instructions

---
 niva.md | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/niva.md b/niva.md
index 2a70593c..6b946bc3 100644
--- a/niva.md
+++ b/niva.md
@@ -6,16 +6,24 @@ contributors:
 ---
 
 ## Intro
-Niva is a simple language that takes a lot of inspiration from Smalltalk.
-But leaning towards the functional side.
-Everything is still an object, but instead of classes, interfaces, and abstract classes, we have tagged unions,
-which is the only way to achieve polymorphism.
+Niva is a simple language that takes a lot of inspiration from Smalltalk.  
+But leaning towards the functional side and static typed.
+Everything is still an object, but instead of classes, interfaces, inheritance, and abstract classes,  
+we have tagged unions, which is the only way to achieve polymorphism.
 
-So basically niva is types, unions, and methods for them. There are no functions.
 
-On an imaginary graph of complexity, I would put it here:
-Go < Niva < Java < Kotlin < Scala
+For example, everything except the declaration is sending messages to objects.  
+`1 + 2` is not a + operator, but a `... + Int` message for `Int` object.
+(ofc there are no extra costs for that)   
 
+C-like: `1.inc()`  
+Niva: `1 inc`  
+
+So basically niva is types, unions, and methods for them. 
+There are no functions.  
+On an imaginary graph of complexity, I would put it here:  
+Go < Niva < Java < Kotlin < Scala  
+  
 Links:
 - [Site](https://gavr123456789.github.io/niva-site/reference.html)
 - [GitHub](https://github.com/gavr123456789/Niva)
@@ -34,7 +42,7 @@ cd Niva
 
 #### Variable
 Variables are immutable by default.
-There is no keyword for declaring a variable.
+There is no special keyword for declaring a variable.
 
 ```Scala
 // this is a comment

From f1771a143505c618f06dc8dd2e8b2de289261df5 Mon Sep 17 00:00:00 2001
From: gavr123456789 <gavr123456789@gmail.com>
Date: Mon, 17 Mar 2025 14:53:59 +0200
Subject: [PATCH 6/9] review

---
 niva.md | 96 ++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 58 insertions(+), 38 deletions(-)

diff --git a/niva.md b/niva.md
index 6b946bc3..dbccf035 100644
--- a/niva.md
+++ b/niva.md
@@ -14,21 +14,14 @@ we have tagged unions, which is the only way to achieve polymorphism.
 
 For example, everything except the declaration is sending messages to objects.  
 `1 + 2` is not a + operator, but a `... + Int` message for `Int` object.
-(ofc there are no extra costs for that)   
+(there are no extra costs for that)   
 
 C-like: `1.inc()`  
 Niva: `1 inc`  
 
-So basically niva is types, unions, and methods for them. 
-There are no functions.  
-On an imaginary graph of complexity, I would put it here:  
-Go < Niva < Java < Kotlin < Scala  
-  
-Links:
-- [Site](https://gavr123456789.github.io/niva-site/reference.html)
-- [GitHub](https://github.com/gavr123456789/Niva)
-- [LSP](https://github.com/gavr123456789/vaLSe)
-- [VSC plugin](https://github.com/gavr123456789/niva-vscode-bundle)
+In essence, niva is highly minimalistic, like its ancestor Smalltalk.  
+It introduces types, unions, and associated methods. 
+There are no functions.
 
 Install:
 ```bash
@@ -68,7 +61,7 @@ x <- 6 // mutate
 
 #### Messages
 ```Scala
-// hello world is one liner
+// hello world is a one liner
 "Hello world" echo // echo is a message for String obj
 
 
@@ -83,15 +76,17 @@ x <- 6 // mutate
 1 + 1 + 2 - 3 // 1
 1 to: 3 do: [it echo] // 1 2 3
 // the last one here to:do: is a single message
-// to chain 2 keyword message you need comma `,`
+// to chain 2 keyword messages you need to wrap it in parentheses
+("123456" drop: 1) dropLast: 2 // "234" 
+the comma `,` is syntactic sugar for the same effect
 "123456" drop: 1, dropLast: 2 // "234" 
 
-// or mixed
+// you can mix them
 1 inc + 3 dec - "abc" count // 2 + 2 - 3 -> 1
 "123" + "456" drop: 1 + 1   // "123456" drop: 2 -> "3456"
 
-// everything except type and msg declarations are message sends in niva
-// for example `if` is a message for Boolean object that takes lambda
+// everything except type and message declarations are message sends in niva
+// for example `if` is a message for Boolean object that takes a lambda
 1 > 2 ifTrue: ["wow" echo]
 // expression
 base = 1 > 2 ifTrue: ["heh"] ifFalse: ["qwf"]
@@ -103,7 +98,7 @@ mut q = 0
 
 #### Type
 New lines are not significant in niva  
-Type declaration looks like a keyword message for type
+Type declarations look like keyword messages consisting of fields and types
 ```Scala
 type Square side: Int
 
@@ -112,10 +107,8 @@ type Person
   age: Int
 ```
 
-
-
 #### Create instance
-Object creation is just a keyword message with all fields
+Creating an object is the same keyword message as when declaring it, but with values in place of types.
 ```Scala
 square = Square side: 42
 alice = Person name: "Alice" age: 24
@@ -163,7 +156,7 @@ Int to::Int = Range from: this to: to
 1 to: 2 // Range
 ```
 #### Type constructor
-It's like a message for type itself instead of instance
+A type constructor functions as a message for the type itself rather than to a specific instance.
 ```Scala
 constructor Float pi = 3.14
 x = Float pi // 3.14
@@ -183,25 +176,38 @@ p3 = Point y: 20 // x: 0 y: 20
 
 
 #### Conditions
-=> is syntax sugar for ifTrue message, since conditions are pretty common
+If, like everything else, is the usual sending of a message to a Boolean object.  
+It takes one or two lambda arguments. 
 ```Scala
+false ifTrue: ["yay" echo]
 1 < 2 ifTrue: ["yay" echo]
-
 1 > 2 ifTrue: ["yay" echo] ifFalse: ["oh no" echo]
+
+// `ifTrue:ifFalse:` message can be used as expression
+str = 42 % 2 == 0 
+    ifTrue: ["even"]
+    ifFalse: ["odd"]
+// str == "even"
 ```
 
 #### Cycles
-There is no special syntax for cycles.
+There is no special syntax for cycles.  
 It's just keyword messages that take codeblocks as parameters.  
 (it's zero cost thanks for inlining)
 ```Scala
-{1 2 3} forEach: [ it echo ]
+{1 2 3} forEach: [ it echo ] // 1 2 3
 1..10 forEach: [ it echo ]
 
 mut c = 10
 [c > 0] whileTrue: [ c <- c dec ]
+
+c <- 3 // reset c
+[c > 0] whileTrue: [ 
+    c <- c dec 
+    c echo // 3 2 1
+]
 ```
-`whileTrue` is a message for codeblock of type: 
+`whileTrue:` is a message for codeblock of the type: 
 `[ -> Boolean] whileTrue::[ -> Unit]`
 
 #### Matching
@@ -230,18 +236,24 @@ union Color = Red | Blue | Green
 
 // branches can have fields
 union Shape =
-  | Rectangle width: Int height: Int
-  | Circle    radius: Int
+    | Rectangle width: Int height: Int
+    | Circle    radius: Double
     
-constructor Float pi = 3.14
+constructor Double pi = 3.14
+Double square = this * this
 
 // match on this(Shape)
-Shape getArea -> Float = | this 
-  | Rectangle => width * height |> toFloat
-  | Circle => Float pi * radius * radius
+Shape getArea -> Double = 
+    | this 
+    | Rectangle => width * height, toDouble
+    | Circle => Double pi * radius square
     
-// its exhaustive, so when u add new branch 
+// There is exhaustiveness checking, so when you add a new branch 
 // all the matches will become errors until all cases processed
+
+Shape getArea -> Double = | this 
+    | Rectangle => width * height, toDouble 
+// ERROR: Not all possible variants have been checked (Circle)
 ```
 
 #### Collections 
@@ -252,7 +264,7 @@ map = #{'a' 1 'b' 2}
 map2 = #{'a' 1, 'b' 2, 'c' 3}
 set = #(1 2 3)
 
-// default actions
+// common collection operations
 {1 2 3 4 5} 
   map: [it inc], 
   filter: [it % 2 == 0],
@@ -266,15 +278,17 @@ map forEach: [key, value ->
 ```
 
 #### Nullability
-Same as in Kotlin or Swift
+By default, variables cannot be assigned a null value.  
+To allow this, nullable types are used, indicated by a question mark at the end of the type.  
+You may already be familiar with this concept from TypeScript, Kotlin, or Swift.
 ```Scala
 x::Int? = null
 q = x unpackOrPANIC
 
-// do something if its not null
+// do something if it's not null
 x unpack: [it echo]
 
-// same but expression with backup value
+// same but provide a backup value
 w = x unpack: [it inc] or: -1
 
 // just unpack or backup value
@@ -316,4 +330,10 @@ Foo bar::Int baz::String = [
     b echo
     c echo
 ]
-```
\ No newline at end of file
+```
+
+Links:
+- [Site](https://gavr123456789.github.io/niva-site/reference.html)
+- [GitHub](https://github.com/gavr123456789/Niva)
+- [LSP](https://github.com/gavr123456789/vaLSe)
+- [VSC plugin](https://github.com/gavr123456789/niva-vscode-bundle)
\ No newline at end of file

From bd0a4b6a510720f21357dbc374f9d8ecdf413326 Mon Sep 17 00:00:00 2001
From: gavr123456789 <gavr123456789@gmail.com>
Date: Mon, 17 Mar 2025 14:55:58 +0200
Subject: [PATCH 7/9] mut keyword explanation

---
 niva.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/niva.md b/niva.md
index dbccf035..13b1a4c7 100644
--- a/niva.md
+++ b/niva.md
@@ -55,6 +55,7 @@ list = {1 2 3}
 set = #(1 2 3) 
 map = #{1 'a' 2 'b'} 
 
+// declare a mutable variable
 mut x = 5
 x <- 6 // mutate
 ```

From dadefd1bddf12c13187ffc17fbf3d3f175624ec8 Mon Sep 17 00:00:00 2001
From: gavr123456789 <gavr123456789@gmail.com>
Date: Mon, 17 Mar 2025 15:38:07 +0200
Subject: [PATCH 8/9] MD047 File should end with a single newline character

---
 niva.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/niva.md b/niva.md
index 13b1a4c7..b7a00925 100644
--- a/niva.md
+++ b/niva.md
@@ -337,4 +337,4 @@ Links:
 - [Site](https://gavr123456789.github.io/niva-site/reference.html)
 - [GitHub](https://github.com/gavr123456789/Niva)
 - [LSP](https://github.com/gavr123456789/vaLSe)
-- [VSC plugin](https://github.com/gavr123456789/niva-vscode-bundle)
\ No newline at end of file
+- [VSC plugin](https://github.com/gavr123456789/niva-vscode-bundle)

From ec44661babdd07751975925864a7fc12d046f270 Mon Sep 17 00:00:00 2001
From: gavr <30507409+gavr123456789@users.noreply.github.com>
Date: Mon, 17 Mar 2025 17:22:35 +0200
Subject: [PATCH 9/9] ~~codeblock~~ lambda

---
 niva.md | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/niva.md b/niva.md
index b7a00925..1dec18ec 100644
--- a/niva.md
+++ b/niva.md
@@ -208,7 +208,7 @@ c <- 3 // reset c
     c echo // 3 2 1
 ]
 ```
-`whileTrue:` is a message for codeblock of the type: 
+`whileTrue:` is a message for lambda object of the type: 
 `[ -> Boolean] whileTrue::[ -> Unit]`
 
 #### Matching
@@ -322,15 +322,21 @@ Person foo = [
 #### Compile time reflection
 You can get string representation of any argument from a call site.
 ```Scala
-Foo bar::Int baz::String = [
+Int bar::Int baz::String = [
     // getting string representation from call side
     a = Compiler getName: 0
     b = Compiler getName: 1
     c = Compiler getName: 2
-    a echo
-    b echo
-    c echo
+    a echo // 1 + 1
+    b echo // variable
+    c echo // "str"
 ]
+
+variable = 42
+// call side
+1 + 1 
+    bar: variable 
+    baz: "str"
 ```
 
 Links: