From 6b57e4edb952baffa376885d8d08276a6e9fa5e7 Mon Sep 17 00:00:00 2001
From: Evgeny Metelkin <evgeny.metelkin@gmail.com>
Date: Tue, 9 Jul 2024 11:25:36 +0300
Subject: [PATCH] null values

---
 README.md |  1 +
 null.md   | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 syntax.md |  9 ++++--
 3 files changed, 90 insertions(+), 3 deletions(-)
 create mode 100644 null.md

diff --git a/README.md b/README.md
index da0a309..3ce8604 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,7 @@ See also the [Heta video tutorial](https://hetalang.github.io/#/resources/?id=le
 - [Modules](https://hetalang.github.io/#/specifications/modules)
 - [Namespaces](https://hetalang.github.io/#/specifications/namespaces)
 - [Math expressions](https://hetalang.github.io/#/specifications/math)
+- [Null values](https://hetalang.github.io/#/specifications/null)
 - [Units](https://hetalang.github.io/#/specifications/units)
 - [Tabular format](https://hetalang.github.io/#/specifications/tabular-format)
 - [Cases](https://hetalang.github.io/#/specifications/cases)
diff --git a/null.md b/null.md
new file mode 100644
index 0000000..e221c82
--- /dev/null
+++ b/null.md
@@ -0,0 +1,83 @@
+# Null values
+
+Null values are special property values that represent the absence of a value. They are used to indicate that a property is intentionally empty or missing.
+
+null values cannot be used as a ID of components because it is reserved word. 
+
+Setting a property to `null` works differently for different statements.
+
+## null in #insert and #update
+
+When we set a property to `null` in the `#insert` or `#forceInsert` statements, it means that the property is intentionally empty,missing, or has the default value. It is the same as we do not declare the property at all.
+
+```heta
+k1 @Const {units: null} = 1; // implicit #insert
+```
+
+works the same as
+
+```heta
+k1 @Const = 1;
+```
+
+When we set a property to `null` in the `#update` statement, it means that the property is intentionally removed.
+
+```heta
+k1 @Const {units: mM};
+k1 {units: null} = 1; // implicit #update
+```
+
+which is equivalent to
+
+```heta
+k1 @Const = 1;
+```
+
+## wrong usage of null
+
+Null properties are allowed only in properties but not in sub-properties like in examples below.
+
+```heta
+x1 @Record {
+    aux: {a: 1, b: null} // throw syntax error
+}; 
+```
+
+```heta
+x1 @Record {
+    aux: null // correct
+}; 
+```
+
+```heta
+x1 @Record {
+    tags: [a, b, null] // throw syntax error
+}; 
+```
+
+```heta
+x1 @Record {
+    tags: null // correct
+}; 
+```
+
+Null properties values must be used only for components, but not for `#defineFunction` or `#defineUnit`.
+
+```heta
+#defineFunction f1 {
+    arguments: [x,y,z],
+    math: null          // throw syntax error
+};
+```
+
+```heta
+#defineUnit u1 {
+    units: null          // throw syntax error
+};
+```
+
+Null value cannot be used as a ID of components.
+
+```heta
+null @Const = 1; // throw syntax error
+```
diff --git a/syntax.md b/syntax.md
index 8e22a0b..083a26e 100644
--- a/syntax.md
+++ b/syntax.md
@@ -24,14 +24,14 @@ The Heta code represents a sequence of statements that create and modify element
     - Assignments (with several subtypes)
 
 ## Plain Format of Action Statement
-1. The plain format is the most flexible way to describe action properties. It begins with the `{` symbol and ends with the `}` symbol, and it can contain a set of key-value pairs divided by commas (`,`), similar to a dictionary in JSON or YAML format.
+1. The plain format is the most straightforward way to describe action properties. It begins with the `{` symbol and ends with the `}` symbol, and it can contain a set of key-value pairs divided by commas (`,`), similar to a dictionary in JSON or YAML format.
 
     Example:
     ```heta
     { prop1: value 1, prop2: value 2, ...};
     ```
 
-    The **property** is always a string without spaces. Properties must be unique within a dictionary. The **value** can be one of five types: \<String\>, \<Number\>, \<Boolean\>, \<Dictionary\>, or \<Array\>. \<Dictionary\> and \<Array\> values might include other types.
+    The **property** name is always a string without spaces, it must be unique within a dictionary. The **value** can be one of five types: \<String\>, \<Number\>, \<Boolean\>, \<Dictionary\>, \<Array\> or \<Null\>. \<Dictionary\> and \<Array\> values might include other types.
 
 
     Example:
@@ -41,7 +41,8 @@ The Heta code represents a sequence of statements that create and modify element
         numberProp: 1.2e-3,
         booleanProp: true,
         dictionaryProp: { nestedProp: true },
-        arrayProp: [1, 2, 3]
+        arrayProp: [1, 2, 3],
+        someProp: null
     };
     ```
 
@@ -112,6 +113,8 @@ The Heta code represents a sequence of statements that create and modify element
     };
     ```
 
+7. The \<Null\> value is used to describe the value which must be empty. See more detailes in [Null values](./null)
+
 ## Shortened Format of Action Statement
 
 1. To simplify code reading and writing, there are several types of statement parts that describe commonly used properties in a compact form. See the [Classes](./classes) description for details.