Add doc.

CHANGES.md

@@ -18,6 +18,8 @@ New:
   - `file.replaygain` to compute the replaygain of a file
 - Added support for ImageLib to decode images.
 - Added support for completion in emacs based on company (#2652).
+- Added syntactic sugar for record spread: `let {foo, gni, ..y} = x`
+  and `y = { foo = 123, gni = "aabb", ...x}` (#2737)
 
 Changed:
 

doc/content/language.md

@@ -879,6 +879,24 @@ the duration with
 print("The duration of the song is #{song.duration} seconds")
 ```
 
+Records can be re-used using _spreads_:
+
+```liquidsoap
+song = { filename = "song.mp3", duration = 257., bpm = 132. }
+
+# This is a fresh value with all the fields from `song` and
+# a new `id` field:
+song_with_id = { id = 1234, ...song }
+```
+
+Alternatively, you can also add method with the explicit `v.{...}` syntax:
+
+```liquidsoap
+song = { filename = "song.mp3", duration = 257., bpm = 132. }
+
+song_with_id = song.{id = 1234}
+```
+
 ### Modules
 
 Records are heavily used in Liquidsoap in order to structure the functions of
@@ -1072,6 +1090,10 @@ Here are some examples:
 let {foo, bar} = {foo = 123, bar = "baz", gni = true}
 # foo = 123, bar = "baz"
 
+# Record capture with spread
+let {foo, bar, ...x} = {foo = 123, bar = "baz", gni = true}
+# foo = 123, bar = "baz", x = {gni = true}
+
 # Module capture
 let v.{foo, bar} = "aabbcc".{foo = 123, bar = "baz", gni = true}
 # v = "aabbcc", foo = 123, bar = "baz"