From c4796d56956cda5bb427bf23a28a40866396e481 Mon Sep 17 00:00:00 2001
From: Sander Spies <sandermail@gmail.com>
Date: Thu, 26 Mar 2020 17:53:46 +0100
Subject: [PATCH] Describe nested updates. Put record patches section in a
 pascaligo syntax block.

---
 .../docs/language-basics/maps-records.md      | 102 ++++++++++++++++++
 1 file changed, 102 insertions(+)

diff --git a/gitlab-pages/docs/language-basics/maps-records.md b/gitlab-pages/docs/language-basics/maps-records.md
index 837290d39..76dd2e7b9 100644
--- a/gitlab-pages/docs/language-basics/maps-records.md
+++ b/gitlab-pages/docs/language-basics/maps-records.md
@@ -230,6 +230,106 @@ xy_translate "({x:2,y:3,z:1}, {dx:3,dy:4})"
 You have to understand that `p` has not been changed by the functional
 update: a nameless new version of it has been created and returned.
 
+#### Nested updates
+
+A unique feature of LIGO is the ability to perform nested updates on records.
+
+For example if you have the following record structure:
+
+<Syntax syntax="pascaligo">
+
+```pascaligo
+type color is 
+| Blue 
+| Green
+
+type preferences is record [
+  color : color; 
+  other : int;
+]
+
+type account is record [
+  id : int; 
+  preferences : preferences;
+]
+```
+
+</Syntax>
+<Syntax syntax="cameligo">
+
+```cameligo
+type color = 
+  Blue 
+| Green
+
+type preferences = {
+  color : color;
+  other : int;
+}
+
+type account = {
+  id: int;
+  preferences: preferences;
+}
+```
+
+</Syntax>
+<Syntax syntax="reasonligo">
+
+```reasonligo
+type color = 
+  Blue 
+| Green;
+
+type preferences = {
+  color : color,
+  other : int
+}
+
+type account = {
+  id : int, 
+  preferences : preferences
+}
+```
+
+</Syntax>
+
+You can update the nested record with the following code:
+
+<Syntax syntax="pascaligo">
+
+```pascaligo
+
+function change_color_preference (const account : account; const color : color ) : account is 
+  block {
+      account := account with record [preferences.color = color] 
+  } with account
+  
+```
+
+</Syntax>
+<Syntax syntax="cameligo">
+
+```cameligo
+let change_color_preference (account : account) (color : color) : account = 
+  { account with preferences.color = color }
+```
+
+</Syntax>
+<Syntax syntax="reasonligo">
+
+```reasonligo
+let change_color_preference = (account : account, color : color): account => 
+  { ...account, preferences.color: color };
+```
+
+</Syntax>
+
+Note that all the records in the path will get updated. In this example that's
+`account` and `preferences`.
+
+<Syntax syntax="pascaligo">
+
 ### Record Patches
 
 Another way to understand what it means to update a record value is to
@@ -318,6 +418,8 @@ xy_translate "(record [x=2;y=3;z=1], record [dx=3;dy=4])"
 
 The hiding of a variable by another (here `p`) is called `shadowing`.
 
+</Syntax>
+
 ## Maps
 
 *Maps* are a data structure which associate values of the same type to